This is Macaulay2Doc.info, produced by Macaulay2, version 1.24.11

Macaulay2Doc -- Macaulay2 documentation
***************************************

Description
===========

image of nine planets

Macaulay2 is a software system devoted to supporting research in algebraic
geometry and commutative algebra, developed with funding from the National
Science Foundation. We are eager to help new users get started with it.

Authors
=======

  * Daniel R. Grayson (see http://www.math.uiuc.edu/~dan/ ) <dan@math.uiuc.edu>
  * Michael E. Stillman (see
    http://www.math.cornell.edu/People/Faculty/stillman.html )
    <mike@math.cornell.edu>

Version
=======

This documentation describes version 1.24.11 of Macaulay2.

For the programmer
==================

The object Macaulay2Doc, is a package.

Preface

For the New User

Mathematical Objects

Some Mathematical Computations

The Macaulay2 Language

Packages

Appendix

Reference material

Copyright and license
*********************

Macaulay2, its object code, source code, and documentation, are copyright by
Daniel R. Grayson and Michael E. Stillman.  We permit you to use it either
under the terms of the GNU General Public License, version 2, as published by
the Free Software Foundation, and as contained in the file COPYING-GPL-2,
accompanying the program, or under the terms of the GNU General
Public License, version 3, as published by the Free Software Foundation, and as
contained in the file COPYING-GPL-3, accompanying the
program.

Various packages are included with Macaulay2 and come with their own copyright
notices and licenses, see packages provided with Macaulay2.

Some free libraries have been compiled into (or linked with) Macaulay2, and
some free programs, or packages of programs, with their libraries, have been
compiled and distributed with Macaulay2.

Run the command copyright to view this message.

libraries

programs and their libraries

Singular-Factory
****************

With the kind permission of the authors of Singular, G.-M. Greuel, R. Stobbe,
G. Pfister, H. Schoenemann, and J. Schmidt, University of Kaiserslautern,
Macaulay2 incorporates Singular-Factory, version 4.3.2, a free library of
polynomial routines that provides for factorization of polynomials.  It is
available at ftp://www.mathematik.uni-kl.de/pub/Math/Singular/Factory and at
http://www.mathematik.uni-kl.de/ftp/pub/Math/Singular/SOURCES.  It is part of
Singular, whose home page is http://www.singular.uni-kl.de/.

The following important routines call upon it:
  * factor -- factor a ring element or a ZZ-module
  * gcd -- greatest common divisor
  * minimalPrimes (MinimalPrimes) -- minimal primes of an
    ideal
  * irreducibleCharacteristicSeries, --
    irreducible characteristic series of an ideal

frobby
******

Starting with version 1.2, Macaulay2 incorporates frobby, a free library of
routines for computing the Alexander dual of a monomial ideal (see
dual(MonomialIdeal), a method used internally by many
routines), written by Bjarke Hammersholt Roune, and available at
http://www.broune.com/frobby/.

GNU MP
******

The GNU MP library (GMP) provides routines for arbitrary precision integer and
floating point arithmetic. It is available at https://gmplib.org/ and
https://gmplib.org/. To see the version of the library your copy of Macaulay2
is linked with, examine the variable version.

MPFR
****

The MPFR library is used by Macaulay2 for its arbitrary precision real number
arithmetic and associated transcendental functions.  It is available at
http://www.mpfr.org/.  The library is remarkable for the care taken to return
correctly rounded results.  It is hoped that this will form a good base for
experimentation with algebraic algorithms that mix symbolic and numeric
techniques. It is licensed under the GNU Lesser General Public License, version
3 or later.

MPFI
****

The MPFI library is used by Macaulay2 for its arbitrary precision real interval
arithmetic and associated transcendental functions.  It is available at
https://gforge.inria.fr/projects/mpfi/.  The library is based on the
MPFR, library.  The library is remarkable for the care taken to return
correctly rounded results.  It is hoped that this will form a good base for
experimentation with algebraic algorithms that mix symbolic and numeric
techniques. It is licensed under the GNU Lesser General Public License, version
3 or later.

GC garbage collector
********************

Macaulay2 uses the excellent garbage collector GC, version 8.2.6, written by
Hans-J. Boehm and Alan J. Demers and generously licensed to the public.  It is
available at https://www.hboehm.info/gc/.

Some environment variables can be set by the user to tune garbage collector
performance:

  * GC_INITIAL_HEAP_SIZE -- initial heap size in bytes, or number of gigabytes
    followed by 'G', similarly for 'M', 'K'
  * GC_MAXIMUM_HEAP_SIZE -- optional maximum collected heap size
  * GC_FREE_SPACE_DIVISOR -- if set to a number D, then we try to make sure
    that we allocate at least N/D bytes between collections, where N is twice
    the number of traced bytes, plus the number of untraced bytes, plus a rough
    estimate of the root set size.  Increasing its value will use less space
    but more collection time.  Decreasing it will appreciably decrease
    collection time at the expense of space.
  * GC_PRINT_STATS -- whether to turn on logging
  * GC_PRINT_VERBOSE_STATS -- whether to turn on even more logging
  * GC_DUMP_REGULARLY -- whether to generate a debugging dump on startup and
    during every collection; very verbose
  * GC_NPROCS -- the number of processors to use (for Linux only)
  * GC_MARKERS -- the number of marker threads.  This is normally set to the
    number of processors.  It is safer to adjust GC_MARKERS than GC_NPROCS,
    since GC_MARKERS has no impact on the lock implementation

The full list is found in the source code for gc in the file
doc/README.environment.

Here are some error messages you may see from it when it aborts the program,
due to lack of memory or related problems.

  * Insufficient space for initial table allocation
  * No space for lwp data structures
  * Out of memory
  * Too many exclusions
  * Too many heap sections
  * Too many heap sections: Increase MAXHINCR or MAX_HEAP_SECTS
  * Too many root sets

You may simply be out of memory, and then the only recourse is to increase the
memory available to the program. However, if you don't have enough heap
sections, sometimes one can just start Macaulay2 by setting the
GC_INITIAL_HEAP_SIZE environment variable to some larger value with an
environment setting prefix on the M2 command line, e.g.,
GC_INITIAL_HEAP_SIZE=20G M2.

See also
========

  * collectGarbage -- collect the garbage in memory
  * GCstats -- information about the status of the garbage
    collector

LAPACK
******

The LAPACK library is used by Macaulay2 for its linear algebra routines.  It is
available at http://www.netlib.org/lapack/.

BLAS
****

The BLAS library is used by Macaulay2 for its linear algebra routines.  It is
available at http://www.netlib.org/blas/.

NTL library
***********

The NTL library, written by Victor Shoup, is used by Macaulay2, through the
Singular-Factory, library, for its algebraic routines.
It is available at http://shoup.net/ntl/ and is licensed under the GNU Lesser
General Public License, version 2 or later.

FLINT
*****

The library FLINT (Fast Library for Number Theory) is a library for
computations in number theory, consisting mainly of routines for integer and
polynomial arithmetic and linear algebra.  It was written by William Hart, Mike
Hansen, Sebastian Pancratz, Fredrik Johansson, and others, and is available at
http://flintlib.org/.

givaro
******

The library givaro is a library for arithmetic and algebraic computations, is
required for fflas-ffpack, and is available from
https://github.com/linbox-team/givaro.

fflas-ffpack
************

The library fflas-ffpack is a library for dense and sparse linear algebra over
a finite field or the ring of integers, available from
https://github.com/linbox-team/fflas-ffpack.

MPSolve -- a library for finding roots of univariate polynomials
****************************************************************

Starting with version 1.16, Macaulay2 incorporates the MPsolve (version 3)
package, available at https://numpi.dm.unipi.it/_media/software/mpsolve, and
originally developed by Dario Bini, Giuseppe Fiorentino, and Leonardo Robol.

This library is used by the roots, function, for
finding complex roots of a univariate polynomial

See also
========

  * roots(RingElement) -- compute the roots of a
    polynomial

Boost -- a collection of C++ source libraries
*********************************************

Boost (see https://www.boost.org/ ) is a collection of free peer-reviewed and
portable C++ libraries suitable for eventual standardization.

Macaulay2 incorporates the following Boost libraries:

Boost.Stacktrace (see https://www.boost.org/doc/libs/release/libs/stacktrace/ ) (since version 1.16)
----------------------------------------------------------------------------------------------------

  * used internally for printing stack traces

Boost.Regex (see https://www.boost.org/doc/libs/release/libs/regex/ ) (since version 1.17)
------------------------------------------------------------------------------------------

  * used by the regex, function, as well as other functions using
    regular expressions.

Note: the program normaliz, utilizes the Boost dynamic_bitset
class (see https://www.boost.org/doc/libs/release/libs/dynamic_bitset/ ).

4ti2
****

The package of programs 4ti2 is dedicated to algebraic, geometric and
combinatorial problems on linear spaces.  It is available at
http://www.4ti2.de/.  The package FourTiTwo, runs it.

gfan
****

The program gfan, written by Anders Jensen, computes Groebner fans. It is
available at http://www.math.tu-berlin.de/~jensen/software/gfan/gfan0.4plus.tar
.gz. The packages StatePolytope, and
gfanInterface, run it.

normaliz
********

The program normaliz, written by Winfried Bruns, Bogdan Ichim, and Christof
Soeger, provides computations in affine monoids, vector configurations, lattice
polytopes, and rational cones.  It is available at
http://www.mathematik.uni-osnabrueck.de/normaliz/.  The package Normaliz,
is an interface to it.

csdp
****

The program csdp, by Brian Borchers, solves semidefinite programming problems
and is available from http://www.coin-or.org/download/source/Csdp.

nauty
*****

The collection of programs called nauty, written by Brendan McKay, computes
automorphism groups of graphs and digraphs. It is available at
http://cs.anu.edu.au/~bdm/nauty.  The package Nauty, is an
interface to it.

It is distributed with the following copyright notice: Copyright (1984-2010)
Brendan McKay.  All rights reserved.  Permission is hereby given for use and/or
distribution with the exception of sale for profit or application with
nontrivial military significance.  You must not remove this copyright notice,
and you must document any changes that you make to this program.  This software
is subject to this copyright only, irrespective of any copyright attached to
any package of which this is a part. Absolutely no guarantees or warranties are
made concerning the suitability, correctness, or any other aspect of this
program.  Any use is at your own risk.

cdd+
****

The program cdd+, written by Komei Fukuda, is a C++ implementation of the
double description method of Motzkin, et al., for generating all vertices and
extreme rays of a general convex polyhedron in $\RR^d$ given by a system of
linear inequalities.  It is available at
http://www.ifor.math.ethz.ch/~fukuda/cdd_home/.

lrslib
******

The program lrslib, written by David Avis, provides the reverse search
algorithm for  vertex enumeration and convex hull problems. It is available at
http://www-cgrl.cs.mcgill.ca/~avis/C/lrs.html.

msolve -- a library for solving multivariate polynomial systems
***************************************************************

The program msolve, written by Jérémy Berthomieu, Christian Eder, Vincent
Neiger, and Mohab Safey El Din, uses advanced Groebner bases algorithms,
multi-threading, and vectorization to obtain exact solutions for multivariate
polynomial systems.  It is distributed under the GPLv2 license and is available
at https://msolve.lip6.fr/.  It is used by the package Msolve.

topcom
******

The program topcom, by Jörg Rambau, computes triangulations of point
configurations and oriented matroids, and is available from
http://www.rambau.wm.uni-bayreuth.de/TOPCOM/.

cohomCalg
*********

The program cohomCalg, by Ralph Blumenhagen, Benjamin Jurke, Thorsten Rahn, and
Helmut Roschy, computes cohomology of line bundles, and is available from
http://wwwth.mppmu.mpg.de/members/blumenha/cohomcalg/.

Acknowledgements
****************

We thank the National Science Foundation for generous funding since 1993 for
this project, Gert-Martin Greuel and Ruediger Stobbe for the incorporation of
their library Singular-Factory, and David Eisenbud,
Wolfram Decker and Sorin Popescu for early support, encouragement and
suggestions.  We also acknowledge an intellectual debt to Dave Bayer, who, with
Michael Stillman, wrote Macaulay, a specialized computer algebra system for
algebraic geometry and the predecessor of this program.

See also
========

  * authors of Macaulay2 packages

The authors
***********

To communicate with the authors about the program, use this email address:
<Macaulay2@math.uiuc.edu>.

See also
========

  * authors of Macaulay2 packages

The authors of Macaulay2:

Our co-author for the tutorials, long time supporter and user of Macaulay2, and collaborator on the project since 2007:

Daniel R. Grayson
*****************

Daniel R. Grayson (see http://www.math.uiuc.edu/~dan/ ) -- <dan@math.uiuc.edu>.

Daniel Grayson received his PhD in Mathematics from MIT in 1976, taught at
Columbia from 1976 to 1981, and became a faculty member at the University of
Illinois at Urbana-Champaign in 1981; he retired from the university in 2007.
His mathematical research concerns algebraic K-theory, which is on the
theoretical side, but he has always been intrigued by computers.  In 1986 he
joined Stephen Wolfram and six other co-authors to write Mathematica (see
http://www.wolfram.com/products/mathematica/ ), which in the years since its
introduction in 1988 has become the pre-eminent system for mathematics on the
computer.

picture of Grayson

Michael E. Stillman
*******************

Michael E. Stillman (see http://www.math.cornell.edu/~mike/ ) --
<mike@math.cornell.edu>.

Michael E. Stillman received his PhD in Mathematics from Harvard in 1983,
taught at University of Chicago 1983-85, was at Brandeis and then MIT 1985-87,
and then came to Cornell University.  His mathematical research concerns
computational algebraic geometry and algebraic geometry.  He started writing
syzygy programs as an undergraduate at the University of Illinois, and from
1983 to 1992 with Dave Bayer he wrote Macaulay, a specialized computer algebra
system for algebraic geometry and the predecessor of this program.

picture of Stillman

David Eisenbud
**************

David Eisenbud  (see http://www.msri.org/~de/ ) -- <de@msri.org>.

David Eisenbud received his PhD in mathematics in 1970 at the University of
Chicago under Saunders MacLane and Chris Robson, and was on the faculty at
Brandeis University before coming to Berkeley, where he has been Professor of
Mathematics since 1997. He has been a visiting professor at Harvard, Bonn, and
Paris. Eisenbud's mathematical interests range over commutative and
non-commutative algebra, algebraic geometry, topology, and computer methods.

Eisenbud served as Director of MSRI from 1997 to 2007. He was President of the
American Mathematical Society from 2003 to 2005. He is a Director of Math for
America, a foundation devoted to improving mathematics teaching. He has been a
member of the Board of Mathematical Sciences and their Applications of the
National Research Council, and is a member of the US National Committee of the
International Mathematical Union, which he will chair, starting in 2010. In
2006 Eisenbud was elected a Fellow of the American Academy of Arts and
Sciences. Eisenbud is Chair of the Editorial Board of the Algebra and Number
Theory journal, which he helped found in 2006, and serves on the editorial
boards of the Bulletin du Société Mathématique de France, Springer-Verlag's
book series Algorithms and Computation in Mathematics, and the Journal of
Software for Algebraic Geometry.

Eisenbud's interest in computation in the support of commutative algebra and
algebraic geometry begin in the early 1970's in the course of his work on free
resolutions with David Buchsbaum. An undergraduate named Ray Zibman programmed
Brandeis' PDP10 for to compute Gorenstein ideals of codimension 3, and this led
to the structure theorem for such ideals. After this success, Eisenbud was a
convert to the usefulness of computers in this field, and has been interested
in it ever since. His joint work with E. Graham Evans led Evans to suggest the
project of computing syzygies to his undergraduate student Mike Stillman...

picture of Eisenbud

Other sources of information about Macaulay2
********************************************

Web site
========

  * http://www.math.uiuc.edu/Macaulay2/ -- the main Macaulay2 web site:
    citations, binary distributions

Books
=====

  * Computations in algebraic geometry with Macaulay 2, Algorithms and
    Computations in Mathematics, no. 8, edited by David Eisenbud, Daniel R.
    Grayson, Michael E. Stillman, and Bernd Sturmfels, Springer-Verlag, 2001,
    ISBN 3-540-42230-7.
  * Computational Algebraic Geometry, London Mathematical Society Student Texts
    (No. 58), by Hal Schenck, ISBN-13: 9780521536509, ISBN-10: 0521536502,
    2003, 208 pages.

getting started
***************

To get a good idea of what you will be able to do with Macaulay2, see the
package BeginningMacaulay2.

Macaulay2 is available from our web page http://www.math.uiuc.edu/Macaulay2/.
There you will find online documentation, the source code, and precompiled
versions for MacOSX, Linux, Microsoft Windows, and for various unix boxes.

After you or your system administrator has installed Macaulay2, use the
information here to set up the emacs interface (the recommended way to run
Macaulay2), bookmark the html documentation, and to try to run Macaulay2.

checking your Macaulay2 installation -- and bookmarking the Macaulay2 documentation
***********************************************************************************

At a command prompt in a terminal window, type M2.  If Macaulay2 has been
installed correctly on your machine, you should see a prompt such as this:

    indigo% M2
    Macaulay2, version 1.0
    with packages: Classic, Elimination, LLLBases, PrimaryDecomposition,
                   SchurRings, TangentCone

    i1 :

If this is the first time that you are running Macaulay2, then Macaulay2
creates a directory called .Macaulay2 in your home directory (on unix
machines), or called Library/Application Support/Macaulay2 under MacOS X.
Inside this directory are several files of interest, including an index.html
file that contains links to your local copy of the Macaulay2 documentation.

The viewHelp, command in Macaulay2 starts up your web browser
(if it is not already running) and places you at this index.html page.

    viewHelp

This web page includes links to the main Macaulay2 documentation, as well as
documentation for any installed packages.   This is a good time to bookmark the
page in your browser.

At this point you should try something simple in Macaulay2, such as

    printWidth = 60
    R = QQ[a..d]
    (a+b+c+d)^4

 To exit Macaulay2, type one of: exit, end,
quit, or your end of file character (which, under Unix, is often
CONTROL-D).

    exit

Macaulay2 can be run in this way from the command line, but it is generally
much more convenient to run Macaulay2 from inside the emacs text editor.  This
is because you can more easily view larger objects, do command completion, use
cut and paste, search, save your session, and so on.  There is a nice mode for
running Macaulay2 inside emacs.

finding the Macaulay2 files
***************************

Often you will know where the Macaulay2 files are, because you have installed
them yourself.  But it can happen that Macaulay2 was installed by your system
administrator so you can run M2, but you don't know where its files are.  In
that case, there are a couple of ways to locate the files.

One way, under Unix, is to use the following shell command.
     type M2
The response will be of the following form.
     M2 is /foo/bar/bin/M2
The Macaulay2 files come in a directory tree that mimics the directory tree
found on unix systems in the directory /usr.  In particular, its top-level
directory has subdirectories called bin, info, lib, and share, so now we know,
from the output above, that the Macaulay 2 files have been installed with a
prefix /foo/bar as the name of its root directory.  It will follow, for
example, that the M2 emacs init file is located at
/foo/bar/share/emacs/site-lisp/Macaulay2/M2-init.el.

Another way to locate the files of Macaulay2 is to ask M2, assuming you can run
it.  Start M2 and type the following expression.
     prefixDirectory
The response will be of the following form, and will also tell you the prefix
for the paths to the Macaulay2 files.
     i1 : prefixDirectory

     o1 = /foo/bar/
If you are running M2 and emacs under cygwin on a Windows computer, then that
can prevent special difficulties: see finding your files under cygwin.

teaching M2 how to find its shared libraries
********************************************

Perhaps you know that your M2 executable is located at /foo/bar/bin/M2, say,
but when you run it, you get something like this:
    /foo/bar/bin/M2
    M2: error while loading shared libraries: liblapack.so: cannot open shared
-------------------------------------------------------------------------------
object file: No such file or directory
What that means is that M2 hasn't been told where its shared libraries are.
Actually, it's the operating system that has to be told, since otherwise M2
can't even start up.  Hopefully, the missing shared libraries are located in
/foo/bar/lib, and all we have to do is to tell the operating system by setting
the environment variable LD_LIBRARY_PATH, if you are running a Unix operating
system. If you have downloaded a version of Macaulay2 that comes with
dynamically loaded libraries of its own, they will be in the directory
/foo/bar/lib/Macaulay2/lib/lib/. After setting LD_LIBRARY_PATH temporarily you
may use setup, to record the correct value in your system start up
files.

Alternatively, you may be getting something like this:

    $ /foo/bar/bin/M2
    dyld: Library not loaded: /capybara/lib/libgmp.3.dylib
      Referenced from: /foo/bar/bin/M2
      Reason: image not found
    Trace/BPT trap
That would mean that you are running under Mac OS, and the suggestion above
would not apply.  On such systems, Macaulay2 must be installed in the system
application folder, or Macaulay2 will not be able to find its libraries.

teaching your shell how to find M2
**********************************

Perhaps you have typed M2 into a shell window and gotten something like the
following response:
     % M2
     bash: M2: command not found
If so, then you have to teach your shell how to find M2.

Your shell will look for M2 in the directories listed in the value of the PATH
environment variable.  You will want to arrange for that value to get set when
you log in or when you start your shell.  The former is preferable, because
environment variables are inherited by new processes only from their parents,
and your login shell is an ancestor of all of your processes.

If you teach your shell how to find M2, then emacs may be able to find M2,
also.

The simplest way to teach your shell how to find M2 is to let M2 do it for you.
Assume that you have found M2, and it is located at the path /foo/bar/bin/M2.
Run the command /foo/bar/bin/M2, and then, in response to Macaulay2's input
prompt, enter setup().  If that works, the next time you log in or start a new
shell, the shell should know how to find M2 (see setup).  If that
doesn't work, read onward.

Your goal is to add the directory containing M2 to the value of the PATH
environment variable. For this, you must know where the Macaulay2 files are:
see finding the Macaulay2 files.  Your
system administrator may have installed the Macaulay2 files under /usr, in
which case you will see M2 in /usr/bin, and you can ignore the rest of this
section.  The files may also be installed under /usr/local, in which case you
will see M2 in /usr/local/bin, and you can ignore the rest of this section,
provided you have /usr/local/bin on your PATH.  Or the files may be installed
somewhere else, such as in /Applications/Macaulay2, in which case you will see
M2 in /Applications/Macaulay2/bin, and you will want to add that directory to
your path now.

The method for setting environment variables depends on which shell you are
using.  Typical shells in use include ash, bash, csh, tcsh, ksh, sh, and zsh.
The command languages understood by these shells differ, but they fall into two
main classes: the Bourne shells sh, bash, ash, zsh, and ksh; and the C shells
csh and tcsh.

Bourne shells
=============

A Bourne shell reads commands from the file .profile in your home directory
when you log in, except perhaps under Mac OS X. The bash shell will also read
commands from .bashrc each subsequent time it starts up, after the initial log
in.  To add a directory called, say /foo/bar/bin, to your PATH, put this
command in your file .profile:
     export PATH=/foo/bar/bin:$PATH
It will be acted upon the next time you log in, or the following shell command
will run those commands in your current shell.
     source $HOME/.profile

C shells
========

A C shell reads commands from the file .login in your home directory when you
log in, except perhaps under Mac OS X. The shell will also read commands from
.cshrc or perhaps .tcshrc.  Check the man page of your shell.

To add a directory called, say /foo/bar/bin, to your PATH, put this command in
your file .login:
     setenv PATH /foo/bar/bin:$PATH
It will be acted upon the next time you log in, or the following shell command
will run those commands in your current shell.
     source $HOME/.profile

making a link to M2
===================

Another way to proceed that sometimes works is this.  Look at the output from
the shell command:
          printenv PATH
and see whether one of your own directories is already on the path. If so, say
it's ~/bin, then you can make a symbolic link from M2 to that directory, and it
will appear on your path.  First ensure the directory has been made with this
command:
      mkdir ~/bin
Ignore the error message if the directory already exists.  Then make the
symbolic link with this command:
          ln -s /Applications/Macaulay2/bin/M2 ~/bin/M2
After that your shell will be able to find M2, and M2 will be able to find its
files (because it knows about symbolic links).  (Don't use a hard link.)

what else to try
================

If you fail to teach your shell how to find M2, then all is not lost.  We
prefer to run M2 within emacs, and it is enough to teach emacs how find M2.
See teaching emacs how to find M2.

moving or copying the Macaulay2 files
*************************************

It is important, if you want to move or copy the Macaulay2 files, to move or
copy the entire directory tree, so their relative locations do not change.

When M2 starts up, it locates the files it needs (such as setup.m2), by first
locating M2 and then traversing the directory tree it expects to find M2 in.
If you copy or move just M2 (or M2.exe, under windows) to some other directory,
then that traversal will not be successful.

There are other ways to arrange for M2 to be on your PATH: with a symbolic
link, or by adding a directory name to the PATH; see teaching your shell how to
find M2.

running Macaulay2 in a terminal window
**************************************

Some answers in Macaulay2 can be very wide, but many of them will be wrapped
appropriately to fit in the width of a terminal window.  Macaulay2 can
successfully be used in a terminal window if care is taken not to display very
wide objects, but most users will prefer to use the interface provided with
emacs or with texmacs.

Macaulay2 uses the readline library and the history library to handle user
input in a terminal window.  The readline user interface documentation is
available at http://tiswww.case.edu/php/chet/readline/rluserman.html.  It can
also be read with the command info readline.  The history user interface
documentation is available at
http://tiswww.case.edu/php/chet/readline/history.html#SEC1. It can also be read
with the command info history.

Name completion is implemented.  Press the TAB key to automatically complete
names of identifiers that have been only partially typed, if possible.  Press
TAB a second time to get a list of the possible completions when multiple
choices exist.

using Macaulay2 with emacs
**************************

Emacs is a free text editor written by Richard Stallman, which can be used as
an ascii-oriented interface to Macaulay2. The best way to edit Macaulay2 code
or to run Macaulay2 is with emacs. Emacs is available as part of many operating
systems, as well as from http://www.gnu.org/software/emacs/.

setting up the Macaulay2 emacs interface
****************************************

If you are a newcomer to emacs, you should spend a few minutes going through
the emacs tutorial.  Start up emacs with the command emacs and then start up
the emacs tutorial with the keystrokes C-h t.  (The notation C-h indicates that
you should type Control-H, by holding down the control key, and pressing H.)
The emacs tutorial will introduce you to the basic keystrokes useful with
emacs.  After running through that you will want to examine the online emacs
manual that can be read with info mode; you may enter or re-enter that mode
with the keystrokes C-h i.

The Macaulay2 emacs interface consists of several files in the directory
share/emacs/site-lisp/Macaulay2/ in the Macaulay2 distribution tree.  If you're
lucky, then your system administrator has installed Macaulay2 so that directory
ends up in the same place where emacs looks for its files, as listed by the
emacs variable loadpath. If not, then in order for emacs to be able to find
these files, place the following lines in the .emacs file in your home
directory, creating the file if necessary.  Alternatively, and much simpler,
run M2, and let the setupEmacs, function do it for you.

    ;; .emacs file in your home directory
    (load "M2-init")

    ; comment out the following line with an initial semicolon
    ; if you want to use your f12 key for something else
    ; or change f12 to (for example) f8
    (global-set-key [ f12 ] 'M2)

After saving your .emacs file, try running emacs.  Start Macaulay2 by pressing
the f12 function key.  On MacOS X systems, f12 is usurped by either DashBoard,
SpotLight, or something else, so either you must change the f12 to some other
key, e.g., f8, in the .emacs file, or you should disable the systems use of the
f12 key.

If Macaulay2 doesn't start up (in a buffer named *M2*), check that you typed in
the above lines correctly into .emacs.  If they look okay, then see
teaching emacs how to find M2-init.el,
see teaching emacs how to find M2,
and teaching your shell how to find M2.

teaching emacs how to find M2-init.el
*************************************

Files containing emacs source code have names of the form *.el. Macaulay2 comes
with a file called M2-init.el that sets up emacs for running M2 conveniently.
It is important that emacs be able to find that file and the three other files
that come with it, by searching in the directories listed in the emacs variable
load-path.

If you are lucky, then the Macaulay2 directory tree has been installed with the
same root as the emacs directory tree.  For example, if emacs and Macaulay2 are
both installed in /usr, then M2-init.el is located at
/usr/share/emacs/site-lisp/Macaulay2/M2-init.el, and emacs already knows to
look in that directory for source files.

The simplest way to teach emacs how to find M2-init.el is to let M2 do it for
you.  Run M2, and then, in response to Macaulay2's input prompt, enter setup().
If that works, the next time you start emacs, it should know how to find
M2-init.el (see setup).  If that doesn't work, read onward.

To determine the precise path of the site-lisp directory emacs is looking in,
so that you can install Macaulay2 properly, use the emacs describe-variable
command, accessible with the key strokes C-h v, and ask for the description of
the variable load-path.

Let's assume that you have located the Macaulay2 source code, and that
M2-init.el is located at /foo/bar/share/emacs/site-lisp/Macaulay2/M2-init.el,
and that you want to tell emacs to search that directory, too. Insert the
following command into the file .emacs in your home directory.
(add-to-list 'load-path "/foo/bar/share/emacs/site-lisp/Macaulay2")
The next time you start emacs, emacs will look also in that directory for
files, and it should find M2-init.el.

teaching emacs how to find M2
*****************************

If you teach your shell how to find M2, then you do not have to teach emacs how
to find M2.  See teaching your shell how to find M2,
and come back to this section only if you fail with that.
Let's assume that you have found M2 (the program), and that is located in the
directory /foo/bar/bin, say.

Let's assume you have already set up the function key f12 to call M2.  That is
done with the following command in the .emacs file.
     (global-set-key [ f12 ] 'M2)
Then when you press f12, M2 should start running.

Here is what you will see on your screen in the minibuffer at the bottom of the
screen when you press f12 if emacs doesn't know how to find the file
M2-init.el.
     Symbol's function definition is void: M2
If you see that, you are not ready for this section: see teaching emacs how to find M2-init.el.

Here is what you will see on your screen in a buffer named *M2* if emacs knows
how to find the file M2-init.el but not how to find the program M2.

    + M2 --no-readline --print-width 189
    /bin/sh: M2: command not found

    Process M2 exited abnormally with code 127

teaching emacs temporarily
==========================

To teach emacs temporarily where to find M2, press
     C-u f12
(Recall that in emacs' notation for key-presses, C-u means to press u while
holding down the control key.)  You will get the M2 command line in the
minibuffer at the bottom of the screen, and you can edit it.  It will initially
look something like this:
     M2 --no-readline --print-width 189
You can change it to the right thing:
     /foo/bar/bin/M2 --no-readline --print-width 189
Then press enter and M2 should start running. That will stick for the rest of
your emacs session.  Later, to return to the *M2* window from another, or to
start up M2 again, just press f12.

teaching emacs permanently
==========================

Every time emacs starts up it reads commands from the file .emacs in your home
directory.  Put the following command in your .emacs file.
(setq M2-exe "/foo/bar/bin/M2")
The next time you start emacs it will know how to find M2.

running Macaulay2 in emacs
**************************

Because some answers can be very wide, it is a good idea to run Macaulay2 in a
window that does not wrap output lines and allows the user to scroll
horizontally to see the rest of the output.  We provide a package for
emacs, that implements this. It also provides for
dynamic completion of symbols in the language.

There is an ASCII version of this section of the documentation distributed in
the file share/emacs/site-lisp/macaulay2/M2-emacs-help.txt. It might be useful
for you to visit that file with emacs now, thereby avoiding having to cut and
paste bits of text into emacs buffers for the demonstrations below.

If you are a newcomer to emacs, start up emacs with the command emacs and then
start up the emacs tutorial with the keystrokes C-h t.  (The notation C-h
indicates that you should type Control-H, by holding down the control key, and
pressing H.)  The emacs tutorial will introduce you to the basic keystrokes
useful with emacs.  After running through that you will want to examine the
online emacs manual that can be read with info mode; you may enter or re-enter
that mode with the keystrokes C-h i. You may also want to purchase (or print
out) the emacs manual.  It is cheap, comprehensive and informative.  Once you
have spent an hour with the emacs tutorial and manual, come back and continue
from this point.

We assume you have taught emacs how to find Macaulay2's files, as described in
the previous sections, and that emacs is loading the file M2-init.el
successfully.  Loading that file will cause emacs to enter a special mode for
editing Macaulay2 code whenever a file whose name has the form *.m2 is
encountered.  It will also provide a special mode for running Macaulay2 in an
emacs buffer.  It sets the variable transient-mark-mode to have a different
value in each buffer, and sets hooks so that transient-mark-mode will be set to
t in M2 buffers.  The effect of this is that the mark is only active
occasionally, and then emacs functions that act on a region of text will refuse
to proceed unless the mark is active.  The set-mark function or the
exchange-point-and-mark function will activate the mark, and it will remain
active until some change occurs to the buffer.  The only reason we recommend
the use of this mode is so the same key can be used to evaluate a line or a
region of code, depending on whether the region is active.

Exit and restart emacs with your new initialization file. If you are reading
this file with emacs, then use the keystrokes C-x 2 to divide the buffer
containing this file into two windows. Then press the M-x M2 to start up
Macaulay2 in a buffer named *M2*.  (The command line used to start Macaulay2
may be edited before being run if you use a prefix argument with the above
command: press C-u just before.)

If this doesn't start up Macaulay2, one reason may be that your function keys
are not operable.  In that case press M-x M2 instead.  (The notation M-x is
emacs notation for pressing the x key while holding down the Meta or Alt key.)
If that doesn't work, please see teaching emacs how to find M2-init.el,
and teaching emacs how to find M2.

You may wish to bind the emacs function M2-send-to-program to a global
keystroke for ease of use; this is done automatically in Macaulay2 buffers.
For example, the following emacs code will bind it to the function key f11.

(global-set-key [ f11 ] 'M2-send-to-program)

You may use C-x o freely to switch from one window to the other. Verify that
Macaulay2 is running by entering a command such as 2+2. Now paste the following
text into a buffer, unless you have the ASCII version of this documentation in
an emacs buffer already, position the cursor on the first line of code, and
press the f11 function key repeatedly to present each line to Macaulay2.

i1 : R = ZZ/101[x,y,z]
     i2 : f = symmetricPower(2,vars R)
     i3 : M = cokernel f
     i4 : C = resolution M
     i5 : betti C

Notice that the input prompts are not submitted to Macaulay2.

Here is a way to conduct a demo of Macaulay2 in which the code to be submitted
is not visible on the screen.  Visit a file called foo.m2 and paste the
following text into it.

20!
     4 + 5 * 2^20
     -- that's all folks!

Press M-f11 with your cursor in this buffer to designate it as the source for
the Macaulay2 commands.  (The notation M-f11 means that while holding the Meta
key down, you should press the f11 function key.  The Meta key is the Alt key
on some keyboards, or it can be simulated by pressing Escape (just once) and
following that with the key you wanted to press while the meta key was held
down.)  Then position your cursor (and thus the emacs point) within the line
containing 20!.  Now press M-x M2-demo to open up a new frame called DEMO for
the *M2* window with a large font suitable for use with a projector, and with
your cursor in that frame, press f11 a few times to conduct the demo.  (If the
font or frame is the wrong size, you may have to create a copy of the file
M2.el with a version of the function M2-demo modified to fit your screen.)

One press of f11 brings the next line of code forward into the *M2* buffer, and
the next press executes it.  Use C-x 5 0 when you want the demo frame to go
away.

There is a way to send a region of text to Macaulay2: simply select a region of
text, making sure the mark is active (as described above) and press f11. Try
that on the list below; put it into an emacs buffer, move your cursor to the
start of the list, press M-C-@ or M-C-space to mark the list, and then press
f11 to send it to Macaulay2.  (The notation M-C-@ means: while holding down the
Meta key and the Control key press the @ key, for which you'll also need the
shift key.)

{a,b,c,d,e,f,
     g,h,i,j,k,l,
     m,n}

We have developed a system for incorporating Macaulay2 interactions into TeX
files.  Here is an example of how that looks.  Paste the following text into an
emacs buffer.

The answer, 4, is displayed after the output label ``{\tt o1\ =}''.
     Multiplication is indicated with the traditional {\tt *}.
     <<<1*2*3*4>>>
     Powers are obtained as follows.
     <<<2^100>>>

The bits in brackets can be submitted to Macaulay2 easily.  Position your
cursor at the top of the buffer and press F10.  The cursor will move just past
the first <<<, and the emacs mark will be positioned just before the >>>.  Thus
1*2*3*4 is the region, and it will even be highlighted if you have set the
emacs variable transient-mark-mode to t for this buffer.  Pressing f11 will
send 1*2*3*4 to Macaulay2 for execution: try it now.  A sequence of such
Macaulay2 commands can be executed by alternately pressing F10 and f11.  You
may also use M-F10 to move backward to the previous bracketed expression.

Now go to the very end of the *M2* buffer with M-> and experiment with keyword
completion.  Type reso and then press the TAB key.  Notice how the word is
completed to resolution for you.  Delete the word with M-DEL, type res and then
press the TAB key.  The possible completions are displayed in a window.  Switch
to it with the F8 key, move to the desired completion, select it with the
RETURN key, and then return to the *M2* buffer with C-x o.  Alternatively, if
you have a mouse, use the middle button to select the desired completion.

Experiment with command line history in the *M2* buffer.  Position your cursor
at the end of the buffer, and then use M-p and M-n to move to the previous and
next line of input remembered in the history.  When you get to one you'd like
to run again, simply press return to do so.  Or edit it slightly to change it
before pressing return.

using Macaulay2 with emacs after it has been set up
***************************************************

In this section, we show by example how to use the Macaulay2 emacs interface.
We assume that you have already set up this interface, as described in
setting up the Macaulay2 emacs interface.
After creating or changing the .emacs file mentioned there, you
need to exit and restart emacs.  For the rest of this section, we assume that
you are running emacs.

The aspects of this interface that we describe include
  * Starting Macaulay2 with the f12 key, or with M-x M2
  * Working with two buffers
  * Sending lines or selected text to Macaulay2 using the f11 key
  * Command completion with TAB
  * Horizontal scrolling with f3 and f4

Before starting, note that when we say to type M-x M2, what we really mean is:
press the x key while holding down the meta key (on Macs this is either the
option key or the apple key, depending on how your emacs is set up); type M2;
and then press the return (or enter) key after that.  Similarly, C-c means to
press the c key while holding down the control key, and C-x 2 means to press x
while holding down the control key, then to press 2; this time do not press
enter.

Use the keystrokes C-x 2 to divide the buffer containing this file into two
windows. Then press the f12 key or type M-x M2 to start up Macaulay2 in a
buffer named *M2*.  (The command line used to start Macaulay2 may be edited
before being run if you use a prefix argument with the above command: press C-u
just before.)

If f12 doesn't start up Macaulay2, one reason may be that your function keys
are not operable.  In that case press C-c m instead. Another reason may be that
you have not installed Macaulay2 properly - the startup script (M2 or M2.bat)
should be on your path.

You may use C-x o freely to switch from one window to the other. Verify that
Macaulay2 is running by entering a command such as 2+2. Now create (using C-x
C-f) a file, named something like foo.m2 (the final .m2 is important, as it
informs emacs to use the Macaulay2 mode). Paste the following text into a
buffer.  If you wish, save the file using C-x C-s.

    R = QQ[x,y,z]
    f = symmetricPower(2,vars R)
    M = cokernel f
    C = resolution M
    betti C

Position the cursor on the first line of code, and press the f11 function key
(or C-<return>) repeatedly to present each line to Macaulay2.  If you select
several lines using the mouse, then pressing f11 will present the entire
selection to Macaulay2.  Try this on some of these lines.

Here are some other useful keybindings:

  * C-c C-j: send the current line
  * C-c C-r: send the current region
  * C-c C-b: send the entire buffer
  * C-c C-<up>: send everything before the point
  * C-c C-<down>: send everything after the point
  * C-c C-p: send the current paragraph
-------------------------------------------------------------------------------
Now go to the very end of the *M2* buffer with M-> and experiment with keyword
completion.  Type reso and then press the TAB key.  Notice how the word is
completed to resolution for you.  Delete the word with M-DEL, type res and then
press the TAB key.  The possible completions are displayed in a window.  Switch
to it with M-x switch-to-completions, move to the desired completion, select it
with the RETURN key, and then return to the *M2* buffer with C-x o.
Alternatively, if you have a mouse, use the middle button to select the desired
completion. (On the mac, hold down the option key while clicking the
mouse)-------------------------------------------------------------------------
------

Experiment with command line history in the *M2* buffer.  Position your cursor
at the end of the buffer, and then use M-p and M-n to move to the previous and
next line of input remembered in the history.  When you get to one you'd like
to run again, simply press return to do so.  Or edit it slightly to change it
before pressing return.--------------------------------------------------------
-----------------------

Now let's see how we can handle wide and tall Macaulay2 output.  Execute the
following line of code (put it in your foo.m2 buffer, and then press f11)

printWidth=0; random(R^20,R^{6:-2})
Setting printWidth to zero removes line wrapping in the buffer, sometimes
useful to view large matrices.

Notice that the long lines in the Macaulay2 window, instead of being wrapped
around to the next line, simply disappear off the right side of the screen, as
indicated by the dollar signs or little arrows in the rightmost column.  Switch
to the other window and practice scrolling up and down with M-v and C-v, and
scrolling left and right with the function key F3 (or C-x <) and the function
key F4 (or C-x >).  In modern emacs implementations where mouse clicking works,
click on the arrow to scroll in that direction.  In these versions of emacs,
typing C-e, or C-a to get at the end or beginning of the line also horizontally
scrolls the text to that position.  Older emacs tend to need a bit more: Notice
how the use of C-e to go to the end of the line sends the cursor to the dollar
sign at the right hand side of the screen; that's where the cursor will appear
whenever you go to a position off the screen to the right.  Then use the f2
function key (or C-S-c .) to scroll the text so the cursor appears at the
center of the screen.  Use C-a to move to the beginning of the line and then
the f2 function key (or C-S-c .) to bring the left margin back into view.

You may use C-S-c SPC to toggle whether long lines are truncated or wrapped;
initially they are truncated.

editing Macaulay2 code with emacs
*********************************

In this section we learn how to use emacs to edit Macaulay2 code. Assuming you
have set up your emacs init file as described in setting up the Macaulay2 emacs interface,
when you visit a
file whose name ends with .m2 you will see on the mode line the name Macaulay2
in parentheses, indicating that the file is being edited in Macaulay2 mode.

To see how electric parentheses, electric semicolons, and indentation work,
move to a blank line of this file and type the following text.

f = () -> (
     a := 4;
     b := {6,7};
     a+b)

Observe carefully how matching left parentheses are indicated briefly when a
right parenthesis is typed.

Now position your cursor in between the 6 and 7.  Notice how pressing M-C-u
moves you up out of the list to its left.  Do it again.  Experiment with M-C-f
and M-C-b to move forward and back over complete parenthesized expressions.
(In the emacs manual a complete parenthesized expression is referred to as an
sexp, which is an abbreviation for S-expression.)  Try out C-u 2 M-C-@ as a way
of marking the next two complete parenthesized expression, and see how to use
C-w to kill them and C-y to yank them back.  Experiment with M-C-k to kill the
next complete parenthesized expression.

Position your cursor on the 4 and observe how M-; will start a comment for you
with two hyphens, and position the cursor at the point where commentary may be
entered.

Type res somewhere and then press C-c TAB to bring up the possible completions
of the word to documented Macaulay2 symbols.

Notice how C-h m or F1 m will display the keystrokes peculiar to the mode in a
help window.

using Macaulay2 with TeXmacs
****************************

Texmacs is a free visual text editor for mathematics that can be used to
produce TeX output.  It also supports interactive use with various symbolic
algebra programs, such as Macaulay2.  Texmacs is available from
http://www.texmacs.org/.

Be sure to get TeXmacs version 1.0.6.12 or later.  There is bug in 1.0.6.10,
the effect of which is that no output from Macaulay2 will be displayed.

Using TeXmacs as an interface to Macaulay2 is described in the TeXmacs online
manual: http://www.texmacs.org/tmweb/manual/webman-interface.en.html. The basic
procedure is to pull down the Insert menu, select Session from it, and then to
select Macaulay2 from the resulting submenu.  Alternatively, you can click on
the icon that looks like a computer terminal and select Macaulay2 from the
resulting submenu.

The interface is implemented by a special top level mode in Macaulay2 that
causes the output to be converted to mathML, see TeXmacs.
MathML conversion methods have not been implemented yet for all data types.

a first Macaulay2 session
*************************

Your first input prompt will be i1 : .  In response to the prompt, type 2+2 and
press return.  The expression you entered will be evaluated - no punctuation is
required at the end of the line.

+--------+
|i1 : 2+2|
|        |
|o1 = 4  |
+--------+
The answer is displayed to the right of the output label o1 =.

Here is some arithmetic with fractions.
+---------------+
|i2 : 3/5 + 7/11|
|               |
|     68        |
|o2 = --        |
|     55        |
|               |
|o2 : QQ        |
+---------------+

Notice the additional line of output labeled with o2 :.  Output lines labeled
with colons provide information about the type of output.  In this case, the
symbol QQ, is our notation for the class of all rational numbers, and
indicates that the answer on the previous line is a rational number.

Multiplication is indicated with *.
+------------+
|i3 : 1*2*3*4|
|            |
|o3 = 24     |
+------------+
Powers are obtained with ^.
+------------------------------------------------------------------+
|i4 : 2^200                                                        |
|                                                                  |
|o4 = 1606938044258990275541962092341162602522202993782792835301376|
+------------------------------------------------------------------+
Factorials are obtained with !.
+-----------------------------------------------------+
|i5 : 40!                                             |
|                                                     |
|o5 = 815915283247897734345611269596115894272000000000|
+-----------------------------------------------------+
Because some answers can be very long, it is a good idea to run the program in
a window that does not wrap output lines, and allows the user to scroll left
horizontally to see the rest of the output.  (See using Macaulay2 with emacs.)
+-----------------------------------------------------------------------------+
|i6 : 100!                                                                    |
|                                                                             |
|o6 = 933262154439441526816992388562667004907159682643816214685929638952175999|
|     932299156089414639761565182862536979208272237582511852109168640000000000|
|     00000000000000                                                          |
+-----------------------------------------------------------------------------+
Multiple expressions may be separated by semicolons.
+------------+
|i7 : 1;2;3*4|
|            |
|o9 = 12     |
+------------+
A semicolon at the end of the line suppresses the printing of the value.
+----------+
|i10 : 4*5;|
+----------+
The output from the previous line can be obtained with oo, even if a
semicolon prevented it from being printed.
+--------+
|i11 : oo|
|        |
|o11 = 20|
+--------+
Lines before that can be obtained with ooo, and oooo.
Alternatively, the symbol labeling an output line can be used to retrieve the
value, as in the following example.
+------------------------------------------------------+
|i12 : o5 + 1                                          |
|                                                      |
|o12 = 815915283247897734345611269596115894272000000001|
+------------------------------------------------------+
To enter a string, use quotation marks.
+----------------+
|i13 : "hi there"|
|                |
|o13 = hi there  |
+----------------+
A value can be assigned to a variable with =.
+--------------------+
|i14 : s = "hi there"|
|                    |
|o14 = hi there      |
+--------------------+
Strings may be concatenated horizontally with |, (see String | String).
+-------------------------+
|i15 : s | " - " | s      |
|                         |
|o15 = hi there - hi there|
+-------------------------+
or vertically with ||, (see Net || Net).
+---------------------+
|i16 : s || " - " || s|
|                     |
|o16 = hi there       |
|       -             |
|      hi there       |
+---------------------+
A list of expressions can be formed with braces.
+----------------------+
|i17 : {1, 2, s}       |
|                      |
|o17 = {1, 2, hi there}|
|                      |
|o17 : List            |
+----------------------+
Lists behave like vectors.
+--------------------------+
|i18 : 10*{1,2,3} + {1,1,1}|
|                          |
|o18 = {11, 21, 31}        |
|                          |
|o18 : List                |
+--------------------------+
A function can be created with the arrow operator, see ->, .
+---------------------+
|i19 : f = i -> i^3   |
|                     |
|o19 = f              |
|                     |
|o19 : FunctionClosure|
+---------------------+
To evaluate a function, place its argument to the right of the function.
+---------+
|i20 : f 5|
|         |
|o20 = 125|
+---------+
Functions of more than one variable take a parenthesized sequence of arguments.
+------------------------+
|i21 : g = (x,y) -> x * y|
|                        |
|o21 = g                 |
|                        |
|o21 : FunctionClosure   |
+------------------------+
|i22 : g(6,9)            |
|                        |
|o22 = 54                |
+------------------------+
The function apply, can be used to apply a function to each
element of a list.
+--------------------------------+
|i23 : apply({1,2,3,4}, i -> i^2)|
|                                |
|o23 = {1, 4, 9, 16}             |
|                                |
|o23 : List                      |
+--------------------------------+
|i24 : apply({1,2,3,4}, f)       |
|                                |
|o24 = {1, 8, 27, 64}            |
|                                |
|o24 : List                      |
+--------------------------------+
The operator .., may be used to generate sequences of consecutive
numbers.
+----------------------+
|i25 : apply(1 .. 4, f)|
|                      |
|o25 = (1, 8, 27, 64)  |
|                      |
|o25 : Sequence        |
+----------------------+
If the first argument to apply is an integer n then it stands for the list {0,
1, ..., n-1}.
+-----------------------+
|i26 : apply(5, f)      |
|                       |
|o26 = {0, 1, 8, 27, 64}|
|                       |
|o26 : List             |
+-----------------------+
The function scan, is analogous to apply, except that
no value is returned.  It may be used to implement loops in programs.
+------------------------------------+
|i27 : scan(5, i -> print (i, i^3))  |
|(0, 0)                              |
|(1, 1)                              |
|(2, 8)                              |
|(3, 27)                             |
|(4, 64)                             |
+------------------------------------+
|i28 : j=1; scan(10, i -> j = 2*j); j|
|                                    |
|o30 = 1024                          |
+------------------------------------+
Most computations with polynomials take place in rings that may be specified in
usual mathematical notation.
+----------------------+
|i31 : R = ZZ/5[x,y,z];|
+----------------------+
(We reserve single letter symbols such as Z for use as variables in rings,
hence we must use something like ZZ, to stand for the ring of
integers. It may remind you of the "blackboard bold" font of AMSTeX.  If you
prefer Z to ZZ, you may put Z=ZZ in your initialization file.
The symbols ZZ/5 represent the quotient ring Z/5Z, and
then ZZ/5[x,y,z] represents the ring of polynomials in the variables x,y, and z
with coefficients in the ring Z/5Z.)
+-------------+
|i32 : (x+y)^5|
|             |
|       5    5|
|o32 = x  + y |
|             |
|o32 : R      |
+-------------+
Rings and certain other types of things acquire the name of the global variable
they are assigned to.
+--------------------+
|i33 : R             |
|                    |
|o33 = R             |
|                    |
|o33 : PolynomialRing|
+--------------------+
To see the original description of a ring, use describe.
+---------------------------------------------+
|i34 : describe R                             |
|                                             |
|      ZZ                                     |
|o34 = --[x..z, Degrees => {3:1}, Heft => {1}]|
|       5                                     |
+---------------------------------------------+
A free module can be created as follows.
+--------------------+
|i35 : F = R^3       |
|                    |
|       3            |
|o35 = R             |
|                    |
|o35 : R-module, free|
+--------------------+
The i-th basis element of F can be obtained as F_i.  In this example, the valid
values for i are 0, 1, and 2.
+-----------+
|i36 : F_1  |
|           |
|o36 = | 0 ||
|      | 1 ||
|      | 0 ||
|           |
|       3   |
|o36 : R    |
+-----------+
Using a list of indices instead will produce the homomorphism corresponding to
the basis vectors indicated.
+----------------------+
|i37 : F_{1,2}         |
|                      |
|o37 = | 0 0 |         |
|      | 1 0 |         |
|      | 0 1 |         |
|                      |
|              3      2|
|o37 : Matrix R  <-- R |
+----------------------+
Repetitions are allowed.
+----------------------+
|i38 : F_{2,1,1}       |
|                      |
|o38 = | 0 0 0 |       |
|      | 0 1 1 |       |
|      | 1 0 0 |       |
|                      |
|              3      3|
|o38 : Matrix R  <-- R |
+----------------------+
We can create a homomorphism between free modules with matrix, by
providing the list of rows of the matrix, each of which is in turn a list of
ring elements.
+--------------------------+
|i39 : f = matrix {{x,y,z}}|
|                          |
|o39 = | x y z |           |
|                          |
|              1      3    |
|o39 : Matrix R  <-- R     |
+--------------------------+
Use image, to get the image of f.
+-------------------------------+
|i40 : image f                  |
|                               |
|o40 = image | x y z |          |
|                               |
|                              1|
|o40 : R-module, submodule of R |
+-------------------------------+
We may use ideal, to produce the corresponding ideal.
+---------------------+
|i41 : ideal (x,y,z)  |
|                     |
|o41 = ideal (x, y, z)|
|                     |
|o41 : Ideal of R     |
+---------------------+
We may use kernel, to compute the kernel of f.
+-------------------------------+
|i42 : kernel f                 |
|                               |
|o42 = image {1} | -y 0  -z |   |
|            {1} | x  -z 0  |   |
|            {1} | 0  y  x  |   |
|                               |
|                              3|
|o42 : R-module, submodule of R |
+-------------------------------+
The answer comes out as a module that is expressed as the image of a
homomorphism whose matrix is displayed.  Integers inside braces to the left of
the matrix give the degrees of the basis elements of the target of the matrix;
they are omitted if the degrees are all zero. In case the matrix itself is
desired, it can be obtained with generators, as follows.
+----------------------+
|i43 : generators oo   |
|                      |
|o43 = {1} | -y 0  -z ||
|      {1} | x  -z 0  ||
|      {1} | 0  y  x  ||
|                      |
|              3      3|
|o43 : Matrix R  <-- R |
+----------------------+
We may use poincare, to compute the Poincare polynomial.
+-----------------------+
|i44 : poincare kernel f|
|                       |
|        2    3         |
|o44 = 3T  - T          |
|                       |
|o44 : ZZ[T]            |
+-----------------------+
We may use rank, to compute the rank.
+-------------------+
|i45 : rank kernel f|
|                   |
|o45 = 2            |
+-------------------+
A presentation for the kernel can be obtained with presentation.
+---------------------------+
|i46 : presentation kernel f|
|                           |
|o46 = {2} | z  |           |
|      {2} | x  |           |
|      {2} | -y |           |
|                           |
|              3      1     |
|o46 : Matrix R  <-- R      |
+---------------------------+
We can produce the cokernel with cokernel,; no computation is
performed.
+------------------------------+
|i47 : cokernel f              |
|                              |
|o47 = cokernel | x y z |      |
|                              |
|                             1|
|o47 : R-module, quotient of R |
+------------------------------+
The direct sum is formed with Module ++ Module.
+-----------------------------------------------------+
|i48 : N = kernel f ++ cokernel f                     |
|                                                     |
|o48 = subquotient ({1} | -y 0  -z 0 |, {1} | 0 0 0 |)|
|                   {1} | x  -z 0  0 |  {1} | 0 0 0 | |
|                   {1} | 0  y  x  0 |  {1} | 0 0 0 | |
|                   {0} | 0  0  0  1 |  {0} | x y z | |
|                                                     |
|                                4                    |
|o48 : R-module, subquotient of R                     |
+-----------------------------------------------------+
The answer is expressed in terms of the subquotient,
function, which produces subquotient modules.  Each subquotient module is
accompanied by its matrix of generators and its matrix of relations.  These
matrices can be recovered with generators, and
relations.
+------------------------+
|i49 : generators N      |
|                        |
|o49 = {1} | -y 0  -z 0 ||
|      {1} | x  -z 0  0 ||
|      {1} | 0  y  x  0 ||
|      {0} | 0  0  0  1 ||
|                        |
|              4      4  |
|o49 : Matrix R  <-- R   |
+------------------------+
|i50 : relations N       |
|                        |
|o50 = {1} | 0 0 0 |     |
|      {1} | 0 0 0 |     |
|      {1} | 0 0 0 |     |
|      {0} | x y z |     |
|                        |
|              4      3  |
|o50 : Matrix R  <-- R   |
+------------------------+
The function prune, can be used to convert a subquotient module to
a quotient module.
+-------------------------------+
|i51 : prune N                  |
|                               |
|o51 = cokernel {2} | 0 0 0 z  ||
|               {2} | 0 0 0 x  ||
|               {2} | 0 0 0 -y ||
|               {0} | z y x 0  ||
|                               |
|                             4 |
|o51 : R-module, quotient of R  |
+-------------------------------+
We can use resolution, to compute a projective resolution of
the cokernel of f.
+-----------------------------------+
|i52 : C = resolution cokernel f    |
|                                   |
|       1      3      3      1      |
|o52 = R  <-- R  <-- R  <-- R  <-- 0|
|                                   |
|      0      1      2      3      4|
|                                   |
|o52 : ChainComplex                 |
+-----------------------------------+
To see the differentials we examine 'C.dd'.
+-----------------------------------------+
|i53 : C.dd                               |
|                                         |
|           1                 3           |
|o53 = 0 : R  <------------- R  : 1       |
|                | x y z |                |
|                                         |
|           3                        3    |
|      1 : R  <-------------------- R  : 2|
|                {1} | -y -z 0  |         |
|                {1} | x  0  -z |         |
|                {1} | 0  x  y  |         |
|                                         |
|           3                  1          |
|      2 : R  <-------------- R  : 3      |
|                {2} | z  |               |
|                {2} | -y |               |
|                {2} | x  |               |
|                                         |
|           1                             |
|      3 : R  <----- 0 : 4                |
|                0                        |
|                                         |
|o53 : ChainComplexMap                    |
+-----------------------------------------+
We can verify that C is a complex by squaring the differential map.
+-----------------+
|i54 : C.dd^2 == 0|
|                 |
|o54 = true       |
+-----------------+
We can use betti, to see the degrees of the components of C.
+--------------------+
|i55 : betti C       |
|                    |
|             0 1 2 3|
|o55 = total: 1 3 3 1|
|          0: 1 3 3 1|
|                    |
|o55 : BettiTally    |
+--------------------+
Let's try a harder example.  We can use vars, to create a sequence
of variables.
+-------------------------+
|i56 : R = ZZ/101[a .. r];|
+-------------------------+
We use genericMatrix, to make a 3 by 6 generic matrix
whose entries are drawn from the variables of the ring R.
+--------------------------------+
|i57 : g = genericMatrix(R,a,3,6)|
|                                |
|o57 = | a d g j m p |           |
|      | b e h k n q |           |
|      | c f i l o r |           |
|                                |
|              3      6          |
|o57 : Matrix R  <-- R           |
+--------------------------------+
Then we construct its cokernel with cokernel.
+------------------------------+
|i58 : M = cokernel g          |
|                              |
|o58 = cokernel | a d g j m p ||
|               | b e h k n q ||
|               | c f i l o r ||
|                              |
|                             3|
|o58 : R-module, quotient of R |
+------------------------------+
We may use resolution, to produce a projective resolution of
it, and time, to report the time required.
+---------------------------------------------------------+
|i59 : time C = resolution M                              |
| -- used 0.00133969s (cpu); 0.00133701s (thread); 0s (gc)|
|                                                         |
|       3      6      15      18      6                   |
|o59 = R  <-- R  <-- R   <-- R   <-- R  <-- 0             |
|                                                         |
|      0      1      2       3       4      5             |
|                                                         |
|o59 : ChainComplex                                       |
+---------------------------------------------------------+
As before, we may examine the degrees of its components, or display it.
+------------------------+
|i60 : betti C           |
|                        |
|             0 1  2  3 4|
|o60 = total: 3 6 15 18 6|
|          0: 3 6  .  . .|
|          1: . .  .  . .|
|          2: . . 15 18 6|
|                        |
|o60 : BettiTally        |
+------------------------+
We can make a polynomial ring with 18 IndexedVariable,s.
+-----------------------------------------+
|i61 : S = ZZ/101[t_1 .. t_9, u_1 .. u_9];|
+-----------------------------------------+
We can use genericMatrix, to pack the variables into
3-by-3 matrices.
+-------------------------------------+
|i62 : m = genericMatrix(S, t_1, 3, 3)|
|                                     |
|o62 = | t_1 t_4 t_7 |                |
|      | t_2 t_5 t_8 |                |
|      | t_3 t_6 t_9 |                |
|                                     |
|              3      3               |
|o62 : Matrix S  <-- S                |
+-------------------------------------+
|i63 : n = genericMatrix(S, u_1, 3, 3)|
|                                     |
|o63 = | u_1 u_4 u_7 |                |
|      | u_2 u_5 u_8 |                |
|      | u_3 u_6 u_9 |                |
|                                     |
|              3      3               |
|o63 : Matrix S  <-- S                |
+-------------------------------------+
We may look at the matrix product.
+------------------------------------------------------------------------+
|i64 : m*n                                                               |
|                                                                        |
|o64 = | t_1u_1+t_4u_2+t_7u_3 t_1u_4+t_4u_5+t_7u_6 t_1u_7+t_4u_8+t_7u_9 ||
|      | t_2u_1+t_5u_2+t_8u_3 t_2u_4+t_5u_5+t_8u_6 t_2u_7+t_5u_8+t_8u_9 ||
|      | t_3u_1+t_6u_2+t_9u_3 t_3u_4+t_6u_5+t_9u_6 t_3u_7+t_6u_8+t_9u_9 ||
|                                                                        |
|              3      3                                                  |
|o64 : Matrix S  <-- S                                                   |
+------------------------------------------------------------------------+
Let's produce the equations generated by the equations that assert that m and n
commute with each other.  (See flatten.)
+-----------------------------------------------------------------------------+
|i65 : j = flatten(m*n - n*m)                                                 |
|                                                                             |
|o65 = | t_4u_2+t_7u_3-t_2u_4-t_3u_7 t_2u_1-t_1u_2+t_5u_2+t_8u_3-t_2u_5-t_3u_8|
|      -----------------------------------------------------------------------|
|      t_3u_1+t_6u_2-t_1u_3+t_9u_3-t_2u_6-t_3u_9                              |
|      -----------------------------------------------------------------------|
|      -t_4u_1+t_1u_4-t_5u_4+t_4u_5+t_7u_6-t_6u_7 -t_4u_2+t_2u_4+t_8u_6-t_6u_8|
|      -----------------------------------------------------------------------|
|      -t_4u_3+t_3u_4+t_6u_5-t_5u_6+t_9u_6-t_6u_9                             |
|      -----------------------------------------------------------------------|
|      -t_7u_1-t_8u_4+t_1u_7-t_9u_7+t_4u_8+t_7u_9                             |
|      -----------------------------------------------------------------------|
|      -t_7u_2-t_8u_5+t_2u_7+t_5u_8-t_9u_8+t_8u_9 -t_7u_3-t_8u_6+t_3u_7+t_6u_8|
|      -----------------------------------------------------------------------|
|      |                                                                      |
|                                                                             |
|              1      9                                                       |
|o65 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+
Let's compute a Gröbner basis for the image of j with gb.
+---------------------------------------------------------------------+
|i66 : gb j                                                           |
|                                                                     |
|o66 = GroebnerBasis[status: done; S-pairs encountered up to degree 5]|
|                                                                     |
|o66 : GroebnerBasis                                                  |
+---------------------------------------------------------------------+
The resulting Gröbner basis contains a lot of information. We can get the
generators of the basis, and even though we call upon gb, again, the
computation will not be repeated.
+-----------------------+
|i67 : generators gb j; |
|                       |
|              1      26|
|o67 : Matrix S  <-- S  |
+-----------------------+
The semicolon prevents the matrix of generators from appearing on the screen,
but the class of the matrix appears -- we see that there are 26 generators.

We can use betti, to see the degrees involved in the Gröbner
basis.
+-----------------+
|i68 : betti gb j |
|                 |
|             0  1|
|o68 = total: 1 26|
|          0: 1  .|
|          1: .  8|
|          2: . 12|
|          3: .  5|
|          4: .  1|
|                 |
|o68 : BettiTally |
+-----------------+

reading the documentation
*************************

The documentation for Macaulay2 is available in several formats and can be
searched and viewed using the following functions:

Finding documentation nodes
---------------------------

  * about -- search the documentation
  * apropos -- symbols matching a pattern

Accessing documentation nodes
-----------------------------

  * help -- view documentation nodes
  * viewHelp -- view online documentation in a web browser
  * infoHelp -- view documentation in Info format
  * ? Symbol -- view brief documentation of a symbol

Getting other information from documentation
--------------------------------------------

  * examples -- list the examples in documentation

To begin, the about, method allows for searching all documentation
nodes whose title or content contains a given string:

+-----------------------------+
|i1 : about "Horrocks-Mumford"|
|                             |
|o1 = {}                      |
|                             |
|o1 : NumberedVerticalList    |
+-----------------------------+

The apropos, method is useful for finding all exported objects
whose symbol matches the given regular expression:

+-----------------------------------------------------------------------------+
|i2 : apropos "(H|h)ilbert"                                                   |
|                                                                             |
|o2 = {Hilbert, hilbertBasis, hilbertFunction, hilbertPolynomial,             |
|     ------------------------------------------------------------------------|
|     hilbertSeries, installHilbertFunction, ProjectiveHilbertPolynomial,     |
|     ------------------------------------------------------------------------|
|     projectiveHilbertPolynomial, reduceHilbert, UseHilbertFunction}         |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

While in Macaulay2, type help, to get the documentation on a topic
or function, or type viewHelp, to open ~/.Macaulay2/index.html,
which contains a list of all installed packages, in your default web browser.

For help on a specific topic, e.g., the Jacobian function, use viewHelp
jacobian or viewHelp "jacobian", or if you want the documentation for Jacobian
of an Ideal, use viewHelp (jacobian, Ideal) or viewHelp "jacobian(Ideal)".
Using help, instead of viewHelp, results in the
help text appearing in your Macaulay2 session.

A useful tip: within Emacs, if you place your cursor on one of the resulting
output lines that starts with a *, and press the return key, Macaulay2 will
display that documentation node.

The documentation for most functions comes with example code. You can obtain
the text of this example code using examples.

about -- search the documentation
*********************************

Synopsis
========

  * Usage:
        about s
  * Inputs:
      * s, a string, a function, a
        symbol, or a type,
  * Optional inputs,:
      * Body => a Boolean value, default value false, whether
        also to search the bodies of the documentation nodes. By default, just
        their keys are searched.
  * Outputs:
      * a numbered vertical list, a list of
        documentation node keys matching the regular expression in the string
        s, if s is a string. Otherwise the search matches against the name of s
        as a complete word.

Description
===========

The documentation corresponding to the keys in the list returned can be
displayed by applying the function help, to it. To see the
documentation corresponding to just one or some of the keys, give help,
an integer or a list of integers to be used as indices in the list
returned by the most recent application of about. The functions
viewHelp, and infoHelp, can also be given an
integer for viewing the documentation.

The packages searched are the loaded packages and the packages installed under
one of the prefixes listed in prefixPath. The first search
will take a few seconds while it reads all the documentation keys into memory.

+--------------------------------------------------------------+
|i1 : about firstFunction                                      |
|                                                              |
|o1 = {0 => FirstPackage :: firstFunction    }                 |
|     {1 => FirstPackage :: firstFunction(ZZ)}                 |
|                                                              |
|o1 : NumberedVerticalList                                     |
+--------------------------------------------------------------+
|i2 : help 1                                                   |
|                                                              |
|o2 = FirstPackage::firstFunction(ZZ) -- a silly first function|
|     *********************************************************|
|                                                              |
|     Synopsis                                                 |
|     ========                                                 |
|                                                              |
|       * Usage:                                               |
|             firstFunction n                                  |
|       * Inputs:                                              |
|           * n,                                               |
|       * Outputs:                                             |
|           * a silly string, depending on the value of n      |
|                                                              |
|     Here we show an example.                                 |
|                                                              |
|     +------------------------+                               |
|     |  i1 : firstFunction 1  |                               |
|     |                        |                               |
|     |  o1 = Hello World!     |                               |
|     +------------------------+                               |
|     |  i2 : firstFunction 0  |                               |
|     |                        |                               |
|     |  o2 = D'oh!            |                               |
|     +------------------------+                               |
+--------------------------------------------------------------+

It is also possible to view a table of headlines corresponding to the results.

+------------------------------------------------------------------------+
|i3 : headlines about firstFunction                                      |
|                                                                        |
|o3 = 0.  "FirstPackage :: firstFunction"       -- a silly first function|
|     1.  "FirstPackage :: firstFunction(ZZ)"   -- a silly first function|
+------------------------------------------------------------------------+

Caveat
======

Since s is taken as a regular expression, parentheses serve for grouping
subexpressions, rather than matching themselves.

See also
========

  * help(ZZ) -- search the documentation
  * ? Symbol -- view brief documentation of a symbol
  * apropos -- symbols matching a pattern
  * headlines -- display a table of documentation headlines
  * findSynonyms -- find synonyms of symbols
  * regular expressions -- syntax for regular
    expressions
  * examples(ZZ) -- list the examples in documentation

Ways to use about:
==================

  * "about(Function)"
  * "about(String)"
  * "about(Symbol)"
  * "about(Type)"

For the programmer
==================

The object about, is a method function with options.

apropos -- symbols matching a pattern
*************************************

Synopsis
========

  * Usage:
        apropos pattern
  * Inputs:
      * pattern, a string, a regular expression pattern to match
  * Outputs:
      * a list, of global symbols matching the given pattern

Description
===========

In the simplest case, the list of symbols containing the given string is
returned.

+-----------------------------------------------------------------------------+
|i1 : apropos "atrix"                                                         |
|                                                                             |
|o1 = {blockMatrixForm, ChangeMatrix, compactMatrixForm, diagonalMatrix,      |
|     ------------------------------------------------------------------------|
|     fillMatrix, genericMatrix, genericSkewMatrix, genericSymmetricMatrix,   |
|     ------------------------------------------------------------------------|
|     getChangeMatrix, Matrix, matrix, MatrixExpression, MinimalMatrix,       |
|     ------------------------------------------------------------------------|
|     MutableMatrix, mutableMatrix, randomMutableMatrix, submatrix,           |
|     ------------------------------------------------------------------------|
|     submatrix', submatrixByDegrees, sylvesterMatrix, SyzygyMatrix,          |
|     ------------------------------------------------------------------------|
|     vertexEdgeMatrix, vertexFacetMatrix}                                    |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+

See Regular expressions, allow for more complicated
requests. For example, to find all functions that start with mat or Mat:

+------------------------------------------------------+
|i2 : apropos "^[mM]at"                                |
|                                                      |
|o2 = {match, mathML, Matrix, matrix, MatrixExpression}|
|                                                      |
|o2 : List                                             |
+------------------------------------------------------+

It is also possible to view a table of headlines corresponding to the results.

+-----------------------------------------------------------------------------+
|i3 : headlines apropos "hilbert"                                             |
|                                                                             |
|o3 = 0.  "Polyhedra :: hilbertBasis"           --                            |
|     1.  "Macaulay2Doc :: hilbertFunction"     --                            |
|     2.  "Macaulay2Doc :: hilbertPolynomial"   --                            |
|     3.  "Macaulay2Doc :: hilbertSeries"       --                            |
|-----------------------------------------------------------------------------|
|computes the Hilbert basis of a Cone                                         |
|the Hilbert function                                                         |
|compute the Hilbert polynomial                                               |
|compute the Hilbert series                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * help -- view documentation nodes
  * about -- search the documentation
  * headlines -- display a table of documentation headlines
  * findSynonyms -- find synonyms of symbols
  * regular expressions -- syntax for regular
    expressions

Ways to use apropos:
====================

  * "apropos(String)"

For the programmer
==================

The object apropos, is a method function.

help -- view documentation nodes
********************************

Description
===========

Various ways to get help:

  * help "Macaulay2" -- displays the base of the online documentation tree.
  * help X -- displays the online documentation for X.
  * help methods T -- displays help messages about the methods that take an
    object of class Tas input.
  * help methods res -- displays help messages about various uses the function
    res.
  * help methods symbol ** -- displays help messages about various uses and
    meanings of the operator **.
  * help methods (map, Module) -- displays help messages about various ways to
    use the function map and a module.
  * help methods (symbol **, T) -- displays help messages about various ways to
    use the operator ** and an object of class T.
  * help methods (X, Y) -- displays help messages about the methods usable with
    an object of class X and an object of class Y.
  * help apropos "hilbert" -- displays help messages about all functions whose
    name contains the string hilbert.
  * help about X -- displays documentation nodes from all installed packages
    whose keys contain X.
  * help about(X, Body => true) -- displays documentation nodes from all
    installed packages whose keys or contents contain X.

The help command is used to display online documentation, as in the following
suggestions. Use viewHelp, to display the corresponding
documentation in your web browser.

  * help
  * help ideal
  * help(ideal, List)

Some other potential help topics:

  * help "monomial orderings"
  * help "Gröbner bases"
  * help "multigraded polynomial rings"

See also
========

  * initial help
  * ? Symbol -- view brief documentation of a symbol
  * viewHelp -- view online documentation in a web browser
  * infoHelp -- view documentation in Info format
  * apropos -- symbols matching a pattern
  * about -- search the documentation
  * code -- display source code
  * methods -- list methods
  * examples -- list the examples in documentation

Ways to use help:
=================

  * "help"
  * "help(ZZ)" -- see about, -- search the documentation
  * "help(Array)"
  * "help(DocumentTag)"
  * "help(List)"
  * "help(Sequence)"
  * "help(String)"
  * "help(Symbol)"
  * "help(Thing)"

For the programmer
==================

The object help, is a command.

viewHelp -- view online documentation in a web browser
******************************************************

Synopsis
========

  * Usage:
        viewHelp
        viewHelp X
  * Inputs:
      * X, a thing, a descriptor for a documentation node (see
        below for examples)
  * Consequences:
      * The given documentation page is displayed using the function
        show, which opens the page in the default web browser.

Description
===========

If no argument is given to viewHelp then the top page of your local html
documentation is displayed.

Some example uses:

  * viewHelp -- top of local copy of the documentation, including installed
    packages
  * viewHelp "Macaulay2" -- top of Macaulay2 doc
  * viewHelp ideal -- online doc for the 'ideal' function
  * viewHelp "matrices" -- overview of matrices in Macaulay2
  * viewHelp (ideal, List) -- online doc for ideal(List) method
  * viewHelp (diff, Matrix, Matrix) -- online doc for the diff function taking
    two matrices as arguments
  * viewHelp [gb, DegreeLimit] -- view doc for the optional argument
    DegreeLimit to gb function
  * viewHelp (symbol**, Matrix, Matrix) -- view doc for Matrix**Matrix

Caveat
======

The help, command allows other possible arguments, such as help
methods ideal, but for viewHelp the argument X must refer to only one web page.

See also
========

  * infoHelp -- view documentation in Info format
  * help -- view documentation nodes
  * about -- search the documentation
  * apropos -- symbols matching a pattern
  * makePackageIndex -- create an index of installed
    packages

Ways to use viewHelp:
=====================

  * "viewHelp"
  * "viewHelp(ZZ)" -- see about, -- search the documentation
  * "viewHelp(DocumentTag)"
  * "viewHelp(String)"
  * "viewHelp(Thing)"

For the programmer
==================

The object viewHelp, is a command.

infoHelp -- view documentation in Info format
*********************************************

Synopsis
========

  * Usage:
        infoHelp
        infoHelp X
  * Inputs:
      * X, a thing, a descriptor for a documentation node (see
        below for examples)
  * Consequences:
      * The given documentation page is displayed using info, if you are
        running Macaulay2 in a terminal window. If you are running Macaulay2 in
        Emacs, then the page is opened in another window using Info mode. If no
        argument is given to infoHelp, then the top node of the Macaulay2
        documentation is displayed.

Description
===========

Some example uses:

  * infoHelp "Macaulay2" -- top of Macaulay2 doc
  * infoHelp ideal -- online doc for the 'ideal' function
  * infoHelp "matrices" -- overview of matrices in Macaulay2
  * infoHelp (ideal, List) -- online doc for ideal(List) method
  * infoHelp (diff, Matrix, Matrix) -- online doc for the diff function taking
    two matrices as arguments
  * infoHelp [gb, DegreeLimit] -- view doc for the optional argument
    DegreeLimit to gb function
  * infoHelp (symbol**, Matrix, Matrix) -- view doc for Matrix**Matrix

While in the info program, there are many ways to navigate and search. Besides
the arrow keys to move around on the page, here is a list of the most useful
key strokes:

  * ? -- display information about all of the possible keystrokes
  * q -- quit info, return to Macaulay2
  * n -- go to the next documentation node
  * p -- go to the previous node
  * m -- follow the menu link
  * r -- follow a cross-reference
  * l -- go to the last node visited

Caveat
======

The help, command allows other possible arguments, such as help
methods ideal, but infoHelp requires that the argument s refer to only one
documentation page.

Viewing Info files in Emacs
===========================

If you read the info form of the documentation in Emacs, we recommend
configuring the value of the Emacs variable Info-hide-note-references to hide
in order to prevent Emacs from inserting a superfluous See or see in front of
the hyperlinks. This is done automatically for you by running setup,
or setupEmacs.

See also
========

  * viewHelp -- view online documentation in a web browser
  * help -- view documentation nodes
  * about -- search the documentation
  * apropos -- symbols matching a pattern

Ways to use infoHelp:
=====================

  * "infoHelp"
  * "infoHelp(ZZ)" -- see about, -- search the documentation
  * "infoHelp(DocumentTag)"
  * "infoHelp(Thing)"

For the programmer
==================

The object infoHelp, is a command.

? Symbol -- view brief documentation of a symbol
************************************************

Synopsis
========

  * Operator: ?,

Description
===========

A question mark followed by a symbol representing a function, type, option
name, or package prints a brief, compact list of various ways to use the given
symbol.

  * ? Tally -- displays brief information about ways to use objects of class
    Tally.
  * ? betti -- displays brief information about ways to use the function betti.
  * ? Weights -- displays brief information about ways to use the option
    Weights.
  * ? Package -- displays brief information about the package Package.
  * ? symbol>> -- displays brief information about ways to use the operator >>.
  * ? HH -- displays brief information about ways to use the scripted functor
    HH.

If the object is defined by the user, brief information about the object and
its class are printed.

When using Macaulay2 in Emacs, moving the cursor to each line of the output
beginning with * and pressing Enter results in showing the full documentation
node corresponding to that line.

See also
========

  * initial help
  * methods -- list methods
  * help -- view documentation nodes
  * code -- display source code
  * about -- search the documentation

Ways to use this method:
========================

  * "? Function"
  * "? Keyword"
  * "? Package"
  * "? ScriptedFunctor"
  * ? Symbol -- view brief documentation of a symbol
  * "? Type"

examples -- list the examples in documentation
**********************************************

Synopsis
========

  * Usage:
        examples s
  * Inputs:
      * s, a thing, a descriptor for a documentation node,
        acceptable by makeDocumentTag,
  * Outputs:
      * a net, containing examples of code provided in the
        documentation of s

Description
===========

The output is returned as a Net, of height 0, so the examples will
be displayed indented by just white space, allowing immediate entry.

+-------------------------------------------------------------------+
|i1 : ex := examples(resolution, Ideal)                             |
|                                                                   |
|o1 = -- examples for tag: resolution(Ideal)                        |
|     -- /usr/local/share/Macaulay2/Macaulay2Doc/doc10.m2:256:0     |
|     R = ZZ[a..d]                                                  |
|     I = ideal(a,b,c,d)                                            |
|     C = res I                                                     |
|     C_2                                                           |
|     C.dd_2                                                        |
+-------------------------------------------------------------------+
|i2 : last capture ex                                               |
|                                                                   |
|o2 =                                                               |
|     i1 : -- examples for tag: resolution(Ideal)                   |
|          -- /usr/local/share/Macaulay2/Macaulay2Doc/doc10.m2:256:0|
|          R = ZZ[a..d]                                             |
|                                                                   |
|     o1 = R                                                        |
|                                                                   |
|     o1 : PolynomialRing                                           |
|                                                                   |
|     i2 : I = ideal(a,b,c,d)                                       |
|                                                                   |
|     o2 = ideal (a, b, c, d)                                       |
|                                                                   |
|     o2 : Ideal of R                                               |
|                                                                   |
|     i3 : C = res I                                                |
|                                                                   |
|           1      4      6      4      1                           |
|     o3 = R  <-- R  <-- R  <-- R  <-- R  <-- 0                     |
|                                                                   |
|          0      1      2      3      4      5                     |
|                                                                   |
|     o3 : ChainComplex                                             |
|                                                                   |
|     i4 : C_2                                                      |
|                                                                   |
|           6                                                       |
|     o4 = R                                                        |
|                                                                   |
|     o4 : R-module, free, degrees {6:2}                            |
|                                                                   |
|     i5 : C.dd_2                                                   |
|                                                                   |
|     o5 = {1} | -b 0  -c 0  0  -d |                                |
|          {1} | a  -c 0  0  -d 0  |                                |
|          {1} | 0  b  a  -d 0  0  |                                |
|          {1} | 0  0  0  c  b  a  |                                |
|                                                                   |
|                  4      6                                         |
|     o5 : Matrix R  <-- R                                          |
|                                                                   |
|     i6 :                                                          |
+-------------------------------------------------------------------+

Alternatively, one could use print, to display them with no
indentation.

+---------------------------------------------------------+
|i3 : print ex                                            |
|-- examples for tag: resolution(Ideal)                   |
|-- /usr/local/share/Macaulay2/Macaulay2Doc/doc10.m2:256:0|
|R = ZZ[a..d]                                             |
|I = ideal(a,b,c,d)                                       |
|C = res I                                                |
|C_2                                                      |
|C.dd_2                                                   |
+---------------------------------------------------------+

If the input is an integer, then the examples will correspond to the
documentation node with that index in the last call to about.

+-------------------------------------------------------+
|i4 : about firstFunction                               |
|                                                       |
|o4 = {0 => FirstPackage :: firstFunction    }          |
|     {1 => FirstPackage :: firstFunction(ZZ)}          |
|                                                       |
|o4 : NumberedVerticalList                              |
+-------------------------------------------------------+
|i5 : examples 0                                        |
|                                                       |
|o5 = -- examples for tag: firstFunction                |
|     -- /usr/local/share/Macaulay2/FirstPackage.m2:53:0|
|     firstFunction 1                                   |
|     firstFunction 0                                   |
+-------------------------------------------------------+

If the input is a list, then the examples for all of its elements will be
gathered into a single net.

+-------------------------------------------------------+
|i6 : examples about firstFunction                      |
|                                                       |
|o6 = -- examples for tag: firstFunction                |
|     -- examples for tag: firstFunction(ZZ)            |
|     -- /usr/local/share/Macaulay2/FirstPackage.m2:53:0|
|     firstFunction 1                                   |
|     firstFunction 0                                   |
+-------------------------------------------------------+

See also
========

  * reading the documentation
  * capture -- evaluate Macaulay2 code and capture the output
  * EXAMPLE -- hypertext EXAMPLE item
  * help -- view documentation nodes

Ways to use examples:
=====================

  * "examples(List)"
  * "examples(Thing)"
  * "examples(ZZ)"
  * examples(DocumentTag) (missing documentation)

For the programmer
==================

The object examples, is a method function with a single argument.

getting help or reporting bugs
******************************

An easy way to get help or to report a bug is to use our google group web page
at http://groups.google.com/group/macaulay2. These requests are automatically
emailed to Dan Grayson and Mike Stillman, and they try to handle these requests
quickly.

rings
*****

Macaulay2 differs from other computer algebra systems such as Maple and
Mathematica, in that before making a polynomial, you must create a ring to
contain it, deciding first the complete list of indeterminates and the type of
coefficients permitted.  Recall that a ring is a set with addition and
multiplication operations satisfying familiar axioms, such as the distributive
rule. Examples include the ring of integers (see ZZ), the ring of
rational numbers (see QQ), and the most important rings in Macaulay2,
polynomial rings.

The sections below describe the types of rings available and how to use them.

For additional common operations and a comprehensive list of all routines in
Macaulay2 which return or use rings, see Ring.

Rings

Fields

Other algebras

basic rings of numbers
**********************

The following rings are initially present in every session with Macaulay2.
  * ZZ -- the class of all integers
  * QQ -- the class of all rational numbers
  * RR -- the class of all real numbers
  * CC -- the class of all complex numbers
The names of some of these rings are double letters so the corresponding
symbols with single letters are preserved for use as variables.

Numbers in these rings are constructed as follows.
+-------------------------+
|i1 : 1234                |
|                         |
|o1 = 1234                |
+-------------------------+
|i2 : 123/4               |
|                         |
|     123                 |
|o2 = ---                 |
|      4                  |
|                         |
|o2 : QQ                  |
+-------------------------+
|i3 : 123.4               |
|                         |
|o3 = 123.4               |
|                         |
|o3 : RR (of precision 53)|
+-------------------------+
|i4 : 1.234e-20           |
|                         |
|o4 = 1.234e-20           |
|                         |
|o4 : RR (of precision 53)|
+-------------------------+
|i5 : 123+4*ii            |
|                         |
|o5 = 123+4*ii            |
|                         |
|o5 : CC (of precision 53)|
+-------------------------+
Integers may be entered in bases 2, 8, or 16 using particular prefixes.
+----------------------------+
|i6 : 0b10011010010 -- binary|
|                            |
|o6 = 1234                   |
+----------------------------+
|i7 : 0o2322 -- octal        |
|                            |
|o7 = 1234                   |
+----------------------------+
|i8 : 0x4d2 -- hexadecimal   |
|                            |
|o8 = 1234                   |
+----------------------------+
The usual arithmetic operations are available.
+---------------------------+
|i9 : 4/5 + 2/3             |
|                           |
|     22                    |
|o9 = --                    |
|     15                    |
|                           |
|o9 : QQ                    |
+---------------------------+
|i10 : 10^20                |
|                           |
|o10 = 100000000000000000000|
+---------------------------+
|i11 : 3*5*7                |
|                           |
|o11 = 105                  |
+---------------------------+
|i12 : 3.1^2.1              |
|                           |
|o12 = 10.76117160609969    |
|                           |
|o12 : RR (of precision 53) |
+---------------------------+
|i13 : sqrt 3.              |
|                           |
|o13 = 1.732050807568877    |
|                           |
|o13 : RR (of precision 53) |
+---------------------------+
An additional pair of division operations that produce integer quotients and
remainders is available.
+---------------+
|i14 : 1234//100|
|               |
|o14 = 12       |
+---------------+
|i15 : 1234%100 |
|               |
|o15 = 34       |
+---------------+
Numbers can be promoted to larger rings as follows, see RingElement _ Ring.
+--------------------------+
|i16 : 1_QQ                |
|                          |
|o16 = 1                   |
|                          |
|o16 : QQ                  |
+--------------------------+
|i17 : (2/3)_CC            |
|                          |
|o17 = .6666666666666666   |
|                          |
|o17 : CC (of precision 53)|
+--------------------------+
One way to enter real and complex numbers with more precision is to insert the
desired number of bits of precision after the letter p at the end of the
number, but before the possible e that indicates the exponent of 10.
+---------------------------+
|i18 : 1p300                |
|                           |
|o18 = 1                    |
|                           |
|o18 : RR (of precision 300)|
+---------------------------+
|i19 : 1p300e-30            |
|                           |
|o19 = 1e-30                |
|                           |
|o19 : RR (of precision 300)|
+---------------------------+
Numbers can be lifted to smaller rings as follows, see lift.
+--------------------------+
|i20 : x = 2/3*ii/ii       |
|                          |
|o20 = .6666666666666666   |
|                          |
|o20 : CC (of precision 53)|
+--------------------------+
|i21 : lift(x,RR)          |
|                          |
|o21 = .6666666666666666   |
|                          |
|o21 : RR (of precision 53)|
+--------------------------+
|i22 : lift(x,QQ)          |
|                          |
|      2                   |
|o22 = -                   |
|      3                   |
|                          |
|o22 : QQ                  |
+--------------------------+

integers modulo a prime
***********************

Create the ring of integers modulo a prime number p as follows.
+-----------------+
|i1 : R = ZZ/101  |
|                 |
|o1 = R           |
|                 |
|o1 : QuotientRing|
+-----------------+
We can create elements of the ring as follows.
+----------+
|i2 : 9_R  |
|          |
|o2 = 9    |
|          |
|o2 : R    |
+----------+
|i3 : 103_R|
|          |
|o3 = 2    |
|          |
|o3 : R    |
+----------+
The usual arithmetic operations are available.
+-----------------------+
|i4 : 9_R * 11_R        |
|                       |
|o4 = -2                |
|                       |
|o4 : R                 |
+-----------------------+
|i5 : 9_R ^ 11          |
|                       |
|o5 = 49                |
|                       |
|o5 : R                 |
+-----------------------+
|i6 : 9_R * 11_R == -2_R|
|                       |
|o6 = true              |
+-----------------------+
Find the inverse of an integer modulo a prime as follows.
+------------+
|i7 : 17_R^-1|
|            |
|o7 = 6      |
|            |
|o7 : R      |
+------------+
To view this element as an element of ZZ use the lift, command.
+-----------------------+
|i8 : lift (17_R^-1, ZZ)|
|                       |
|o8 = 6                 |
+-----------------------+

finite fields
*************

Two basic finite fields are:
  * ZZ/p
  * GF(p^n)
Create a finite field with $q = p^n$ elements using
+---------------------------+
|i1 : F = GF(81,Variable=>a)|
|                           |
|o1 = F                     |
|                           |
|o1 : GaloisField           |
+---------------------------+
This creates the ring of characteristic 3, having 3^4 = 81 elements.  The
elements of this ring are 0, a, a^2, a^3, ..., a^80.
+---------+
|i2 : a^80|
|         |
|o2 = 1   |
|         |
|o2 : F   |
+---------+
|i3 : a^40|
|         |
|o3 = -1  |
|         |
|o3 : F   |
+---------+
Use ambient, to see the quotient ring the field is made from.
+-----------------+
|i4 : ambient F   |
|                 |
|        ZZ       |
|        --[a]    |
|         3       |
|o4 = ----------- |
|      4    3     |
|     a  - a  - 1 |
|                 |
|o4 : QuotientRing|
+-----------------+
Now check that a satisfies this equation.
+----------------+
|i5 : a^4 + a - 1|
|                |
|      3         |
|o5 = a  + a     |
|                |
|o5 : F          |
+----------------+
It is often preferable to view elements of F as polynomials in a rather than as
powers of a.  This can be accomplished by lifting the elements back to this
ambient ring.
+-------------------------------------------------+
|i6 : lift(a^20, ambient F)                       |
|                                                 |
|        3    2                                   |
|o6 = - a  - a  - 1                               |
|                                                 |
|        ZZ                                       |
|        --[a]                                    |
|         3                                       |
|o6 : -----------                                 |
|      4    3                                     |
|     a  - a  - 1                                 |
+-------------------------------------------------+
|i7 : apply({20,40,80}, i -> lift(a^i, ambient F))|
|                                                 |
|         3    2                                  |
|o7 = {- a  - a  - 1, -1, 1}                      |
|                                                 |
|o7 : List                                        |
+-------------------------------------------------+
(for more details on lift, see working with multiple rings).

Finite fields can be used as base rings for polynomial rings.
+-----------------------------------------------------------------------------+
|i8 : R = F[x,y,z]                                                            |
|                                                                             |
|o8 = R                                                                       |
|                                                                             |
|o8 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i9 : f = random(2,R)                                                         |
|                                                                             |
|         3      2    2          3    2          2     3                 3    |
|o9 = (- a  + a)x  + a x*y + (- a  - a  - a - 1)y  + (a  + a + 1)x*z + (a  -  |
|     ------------------------------------------------------------------------|
|      2               3    2          2                                      |
|     a  - a)y*z + (- a  - a  + a - 1)z                                       |
|                                                                             |
|o9 : R                                                                       |
+-----------------------------------------------------------------------------+
|i10 : f = (leadCoefficient f)^(-1) * f                                       |
|                                                                             |
|       2       2                 3    2      2       3             2         |
|o10 = x  + (- a  + a - 1)x*y + (a  + a  + 1)y  + (- a  - a)x*z + (a  - a)y*z |
|      -----------------------------------------------------------------------|
|            3      2                                                         |
|      + (- a  + a)z                                                          |
|                                                                             |
|o10 : R                                                                      |
+-----------------------------------------------------------------------------+
Gröbner bases, and all related computations work in these rings.

The prime finite fields can be made easily as quotient rings of ZZ.
+------------------+
|i11 : ZZ/101      |
|                  |
|       ZZ         |
|o11 = ---         |
|      101         |
|                  |
|o11 : QuotientRing|
+------------------+
In general, to make a finite field with q elements, we use GF.
+-----------------+
|i12 : k = GF 81  |
|                 |
|o12 = k          |
|                 |
|o12 : GaloisField|
+-----------------+
The generator of the field is available as the variable a or it can be obtained
as usual.
+---------+
|i13 : a  |
|         |
|o13 = a  |
|         |
|o13 : k  |
+---------+
|i14 : k_0|
|         |
|o14 = a  |
|         |
|o14 : k  |
+---------+
You may use ambient, to see the quotient ring the field is made
from.
+------------------+
|i15 : ambient k   |
|                  |
|         ZZ       |
|         --[a]    |
|          3       |
|o15 = ----------- |
|       4    3     |
|      a  - a  - 1 |
|                  |
|o15 : QuotientRing|
+------------------+
Use ideal, to see the ideal that defined that quotient ring.
+------------------------+
|i16 : ideal oo          |
|                        |
|             4    3     |
|o16 = ideal(a  - a  - 1)|
|                        |
|               ZZ       |
|o16 : Ideal of --[a]    |
|                3       |
+------------------------+
Finally, you may use _, to recover the generator of the ideal.
+-----------------+
|i17 : oo_0       |
|                 |
|       4    3    |
|o17 = a  - a  - 1|
|                 |
|      ZZ         |
|o17 : --[a]      |
|       3         |
+-----------------+
To specify a different name for the generator when the field is created, use
the Variable, option.
+-------------------------------+
|i18 : F = GF(16, Variable => b)|
|                               |
|o18 = F                        |
|                               |
|o18 : GaloisField              |
+-------------------------------+
|i19 : b^20 + 1                 |
|                               |
|       2                       |
|o19 = b  + b + 1               |
|                               |
|o19 : F                        |
+-------------------------------+
|i20 : random F                 |
|                               |
|o20 = 0                        |
|                               |
|o20 : F                        |
+-------------------------------+
Finite fields can be used as base rings for polynomial rings.
+-----------------------------------------------------------------------------+
|i21 : R = F[x,y,z]                                                           |
|                                                                             |
|o21 = R                                                                      |
|                                                                             |
|o21 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i22 : random(2,R)                                                            |
|                                                                             |
|        3          2     3    2             2          2     2               |
|o22 = (b  + b + 1)x  + (b  + b  + 1)x*y + (b  + b + 1)y  + (b  + b + 1)x*z + |
|      -----------------------------------------------------------------------|
|                3    2      2                                                |
|      b*y*z + (b  + b  + b)z                                                 |
|                                                                             |
|o22 : R                                                                      |
+-----------------------------------------------------------------------------+
If you have a quotient ring that you know is a finite field, then you can
convert it to ring that is known by the system to be a finite field.
+--------------------------------------------+
|i23 : GF (ZZ/2[T]/(T^9+T+1), Variable => T) |
|                                            |
|o23 = GF 512                                |
|                                            |
|o23 : GaloisField                           |
+--------------------------------------------+
You may also provide your own choice of primitive element.  Internally,
elements of the finite field are stored as powers of the primitive element.
First we assign our quotient ring to a global variable to ensure that T gets
set to a value in the quotient ring, and then we call GF.
+-------------------------------------------+
|i24 : A = ZZ/2[T]/(T^9+T+1)                |
|                                           |
|o24 = A                                    |
|                                           |
|o24 : QuotientRing                         |
+-------------------------------------------+
|i25 : k = GF (A, PrimitiveElement => T^3+1)|
|                                           |
|o25 = k                                    |
|                                           |
|o25 : GaloisField                          |
+-------------------------------------------+
Notice that T is now recorded as an element of this finite field.
+-------+
|i26 : T|
|       |
|o26 = T|
|       |
|o26 : k|
+-------+
The generator of A can be obtained this way:
+---------+
|i27 : A_0|
|         |
|o27 = T  |
|         |
|o27 : A  |
+---------+
Use substitute, to map it to an element of the finite field.
+-----------------------+
|i28 : substitute(A_0,k)|
|                       |
|o28 = T                |
|                       |
|o28 : k                |
+-----------------------+
Conversely, a given element of the finite field can be transferred back to the
quotient ring with lift.
+-----------------------+
|i29 : lift(k_0, ring T)|
|                       |
|o29 = T                |
|                       |
|o29 : k                |
+-----------------------+
We can even lift it back to the polynomial ring.
+-------------------------------+
|i30 : lift(k_0, ambient ring T)|
|                               |
|o30 = T                        |
|                               |
|o30 : A                        |
+-------------------------------+
For more information see GaloisField.

polynomial rings
****************

A polynomial ring can be created with the usual mathematical notation.
+-------------------+
|i1 : ZZ[x,y,z]     |
|                   |
|o1 = ZZ[x..z]      |
|                   |
|o1 : PolynomialRing|
+-------------------+
If you try to construct this ring again, you will get a different answer.  We
use the strict comparison operator ===, to demonstrate
this.
+--------------------------+
|i2 : ZZ[x,y,z]===ZZ[x,y,z]|
|                          |
|o2 = false                |
+--------------------------+
Thus it is a good idea to assign a new ring to a variable for future reference.
+------------------------+
|i3 : R = QQ[a,b,c,d,e,f]|
|                        |
|o3 = R                  |
|                        |
|o3 : PolynomialRing     |
+------------------------+
Notice that after assignment to a global variable, Macaulay2 knows the ring's
name, and this name is used when printing the ring.
+-------------------+
|i4 : R             |
|                   |
|o4 = R             |
|                   |
|o4 : PolynomialRing|
+-------------------+
The original description of the ring can be recovered with describe.
+--------------------------------------------+
|i5 : describe R                             |
|                                            |
|o5 = QQ[a..f, Degrees => {6:1}, Heft => {1}]|
+--------------------------------------------+
Use the following subscript notation to obtain 0,1, or any multiple of 1, as
elements in the ring.
+---------+
|i6 : 0_R |
|         |
|o6 = 0   |
|         |
|o6 : R   |
+---------+
|i7 : 1_R |
|         |
|o7 = 1   |
|         |
|o7 : R   |
+---------+
|i8 : 11_R|
|         |
|o8 = 11  |
|         |
|o8 : R   |
+---------+
Obtain the variables (generators) of the ring by subscripting the name of the
ring.  As always in Macaulay2, indexing starts at 0.
+---------------------+
|i9 : R_0^10+R_1^3+R_2|
|                     |
|      10    3        |
|o9 = a   + b  + c    |
|                     |
|o9 : R               |
+---------------------+
It is also possible to obtain the variables in a ring from strings containing
their names.
+----------------------------+
|i10 : "a"_R^10+"b"_R^3+"c"_R|
|                            |
|       10    3              |
|o10 = a   + b  + c          |
|                            |
|o10 : R                     |
+----------------------------+
The number of variables is provided by numgens.
+----------------------------------+
|i11 : numgens R                   |
|                                  |
|o11 = 6                           |
+----------------------------------+
|i12 : apply(numgens R, i -> R_i^i)|
|                                  |
|              2   3   4   5       |
|o12 = {1, b, c , d , e , f }      |
|                                  |
|o12 : List                        |
+----------------------------------+
|i13 : sum(numgens R, i -> R_i^i)  |
|                                  |
|       5    4    3    2           |
|o13 = f  + e  + d  + c  + b + 1   |
|                                  |
|o13 : R                           |
+----------------------------------+
(See apply, and sum.)  Use generators,
to obtain a list of the variables of the ring.
+------------------------+
|i14 : gens R            |
|                        |
|o14 = {a, b, c, d, e, f}|
|                        |
|o14 : List              |
+------------------------+
A matrix (with one row) containing the variables of the ring can be obtained
using vars(Ring).
+----------------------+
|i15 : vars R          |
|                      |
|o15 = | a b c d e f | |
|                      |
|              1      6|
|o15 : Matrix R  <-- R |
+----------------------+
The index, of a variable:
+-------------------------------+
|i16 : index x, index y, index z|
|                               |
|o16 = (0, 1, 2)                |
|                               |
|o16 : Sequence                 |
+-------------------------------+
The coefficient ring can be recovered with coefficientRing.
+-----------------------+
|i17 : coefficientRing R|
|                       |
|o17 = QQ               |
|                       |
|o17 : Ring             |
+-----------------------+
An element of the coefficient ring can be promoted to the polynomial ring.
+---------------------+
|i18 : promote(11/2,R)|
|                     |
|      11             |
|o18 = --             |
|       2             |
|                     |
|o18 : R              |
+---------------------+
Conversely, an element of the polynomial ring that is known to be a scalar can
be lifted back to the coefficient ring.
+--------------------------+
|i19 : sc = (a-2)^2-a^2+4*a|
|                          |
|o19 = 4                   |
|                          |
|o19 : R                   |
+--------------------------+
|i20 : lift(sc,QQ)         |
|                          |
|o20 = 4                   |
|                          |
|o20 : QQ                  |
+--------------------------+
In programs, the function liftable, can be used to see whether
this is possible.
+----------------------+
|i21 : liftable(sc,QQ) |
|                      |
|o21 = true            |
+----------------------+
|i22 : liftable(c^3,QQ)|
|                      |
|o22 = false           |
+----------------------+
A random homogeneous element can be obtained with random.
+-----------------------------------------------------------------------------+
|i23 : random(2,R)                                                            |
|                                                                             |
|      9 2   1      3 2   9      3      1 2   1      7       7      3 2       |
|o23 = -a  + -a*b + -b  + -a*c + -b*c + -c  + -a*d + -b*d + --c*d + -d  + a*e |
|      2     2      2     4      4      2     2      4      10      7         |
|      -----------------------------------------------------------------------|
|        7      7      5      2 2   3       7             6              2    |
|      + -b*e + -c*e + -d*e + -e  + -a*f + --b*f + 7c*f + -d*f + e*f + 2f     |
|        9      3      2      3     4      10             7                   |
|                                                                             |
|o23 : R                                                                      |
+-----------------------------------------------------------------------------+
A basis of the subspace of ring elements of a given degree can be obtained in
matrix form with basis.
+------------------------------------------------------------------------+
|i24 : basis(2,R)                                                        |
|                                                                        |
|o24 = | a2 ab ac ad ae af b2 bc bd be bf c2 cd ce cf d2 de df e2 ef f2 ||
|                                                                        |
|              1      21                                                 |
|o24 : Matrix R  <-- R                                                   |
+------------------------------------------------------------------------+
We may construct polynomial rings over polynomial rings.
+---------------------------+
|i25 : R = ZZ[a,b,c][d,e,f];|
+---------------------------+
When displaying an element of an iterated polynomial ring, parentheses are used
to organize the coefficients recursively, which may themselves be polynomials.
+----------------------------------+
|i26 : (a+d+1)^2                   |
|                                  |
|       2                2         |
|o26 = d  + (2a + 2)d + a  + 2a + 1|
|                                  |
|o26 : R                           |
+----------------------------------+
Internally, the polynomials in such towers are expressed in terms of a
flattened monoid containing all the variables, obtainable with the key
FlatMonoid.
+-----------------------------------------------------------------------------+
|i27 : R.FlatMonoid                                                           |
|                                                                             |
|o27 = monoid[d..f, a..c, Degrees => {3:{1}, 3:{0}}, Heft => {2:1},           |
|                                       {0}    {1}                            |
|                                                                             |
|                                                                             |
|                                                                             |
|o27 : GeneralOrderedMonoid                                                   |
|-----------------------------------------------------------------------------|
|MonomialOrder => {MonomialSize => 32}]                                       |
|                 {GRevLex => {3:1}  }                                        |
|                 {Position => Up    }                                        |
|                 {GRevLex => {3:1}  }                                        |
+-----------------------------------------------------------------------------+
Variable names may be words.
+--------------------------------+
|i28 : QQ[rho,sigma,tau];        |
+--------------------------------+
|i29 : (rho - sigma)^2           |
|                                |
|         2                     2|
|o29 = rho  - 2rho*sigma + sigma |
|                                |
|o29 : QQ[rho, sigma, tau]       |
+--------------------------------+
There are various other ways to specify the variables in a polynomial ring.  A
sequence of variables can be obtained as follows.
+---------------+
|i30 : ZZ[b..k];|
+---------------+
In this example, if you had previously assigned either b or k a value that was
not a ring generator, then Macaulay2 would complain about this: it would no
longer understand what variables you wanted.  To get around this, we could
either do
+-------------------------------+
|i31 : ZZ[symbol b .. symbol k];|
+-------------------------------+
or we may obtain the single-letter variables with vars.
+------------------------------------------+
|i32 : vars (0..4)                         |
|                                          |
|o32 = (a, b, c, d, e)                     |
|                                          |
|o32 : Sequence                            |
+------------------------------------------+
|i33 : ZZ[vars (0..4),vars(26..30),vars 51]|
|                                          |
|o33 = ZZ[a..e, A..E, Z]                   |
|                                          |
|o33 : PolynomialRing                      |
+------------------------------------------+
Subscripted variables can be used, provided the base for the subscripted
variable has not been used for something else.
+----------------------------+
|i34 : ZZ[t,p_0,p_1,q_0,q_1];|
+----------------------------+
Sequences of subscripted variables can also be used.
+-------------------------------------------+
|i35 : ZZ[p_(0,0) .. p_(2,1),q_0..q_5]      |
|                                           |
|o35 = ZZ[p   ..p   , q ..q ]               |
|          0,0   2,1   0   5                |
|                                           |
|o35 : PolynomialRing                       |
+-------------------------------------------+
|i36 : (p_(0,0)+q_2-1)^2                    |
|                                           |
|       2                2                  |
|o36 = p    + 2p   q  + q  - 2p    - 2q  + 1|
|       0,0     0,0 2    2     0,0     2    |
|                                           |
|o36 : ZZ[p   ..p   , q ..q ]               |
|          0,0   2,1   0   5                |
+-------------------------------------------+
The subscripts can be much more general, but care is required when using
symbols as subscripts, for the symbols may acquire values later that would
interfere with your original use of them as symbols.  Thus you should protect
symbols that will be used in this way.
+-----------------------------------------+
|i37 : protect xx; protect yy; protect zz;|
+-----------------------------------------+
|i40 : ZZ[ee_[xx],ee_[yy],ee_[zz]]        |
|                                         |
|o40 = ZZ[ee    , ee    , ee    ]         |
|           [xx]    [yy]    [zz]          |
|                                         |
|o40 : PolynomialRing                     |
+-----------------------------------------+
A basis of the subspace of ring elements of a given degree can be obtained in
matrix form with basis.
+------------------------------------------------------------------------+
|i41 : R = QQ[a,b,c,d,e,f];                                              |
+------------------------------------------------------------------------+
|i42 : basis(2,R)                                                        |
|                                                                        |
|o42 = | a2 ab ac ad ae af b2 bc bd be bf c2 cd ce cf d2 de df e2 ef f2 ||
|                                                                        |
|              1      21                                                 |
|o42 : Matrix R  <-- R                                                   |
+------------------------------------------------------------------------+
The Hilbert series of a polynomial ring can be obtained.  Its power series
expansion is the generating function for the dimensions of the degree n parts.
+--------------------------------+
|i43 : hilbertSeries R           |
|                                |
|          1                     |
|o43 = --------                  |
|             6                  |
|      (1 - T)                   |
|                                |
|o43 : Expression of class Divide|
+--------------------------------+
We may use the option Degrees, to produce rings where the
generators have degrees other than 1.
+-----------------------------------------------------+
|i44 : S = ZZ/101[a,b,c,d,Degrees=>{1,2,3,4}]         |
|                                                     |
|o44 = S                                              |
|                                                     |
|o44 : PolynomialRing                                 |
+-----------------------------------------------------+
|i45 : random(5,S)                                    |
|                                                     |
|           5      3         2      2                 |
|o45 = - 11a  + 48a b + 35a*b  + 36a c - 38b*c + 11a*d|
|                                                     |
|o45 : S                                              |
+-----------------------------------------------------+
|i46 : hilbertSeries S                                |
|                                                     |
|                     1                               |
|o46 = -------------------------------                |
|            4       3       2                        |
|      (1 - T )(1 - T )(1 - T )(1 - T)                |
|                                                     |
|o46 : Expression of class Divide                     |
+-----------------------------------------------------+
Some things to watch out for when using polynomial rings:
  * Defining a ring twice gives different rings, as far as Macaulay2 is
    concerned: We use the strict comparison operator ===,
    to demonstrate this.
    +-----------------------------+
    |i47 : ZZ[a,b,c] === ZZ[a,b,c]|
    |                             |
    |o47 = false                  |
    +-----------------------------+
    Thus it is a good idea to assign a new ring to a variable for future
    reference.

See also
========

  * heft vectors
  * division in polynomial rings with monomials less than 1

monoid -- make or retrieve a monoid
***********************************

Synopsis
========

  * Usage:
        monoid[a,b,c,...]
        monoid{a,b,c,...}
  * Inputs:
      * TT "[a,b,c,...]", an array, listing generators of the
        monoid, as well as optional arguments.
      * TT "{a,b,c,...}", a list, same as above, but equivalent to
        also passing Local => true.
  * Optional inputs,:
      * Variables, => a
        list, default value null, see
        monoid(...,Variables=>...),;
      * VariableBaseName,
        => a symbol, default value "p", see
        monoid(...,VariableBaseName=>...),;
      * Global, => a
        Boolean value, default value true, see
        monoid(...,Global=>...),;
      * Local, => a
        Boolean value, default value false, see
        monoid(...,Local=>...),;
      * Inverses, => a
        Boolean value, default value false, see
        monoid(...,Inverses=>...),;
      * Weights, => a
        list, default value {}, see monoid(...,Weights=>...),;
      * Degrees, => a
        list, default value null, see monoid(...,Degrees=>...),;
      * DegreeMap, => a
        Boolean value, default value null, see
        monoid(...,DegreeMap=>...),;
      * DegreeLift, => a
        Boolean value, default value null, see
        monoid(...,DegreeLift=>...),;
      * DegreeRank, => an
        integer, default value null, see
        monoid(...,DegreeRank=>...),;
      * Heft, => a list,
        default value null, see monoid(...,Heft=>...),;
      * Join, => a Boolean value,
        default value null, see monoid(...,Join=>...),;
      * MonomialOrder,
        => a list, default value {GRevLex, Position => Up}, see
        monoid(...,MonomialOrder=>...),;
      * MonomialSize, =>
        an integer, default value 32, see
        monoid(...,MonomialSize=>...),;
      * SkewCommutative,
        => a Boolean value,
        default value {}, see
        monoid(...,SkewCommutative=>...),;
      * WeylAlgebra, => a
        list, default value {}, see
        monoid(...,WeylAlgebra=>...),;
      * Constants (missing documentation) => ..., default value false,
      * DegreeGroup (missing documentation) => ..., default value null,
  * Outputs:
      * a monoid,

Description
===========

The function monoid, is called whenever a polynomial ring is
created, see Ring Array, or when a local polynomial ring is
made, see Ring List. Some of the options provided when making
a monoid don't take effect until the monoid is made into a polynomial ring.

Let's make a free ordered commutative monoid on the variables a,b,c, with
degrees 2, 3, and 4, respectively.

+------------------------------------------+
|i1 : M = monoid[a,b,c, Degrees => {2,3,4}]|
|                                          |
|o1 = M                                    |
|                                          |
|o1 : GeneralOrderedMonoid                 |
+------------------------------------------+
|i2 : degrees M                            |
|                                          |
|o2 = {{2}, {3}, {4}}                      |
|                                          |
|o2 : List                                 |
+------------------------------------------+
|i3 : M_0 * M_1^6                          |
|                                          |
|        6                                 |
|o3 = a*b                                  |
|                                          |
|o3 : M                                    |
+------------------------------------------+

Call use, to assign the variables their values in the monoid.

+------------------------------------------------+
|i4 : monoid[x,y,z]                              |
|                                                |
|o4 = monoid[x..z, Degrees => {3:1}, Heft => {1}]|
|                                                |
|o4 : GeneralOrderedMonoid                       |
+------------------------------------------------+
|i5 : x                                          |
|                                                |
|o5 = x                                          |
|                                                |
|o5 : Symbol                                     |
+------------------------------------------------+
|i6 : use ooo                                    |
|                                                |
|o6 = monoid[x..z, Degrees => {3:1}, Heft => {1}]|
|                                                |
|o6 : GeneralOrderedMonoid                       |
+------------------------------------------------+
|i7 : x * y^6                                    |
|                                                |
|        6                                       |
|o7 = x*y                                        |
|                                                |
|o7 : monoid[x..z, Degrees => {3:1}, Heft => {1}]|
+------------------------------------------------+

The options used when the monoid was created can be recovered with
options.

+-----------------------------------------------------------------------------+
|i8 : options M                                                               |
|                                                                             |
|o8 = OptionTable{Constants => false                     }                    |
|                                  1                                          |
|                 DegreeGroup => ZZ                                           |
|                 DegreeLift => null                                          |
|                 DegreeMap => null                                           |
|                 DegreeRank => 1                                             |
|                 Degrees => {{2}, {3}, {4}}                                  |
|                 Global => true                                              |
|                 Heft => {1}                                                 |
|                 Inverses => false                                           |
|                 Join => null                                                |
|                 Local => false                                              |
|                 MonomialOrder => {MonomialSize => 32  }                     |
|                                  {GRevLex => {2, 3, 4}}                     |
|                                  {Position => Up      }                     |
|                 SkewCommutative => {}                                       |
|                 Variables => {a, b, c}                                      |
|                 WeylAlgebra => {}                                           |
|                                                                             |
|o8 : OptionTable                                                             |
+-----------------------------------------------------------------------------+
|i9 : describe M                                                              |
|                                                                             |
|o9 = monoid[a..c, Degrees => {2..4}, Heft => {1}, MonomialOrder =>           |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32}]                                                        |
|{GRevLex => {2..4} }                                                         |
|{Position => Up    }                                                         |
+-----------------------------------------------------------------------------+
|i10 : toExternalString M                                                     |
|                                                                             |
|o10 = monoid[a..c, Degrees => {2..4}, Heft => {1}, MonomialOrder =>          |
|      VerticalList{MonomialSize => 32, GRevLex => {2..4}, Position => Up}]   |
+-----------------------------------------------------------------------------+

The variables listed may be symbols or indexed variables. The values assigned
to these variables are the corresponding monoid generators. The function
baseName, may be used to recover the original symbol or indexed
variable.

The monoid(...,Heft=>...),
option is used, for instance, by Ext(Module,Module).

+---------------------------------------------------+
|i11 : R = ZZ[x,y, Degrees => {-1,-2}, Heft => {-1}]|
|                                                   |
|o11 = R                                            |
|                                                   |
|o11 : PolynomialRing                               |
+---------------------------------------------------+
|i12 : degree \ gens R                              |
|                                                   |
|o12 = {{-1}, {-2}}                                 |
|                                                   |
|o12 : List                                         |
+---------------------------------------------------+
|i13 : transpose vars R                             |
|                                                   |
|o13 = {1} | x |                                    |
|      {2} | y |                                    |
|                                                   |
|              2      1                             |
|o13 : Matrix R  <-- R                              |
+---------------------------------------------------+

By default, (multi)degrees are concatenated when forming polynomial rings over
polynomial rings, as can be seen by examining the corresponding flattened
monoid, which displays information about all of the variables.

+-----------------------------------------------------------------------------+
|i14 : QQ[x][y]                                                               |
|                                                                             |
|o14 = QQ[x][y]                                                               |
|                                                                             |
|o14 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i15 : oo.FlatMonoid                                                          |
|                                                                             |
|o15 = monoid[y, x, Degrees => {{1}, {0}}, Heft => {2:1}, MonomialOrder =>    |
|                               {0}  {1}                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|o15 : GeneralOrderedMonoid                                                   |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32}]                                                        |
|{GRevLex => {1}    }                                                         |
|{Position => Up    }                                                         |
|{GRevLex => {1}    }                                                         |
+-----------------------------------------------------------------------------+
|i16 : QQ[x][y][z]                                                            |
|                                                                             |
|o16 = QQ[x][y][z]                                                            |
|                                                                             |
|o16 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i17 : oo.FlatMonoid                                                          |
|                                                                             |
|o17 = monoid[z, y, x, Degrees => {{1}, {0}, {0}}, Heft => {3:1},             |
|                                  {0}  {1}  {0}                              |
|                                  {0}  {0}  {1}                              |
|                                                                             |
|                                                                             |
|o17 : GeneralOrderedMonoid                                                   |
|-----------------------------------------------------------------------------|
|MonomialOrder => {MonomialSize => 32}]                                       |
|                 {GRevLex => {1}    }                                        |
|                 {Position => Up    }                                        |
|                 {2:(GRevLex => {1})}                                        |
+-----------------------------------------------------------------------------+

That behavior can be overridden with the monoid(...,Join=>...),
option.

+-----------------------------------------------------------------------------+
|i18 : QQ[x][y, Join => false]                                                |
|                                                                             |
|o18 = QQ[x][y]                                                               |
|                                                                             |
|o18 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i19 : oo.FlatMonoid                                                          |
|                                                                             |
|o19 = monoid[y, x, Degrees => {2:1}, Heft => {1}, Join => false,             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|o19 : GeneralOrderedMonoid                                                   |
|-----------------------------------------------------------------------------|
|MonomialOrder => {MonomialSize => 32}]                                       |
|                 {GRevLex => {1}    }                                        |
|                 {Position => Up    }                                        |
|                 {GRevLex => {1}    }                                        |
+-----------------------------------------------------------------------------+

Ways to use monoid:
===================

  * "monoid(Array)"
  * "monoid(List)"
  * monoid(Ring) -- make or retrieve a monoid

For the programmer
==================

The object monoid, is a method function with a single argument.

Optional arguments

monoid(...,Variables=>...) -- specify the names of the indeterminates
*********************************************************************

Synopsis
========

  * Usage:
        monoid[Variables => L]
        monoid[Variables => n, VariableBaseName => s]

Description
===========

When given a list or sequence, Variables => L specifies the variables to be
used as generators of the monoid.

+--------------------------------------+
|i1 : QQ[Variables => vars(0..3)]      |
|                                      |
|o1 = QQ[a..d]                         |
|                                      |
|o1 : PolynomialRing                   |
+--------------------------------------+
|i2 : QQ[Variables => x_(0,0)..x_(3,3)]|
|                                      |
|o2 = QQ[x   ..x   ]                   |
|         0,0   3,3                    |
|                                      |
|o2 : PolynomialRing                   |
+--------------------------------------+

When given a number, Variables => n specifies number of indexed variables,
to create with base name provided by
VariableBaseName => s, where s may be either a symbol or string. The default
base name is p.

+------------------------------------------------+
|i3 : QQ[Variables => 2]                         |
|                                                |
|o3 = QQ[p ..p ]                                 |
|         0   1                                  |
|                                                |
|o3 : PolynomialRing                             |
+------------------------------------------------+
|i4 : QQ[Variables => 3, VariableBaseName => v]  |
|                                                |
|o4 = QQ[v ..v ]                                 |
|         0   2                                  |
|                                                |
|o4 : PolynomialRing                             |
+------------------------------------------------+
|i5 : QQ[Variables => 4, VariableBaseName => "e"]|
|                                                |
|o5 = QQ[e ..e ]                                 |
|         0   3                                  |
|                                                |
|o5 : PolynomialRing                             |
+------------------------------------------------+
|i6 : class baseName e_0                         |
|                                                |
|o6 = IndexedVariable                            |
|                                                |
|o6 : Type                                       |
+------------------------------------------------+
|i7 : class e                                    |
|                                                |
|o7 = IndexedVariableTable                       |
|                                                |
|o7 : Type                                       |
+------------------------------------------------+

This option is also useful when creating a new ring from an existing ring,
creating a tensor product ring, or symmetric algebra.

+--------------------------------------------------+
|i8 : R = QQ[x, y, Degrees => {1, 2}]              |
|                                                  |
|o8 = R                                            |
|                                                  |
|o8 : PolynomialRing                               |
+--------------------------------------------------+
|i9 : newRing(R, Variables => {a,b})               |
|                                                  |
|o9 = QQ[a..b]                                     |
|                                                  |
|o9 : PolynomialRing                               |
+--------------------------------------------------+
|i10 : degrees oo                                  |
|                                                  |
|o10 = {{1}, {2}}                                  |
|                                                  |
|o10 : List                                        |
+--------------------------------------------------+
|i11 : tensor(R, R, Variables => t_(0,0)..t_(1,1)) |
|                                                  |
|o11 = QQ[t   ..t   ]                              |
|          0,0   1,1                               |
|                                                  |
|o11 : PolynomialRing                              |
+--------------------------------------------------+
|i12 : degrees oo                                  |
|                                                  |
|o12 = {{1, 0}, {2, 0}, {0, 1}, {0, 2}}            |
|                                                  |
|o12 : List                                        |
+--------------------------------------------------+
|i13 : symmetricAlgebra(R^3, Variables => s_0..s_2)|
|                                                  |
|o13 = R[s ..s ]                                   |
|         0   2                                    |
|                                                  |
|o13 : PolynomialRing                              |
+--------------------------------------------------+

Further information
===================

  * Default value: null
  * Function: monoid, -- make or retrieve a monoid
  * Option key: Variables, -- an optional argument

See also
========

  * vars -- variables
  * baseName -- the base name of a generator
  * IndexedVariable -- the class of all indexed
    variables
  * IndexedVariableTable
  * monoid -- make or retrieve a monoid
  * newRing -- make a copy of a ring, with some features
    changed
  * tensor(Ring,Ring) -- tensor product of
    monoids
  * symmetricAlgebra -- the symmetric algebra of a
    module

Functions with optional argument named Variables:
=================================================

  * "basis(...,Variables=>...)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "coefficients(...,Variables=>...)" -- see coefficients,
    -- monomials and their coefficients
  * monoid(...,Variables=>...)
    -- specify the names of the
    indeterminates
  * monomials(...,Variables=>...)
    -- specify variables
  * "newRing(...,Variables=>...)" -- see newRing, -- make a copy
    of a ring, with some features changed
  * "symmetricAlgebra(...,Variables=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Variables=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Variables=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

monoid(...,Local=>...) -- specify local or global monomial order
****************************************************************

Synopsis
========

  * Usage:
        monoid[x,y,z, Local => P, Global => Q]

Description
===========

The optional argument Global specifies whether all variables are larger than 1
in the monomial order. The default value Global => true means that rings in
Macaulay2 are by default global rings. If set to true, and the option
Inverses => true, is not
specified, an error is raised if any of the variables are not greater than 1 in
the monomial ordering, as required by the standard theory
of Gröbner bases.

+------------------------------------------------+
|i1 : QQ[x,y, Weights => {-1,1}, Global => false]|
|                                                |
|o1 = QQ[x..y]                                   |
|                                                |
|o1 : PolynomialRing                             |
+------------------------------------------------+
|i2 : 1 > x                                      |
|                                                |
|o2 = true                                       |
+------------------------------------------------+
|i3 : 1 < y                                      |
|                                                |
|o3 = true                                       |
+------------------------------------------------+
|i4 : leadTerm matrix{{x+x^2, y+y^2}}            |
|                                                |
|o4 = | x y2 |                                   |
|                                                |
|                      1               2         |
|o4 : Matrix (QQ[x..y])  <-- (QQ[x..y])          |
+------------------------------------------------+

The optional argument Local specifies whether all variables are smaller than 1
in the monomial order. Providing Local => true induces a local monomial
ordering and in particular implies Global => false. A shortcut for indicating a
local monomial ordering is to use a List, to provide the variables.

+-----------------------------------------+
|i5 : QQ[x,y, Local => true]              |
|                                         |
|o5 = QQ {x..y}                           |
|                                         |
|o5 : PolynomialRing                      |
+-----------------------------------------+
|i6 : 1 > x                               |
|                                         |
|o6 = true                                |
+-----------------------------------------+
|i7 : 1 > y                               |
|                                         |
|o7 = true                                |
+-----------------------------------------+
|i8 : QQ{x,y}                             |
|                                         |
|o8 = QQ {x..y}                           |
|                                         |
|o8 : PolynomialRing                      |
+-----------------------------------------+
|i9 : leadTerm matrix{{x+x^2, y+y^2}}     |
|                                         |
|o9 = | x y |                             |
|                                         |
|                       1                2|
|o9 : Matrix (QQ {x..y})  <-- (QQ {x..y}) |
+-----------------------------------------+

This option may also be used when creating a new ring from an existing ring,
creating a tensor product ring, or symmetric algebra.

Further information
===================

  * Default value: false,
  * Function: monoid, -- make or retrieve a monoid
  * Option key: Local, -- an optional argument

See also
========

  * heft vectors
  * monomial orderings
  * monoid -- make or retrieve a monoid
  * newRing -- make a copy of a ring, with some features
    changed
  * tensor(Ring,Ring) -- tensor product of
    monoids
  * symmetricAlgebra -- the symmetric algebra of a
    module

Functions with optional argument named Local:
=============================================

  * monoid(...,Local=>...), --
    specify local or global monomial order
  * "newRing(...,Local=>...)" -- see newRing, -- make a copy of
    a ring, with some features changed
  * "symmetricAlgebra(...,Local=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Local=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Local=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

monoid(...,Inverses=>...) -- allow negative exponents in monomials
******************************************************************

Synopsis
========

  * Usage:
        monoid[X,Y, Inverses => P]

Description
===========

The optional argument Inverses specifies whether negative exponents will be
allowed, making the monoid into a group. This option is mainly used by
degreesMonoid, and degreesRing, functions to
allow negative exponents in the monomials.

+--------------------------------------------------------+
|i1 : S = QQ[x,y, Inverses => true, MonomialOrder => Lex]|
|                                                        |
|o1 = S                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : S_{1,-1} + S_{-1,1}                                |
|                                                        |
|        -1    -1                                        |
|o2 = x*y   + x  y                                       |
|                                                        |
|o2 : S                                                  |
+--------------------------------------------------------+

This option may also be used when creating a new ring from an existing ring,
creating a tensor product ring, or symmetric algebra.

Further information
===================

  * Default value: false,
  * Function: monoid, -- make or retrieve a monoid
  * Option key: Inverses, -- an optional argument

See also
========

  * monoid -- make or retrieve a monoid
  * newRing -- make a copy of a ring, with some features
    changed
  * tensor(Ring,Ring) -- tensor product of
    monoids
  * symmetricAlgebra -- the symmetric algebra of a
    module

Functions with optional argument named Inverses:
================================================

  * monoid(...,Inverses=>...)
    -- allow negative exponents in
    monomials
  * "newRing(...,Inverses=>...)" -- see newRing, -- make a copy
    of a ring, with some features changed
  * "symmetricAlgebra(...,Inverses=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Inverses=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Inverses=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

monoid(...,Weights=>...) -- specify weights of the variables
************************************************************

Synopsis
========

  * Usage:
        monoid[a,b,c, Weights => {w1, w2, w3}]

Description
===========

This option specifies the weights of the variables in the monoid. The orderings
by these weight vectors is prepended to the list of orderings provided by the
monoid(...,MonomialOrder=>...),
option. The value must be a
list integers when the degree length is one, or a list of lists of integers
otherwise.

+-----------------------------------+
|i1 : R = QQ[x,y]                   |
|                                   |
|o1 = R                             |
|                                   |
|o1 : PolynomialRing                |
+-----------------------------------+
|i2 : leadTerm matrix {{x+y, x^2+y}}|
|                                   |
|o2 = | x x2 |                      |
|                                   |
|             1      2              |
|o2 : Matrix R  <-- R               |
+-----------------------------------+
|i3 : R = QQ[x,y, Weights => {1,2}] |
|                                   |
|o3 = R                             |
|                                   |
|o3 : PolynomialRing                |
+-----------------------------------+
|i4 : leadTerm matrix {{x+y, x^2+y}}|
|                                   |
|o4 = | y x2 |                      |
|                                   |
|             1      2              |
|o4 : Matrix R  <-- R               |
+-----------------------------------+
|i5 : R = QQ[x,y, Weights => {1,3}] |
|                                   |
|o5 = R                             |
|                                   |
|o5 : PolynomialRing                |
+-----------------------------------+
|i6 : leadTerm matrix {{x+y, x^2+y}}|
|                                   |
|o6 = | y y |                       |
|                                   |
|             1      2              |
|o6 : Matrix R  <-- R               |
+-----------------------------------+

This option may also be used when creating a new ring from an existing ring,
creating a tensor product ring, or symmetric algebra.

Further information
===================

  * Default value: {}
  * Function: monoid, -- make or retrieve a monoid
  * Option key: Weights, -- assigning weights to the variables

See also
========

  * monoid -- make or retrieve a monoid
  * newRing -- make a copy of a ring, with some features
    changed
  * tensor(Ring,Ring) -- tensor product of
    monoids
  * symmetricAlgebra -- the symmetric algebra of a
    module
  * leadTerm -- get the greatest term
  * monoid(...,MonomialOrder=>...)
    -- specify the monomial
    ordering

Functions with optional argument named Weights:
===============================================

  * "betti(...,Weights=>...)" -- see betti(BettiTally),
    -- view and set the weight vector of a Betti diagram
  * "minimalBetti(...,Weights=>...)" -- see minimalBetti,
    -- minimal betti numbers of (the minimal free resolution of) a homogeneous
    ideal or module
  * monoid(...,Weights=>...),
    -- specify weights of the variables
  * "newRing(...,Weights=>...)" -- see newRing, -- make a copy
    of a ring, with some features changed
  * "regularity(...,Weights=>...)" -- see regularity, --
    compute the Castelnuovo-Mumford regularity
  * "symmetricAlgebra(...,Weights=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Weights=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Weights=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

monoid(...,Degrees=>...) -- specify the degrees of the variables
****************************************************************

Synopsis
========

  * Usage:
        monoid[x,y,z, Degrees => {d1, d2, d3}]
        monoid[x,y,z, DegreeRank => r]

Description
===========

The Degrees option specifies the degrees of the variables in the monoid. If
provided, the value must be a list or sequence with as many entries (after
splicing, and flattening) as there are variables.
Each degree is an integers or a list of integers. Degrees provided as integers
will be converted into multidegrees of length 1.

+---------------------------------------+
|i1 : QQ[x,y,z, Degrees => {2:1, 2}]    |
|                                       |
|o1 = QQ[x..z]                          |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : degrees oo                        |
|                                       |
|o2 = {{1}, {1}, {2}}                   |
|                                       |
|o2 : List                              |
+---------------------------------------+
|i3 : QQ[x,y, Degrees => {{1,0}, {0,1}}]|
|                                       |
|o3 = QQ[x..y]                          |
|                                       |
|o3 : PolynomialRing                    |
+---------------------------------------+
|i4 : degrees oo                        |
|                                       |
|o4 = {{1, 0}, {0, 1}}                  |
|                                       |
|o4 : List                              |
+---------------------------------------+

The DegreeRank option specifies the degree length of the monoid. If provided,
the value must be an integer. If the Degrees option is not provided, the
degrees of the variables are determined similar to this example.

+--------------------------------+
|i5 : QQ[a..f, DegreeRank => 3]  |
|                                |
|o5 = QQ[a..f]                   |
|                                |
|o5 : PolynomialRing             |
+--------------------------------+
|i6 : transpose matrix degrees oo|
|                                |
|o6 = | 1 0 0 0 0 0 |            |
|     | 0 1 0 0 0 0 |            |
|     | 0 0 1 1 1 1 |            |
|                                |
|              3       6         |
|o6 : Matrix ZZ  <-- ZZ          |
+--------------------------------+

This option may also be used when creating a new ring from an existing ring,
creating a tensor product ring, or symmetric algebra.

Further information
===================

  * Default value: null
  * Function: monoid, -- make or retrieve a monoid
  * Option key: Degrees, -- an optional argument

See also
========

  * monoid -- make or retrieve a monoid
  * newRing -- make a copy of a ring, with some features
    changed
  * tensor(Ring,Ring) -- tensor product of
    monoids
  * symmetricAlgebra -- the symmetric algebra of a
    module

Functions with optional argument named Degrees:
===============================================

  * monoid(...,Degrees=>...),
    -- specify the degrees of the variables
  * "newRing(...,Degrees=>...)" -- see newRing, -- make a copy
    of a ring, with some features changed
  * "symmetricAlgebra(...,Degrees=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Degrees=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Degrees=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

monoid(...,DegreeLift=>...) -- specify maps between degree groups
*****************************************************************

Synopsis
========

  * Usage:
        monoid[x,y, DegreeMap => p, DegreeLift => q]

Description
===========

The DegreeMap option specifies the degree map, particularly when Join => false
is given. The degree map is a (linear) function from the multidegrees of the
(future) coefficient ring to the multidegrees of the monoid ring (polynomial
ring) made from it with the monoid created here, to be used in determining
homogeneity and in determining degrees in tensor products. The default is the
identity.

If a degree map is provided, it will be used in computing tensor products.

+-----------------------------------------------------------------------------+
|i1 : A = QQ[x];                                                              |
+-----------------------------------------------------------------------------+
|i2 : B = A[y,                                                                |
|         Join => false,                                                      |
|         DegreeMap => x -> 7*x]                                              |
|                                                                             |
|o2 = B                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : B.FlatMonoid                                                            |
|                                                                             |
|o3 = monoid[y, x, Degrees => {1, 7}, Heft => {1}, Join => false,             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|o3 : GeneralOrderedMonoid                                                    |
|-----------------------------------------------------------------------------|
|MonomialOrder => {MonomialSize => 32}]                                       |
|                 {GRevLex => {1}    }                                        |
|                 {Position => Up    }                                        |
|                 {GRevLex => {1}    }                                        |
+-----------------------------------------------------------------------------+
|i4 : degrees A^{-1,-2}                                                       |
|                                                                             |
|o4 = {{1}, {2}}                                                              |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : degrees(A^{-1,-2} ** B)                                                 |
|                                                                             |
|o5 = {{7}, {14}}                                                             |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

For certain applications, such as lifting matrices, a degree lift function can
be provided using the DegreeLift option. The degree lift is a (partial) inverse
of the degree map, giving an error when lifting is not possible. If the degree
map is the identity, then by default the identity map will be provided.

+--------------------------------------------------+
|i6 : B = A[y,                                     |
|         Join => false,                           |
|         DegreeMap => x -> 7*x,                   |
|         DegreeLift => x -> apply(x, d -> d // 7)]|
|                                                  |
|o6 = B                                            |
|                                                  |
|o6 : PolynomialRing                               |
+--------------------------------------------------+
|i7 : m = matrix {{x_B}}                           |
|                                                  |
|o7 = | x |                                        |
|                                                  |
|             1      1                             |
|o7 : Matrix B  <-- B                              |
+--------------------------------------------------+
|i8 : degrees m                                    |
|                                                  |
|o8 = {{{0}}, {{7}}}                               |
|                                                  |
|o8 : List                                         |
+--------------------------------------------------+
|i9 : lift(m, A)                                   |
|                                                  |
|o9 = | x |                                        |
|                                                  |
|             1      1                             |
|o9 : Matrix A  <-- A                              |
+--------------------------------------------------+
|i10 : degrees oo                                  |
|                                                  |
|o10 = {{{0}}, {{1}}}                              |
|                                                  |
|o10 : List                                        |
+--------------------------------------------------+

This option may also be used when creating a new ring from an existing ring,
creating a tensor product ring, or symmetric algebra.

Further information
===================

  * Default value: null
  * Function: monoid, -- make or retrieve a monoid
  * Option key: DegreeLift, -- an optional argument

See also
========

  * monoid -- make or retrieve a monoid
  * newRing -- make a copy of a ring, with some features
    changed
  * tensor(Ring,Ring) -- tensor product of
    monoids
  * symmetricAlgebra -- the symmetric algebra of a
    module

Functions with optional argument named DegreeLift:
==================================================

  * "map(...,DegreeLift=>...)" -- see map(Ring,Ring,Matrix),
    -- make a ring map
  * monoid(...,DegreeLift=>...)
    -- specify maps between
    degree groups
  * "newRing(...,DegreeLift=>...)" -- see newRing, -- make a
    copy of a ring, with some features changed
  * "symmetricAlgebra(...,DegreeLift=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,DegreeLift=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,DegreeLift=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

monoid(...,Heft=>...) -- specify a heft vector
**********************************************

Synopsis
========

  * Usage:
        monoid[a,b, Heft => {...}]

Description
===========

The Heft option can be used to provide a heft vector, as a
list of integers such that the dot product with the degree of each variable
will be positive. This is used as a computational aid in certain routines. If
no value for this option is specified, one will be computed automatically if
possible, hence there is no need to provide one unless the time spent computing
one is onerous; if no heft vector exists, certain computations will not be
supported, and others may take more time.

+--------------------------------------------------+
|i1 : R = ZZ[x,y, Degrees => {-1,-2}, Heft => {-1}]|
|                                                  |
|o1 = R                                            |
|                                                  |
|o1 : PolynomialRing                               |
+--------------------------------------------------+

This option may also be used when creating a new ring from an existing ring,
creating a tensor product ring, or symmetric algebra.

Further information
===================

  * Default value: null
  * Function: monoid, -- make or retrieve a monoid
  * Option key: Heft, -- an optional argument

See also
========

  * monoid -- make or retrieve a monoid
  * newRing -- make a copy of a ring, with some features
    changed
  * tensor(Ring,Ring) -- tensor product of
    monoids
  * symmetricAlgebra -- the symmetric algebra of a
    module

Functions with optional argument named Heft:
============================================

  * monoid(...,Heft=>...), --
    specify a heft vector
  * "newRing(...,Heft=>...)" -- see newRing, -- make a copy of a
    ring, with some features changed
  * "symmetricAlgebra(...,Heft=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Heft=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Heft=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

monoid(...,Join=>...) -- specify how to handle degrees in the coefficient ring
******************************************************************************

Synopsis
========

  * Usage:
        monoid[a,b,c, Join => P]

Description
===========

The Join option specifies whether the degrees in the new monoid ring will be
obtained by joining the degrees in the coefficient with the degrees in the
monoid.

By default, (multi)degrees are concatenated when forming polynomial rings over
polynomial rings, as can be seen by examining the corresponding flattened
monoid, which displays information about all of the variables.

+-----------------------------------------------------------------------------+
|i1 : QQ[x][y]                                                                |
|                                                                             |
|o1 = QQ[x][y]                                                                |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : oo.FlatMonoid                                                           |
|                                                                             |
|o2 = monoid[y, x, Degrees => {{1}, {0}}, Heft => {2:1}, MonomialOrder =>     |
|                              {0}  {1}                                       |
|                                                                             |
|                                                                             |
|                                                                             |
|o2 : GeneralOrderedMonoid                                                    |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32}]                                                        |
|{GRevLex => {1}    }                                                         |
|{Position => Up    }                                                         |
|{GRevLex => {1}    }                                                         |
+-----------------------------------------------------------------------------+
|i3 : QQ[x][y][z]                                                             |
|                                                                             |
|o3 = QQ[x][y][z]                                                             |
|                                                                             |
|o3 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i4 : oo.FlatMonoid                                                           |
|                                                                             |
|o4 = monoid[z, y, x, Degrees => {{1}, {0}, {0}}, Heft => {3:1}, MonomialOrder|
|                                 {0}  {1}  {0}                               |
|                                 {0}  {0}  {1}                               |
|                                                                             |
|                                                                             |
|o4 : GeneralOrderedMonoid                                                    |
|-----------------------------------------------------------------------------|
|=> {MonomialSize => 32}]                                                     |
|   {GRevLex => {1}    }                                                      |
|   {Position => Up    }                                                      |
|   {2:(GRevLex => {1})}                                                      |
+-----------------------------------------------------------------------------+

That behavior can be overridden with the monoid(...,Join=>...),
option.

+-----------------------------------------------------------------------------+
|i5 : QQ[x][y, Join => false]                                                 |
|                                                                             |
|o5 = QQ[x][y]                                                                |
|                                                                             |
|o5 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i6 : oo.FlatMonoid                                                           |
|                                                                             |
|o6 = monoid[y, x, Degrees => {2:1}, Heft => {1}, Join => false, MonomialOrder|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|o6 : GeneralOrderedMonoid                                                    |
|-----------------------------------------------------------------------------|
|=> {MonomialSize => 32}]                                                     |
|   {GRevLex => {1}    }                                                      |
|   {Position => Up    }                                                      |
|   {GRevLex => {1}    }                                                      |
+-----------------------------------------------------------------------------+

This option may also be used when creating a new ring from an existing ring,
creating a tensor product ring, or symmetric algebra.

Further information
===================

  * Default value: null
  * Function: monoid, -- make or retrieve a monoid
  * Option key: Join, -- an optional argument

See also
========

  * monoid -- make or retrieve a monoid
  * newRing -- make a copy of a ring, with some features
    changed
  * tensor(Ring,Ring) -- tensor product of
    monoids
  * symmetricAlgebra -- the symmetric algebra of a
    module

Functions with optional argument named Join:
============================================

  * monoid(...,Join=>...), --
    specify how to handle degrees in the coefficient ring
  * "newRing(...,Join=>...)" -- see newRing, -- make a copy of a
    ring, with some features changed
  * "symmetricAlgebra(...,Join=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Join=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Join=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

monoid(...,MonomialOrder=>...) -- specify the monomial ordering
***************************************************************

Synopsis
========

  * Usage:
        monoid[a,b,c, MonomialOrder => {...}]

Description
===========

The MonomialOrder option specifies the monomial ordering, see
MonomialOrder.

This option may also be used when creating a new ring from an existing ring,
creating a tensor product ring, or symmetric algebra.

Further information
===================

  * Default value: {GRevLex, Position => Up}
  * Function: monoid, -- make or retrieve a monoid
  * Option key: MonomialOrder, -- monomial ordering

See also
========

  * MonomialOrder -- monomial ordering
  * monomial orderings
  * monoid -- make or retrieve a monoid
  * newRing -- make a copy of a ring, with some features
    changed
  * tensor(Ring,Ring) -- tensor product of
    monoids
  * symmetricAlgebra -- the symmetric algebra of a
    module

Functions with optional argument named MonomialOrder:
=====================================================

  * "graphIdeal(...,MonomialOrder=>...)" -- see graphIdeal(RingMap),
    -- the ideal of the graph of the regular map
    corresponding to a ring map
  * "graphRing(...,MonomialOrder=>...)" -- see graphRing(RingMap),
    -- the coordinate ring of the graph of the regular
    map corresponding to a ring map
  * monoid(...,MonomialOrder=>...)
    -- specify the monomial
    ordering
  * "newRing(...,MonomialOrder=>...)" -- see newRing, -- make a
    copy of a ring, with some features changed
  * "pushForward(...,MonomialOrder=>...)" -- see
    pushForward(RingMap,Module),
  * rsort(...,MonomialOrder=>...)
    -- specify Ascending or
    Descending monomial order
  * sort(...,MonomialOrder=>...)
    -- specify Ascending or
    Descending monomial order
  * sortColumns(...,MonomialOrder=>...)
    -- specify Ascending
    or Descending monomial order
  * "symmetricAlgebra(...,MonomialOrder=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,MonomialOrder=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids
  * "tensor(Ring,Ring,MonomialOrder=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

monoid(...,MonomialSize=>...) -- specify the bit-length of monomial exponents in the ring
*****************************************************************************************

Synopsis
========

  * Usage:
        monoid[a,b,c, MonomialSize => n]

Description
===========

The MonomialSize option specifies the minimum number of bits to be used for
storing each exponent in a monomial. The exponents are stored as signed binary
numbers, so n bits allows an exponent as large as $2^{n-1}-1$. Useful values
are 8, 16, and 32.

Further information
===================

  * Default value: 32
  * Function: monoid, -- make or retrieve a monoid
  * Option key: MonomialSize, -- an optional argument

Functions with optional argument named MonomialSize:
====================================================

  * "graphIdeal(...,MonomialSize=>...)" -- see graphIdeal(RingMap),
    -- the ideal of the graph of the regular map
    corresponding to a ring map
  * "graphRing(...,MonomialSize=>...)" -- see graphRing(RingMap),
    -- the coordinate ring of the graph of the regular
    map corresponding to a ring map
  * monoid(...,MonomialSize=>...)
    -- specify the bit-length
    of monomial exponents in the ring
  * "newRing(...,MonomialSize=>...)" -- see newRing, -- make a
    copy of a ring, with some features changed
  * "symmetricAlgebra(...,MonomialSize=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,MonomialSize=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids
  * "tensor(Ring,Ring,MonomialSize=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

monoid(...,SkewCommutative=>...) -- specify Skew commuting variables in the ring
********************************************************************************

Synopsis
========

  * Usage:
        monoid[e_0..e_3, SkewCommutative => true]
        monoid[u,v,x,y,  SkewCommutative => {u,v}]

Description
===========

The SkewCommutative option specifies which variables will skew-commute when the
monoid is used to create a ring. The value true indicates that all of the
variables skew-commute. Otherwise, the value of the option may be a list of
symbols or indices corresponding to the skew-commuting variables.

+----------------------------------------------------------+
|i1 : ZZ/101[e_0..e_3,       SkewCommutative => true]      |
|                                                          |
|      ZZ                                                  |
|o1 = ---[e ..e ]                                          |
|     101  0   3                                           |
|                                                          |
|o1 : PolynomialRing, 4 skew commutative variable(s)       |
+----------------------------------------------------------+
|i2 : (e_0+e_1+e_2+e_3)^2                                  |
|                                                          |
|o2 = 0                                                    |
|                                                          |
|      ZZ                                                  |
|o2 : ---[e ..e ]                                          |
|     101  0   3                                           |
+----------------------------------------------------------+
|i3 : ZZ/101[x,y,vars(0..4), SkewCommutative => vars(0..4)]|
|                                                          |
|      ZZ                                                  |
|o3 = ---[x..y, a..e]                                      |
|     101                                                  |
|                                                          |
|o3 : PolynomialRing, 5 skew commutative variable(s)       |
+----------------------------------------------------------+
|i4 : c*b*a*d                                              |
|                                                          |
|o4 = -a*b*c*d                                             |
|                                                          |
|      ZZ                                                  |
|o4 : ---[x..y, a..e]                                      |
|     101                                                  |
+----------------------------------------------------------+
|i5 : ZZ/101[x,y,vars(0..4), SkewCommutative => {2..6}]    |
|                                                          |
|      ZZ                                                  |
|o5 = ---[x..y, a..e]                                      |
|     101                                                  |
|                                                          |
|o5 : PolynomialRing, 5 skew commutative variable(s)       |
+----------------------------------------------------------+
|i6 : c*b*a*d                                              |
|                                                          |
|o6 = -a*b*c*d                                             |
|                                                          |
|      ZZ                                                  |
|o6 : ---[x..y, a..e]                                      |
|     101                                                  |
+----------------------------------------------------------+
+---------------------------------------------------+
|i7 : R = ZZ[x,y,z, SkewCommutative => {x,y}]       |
|                                                   |
|o7 = R                                             |
|                                                   |
|o7 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i8 : x*y                                           |
|                                                   |
|o8 = x*y                                           |
|                                                   |
|o8 : R                                             |
+---------------------------------------------------+
|i9 : y*x                                           |
|                                                   |
|o9 = -x*y                                          |
|                                                   |
|o9 : R                                             |
+---------------------------------------------------+
|i10 : x*z-z*x                                      |
|                                                   |
|o10 = 0                                            |
|                                                   |
|o10 : R                                            |
+---------------------------------------------------+

This option may also be used when creating a new ring from an existing ring,
creating a tensor product ring, or symmetric algebra.

Further information
===================

  * Default value: {}
  * Function: monoid, -- make or retrieve a monoid
  * Option key: SkewCommutative, -- an optional argument

See also
========

  * monoid -- make or retrieve a monoid
  * newRing -- make a copy of a ring, with some features
    changed
  * tensor(Ring,Ring) -- tensor product of
    monoids
  * symmetricAlgebra -- the symmetric algebra of a
    module

Functions with optional argument named SkewCommutative:
=======================================================

  * monoid(...,SkewCommutative=>...)
    -- specify Skew
    commuting variables in the ring
  * "newRing(...,SkewCommutative=>...)" -- see newRing, -- make
    a copy of a ring, with some features changed
  * "symmetricAlgebra(...,SkewCommutative=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,SkewCommutative=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids
  * "tensor(Ring,Ring,SkewCommutative=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids

monoid(...,WeylAlgebra=>...) -- specify differential operators in the ring
**************************************************************************

Synopsis
========

  * Usage:
        monoid[x,dx,y,dy,   WeylAlgebra => {x => dx, y => dy}]
        monoid[x,dx,y,dy,h, WeylAlgebra => {x => dx, y => dy, h}]

Description
===========

The WeylAlgebra option may be used to provide a list of variables and their
corresponding differential operators in a Weyl algebra. For instance, an option
of the form x => dx specifies that dx plays the role of the derivative with
respect to x in the resulting Weyl algebra.

+-------------------------------------------------------------+
|i1 : R = ZZ/101[x,dx,y,dy, WeylAlgebra => {x => dx, y => dy}]|
|                                                             |
|o1 = R                                                       |
|                                                             |
|o1 : PolynomialRing, 2 differential variable(s)              |
+-------------------------------------------------------------+
|i2 : dx*x                                                    |
|                                                             |
|o2 = x*dx + 1                                                |
|                                                             |
|o2 : R                                                       |
+-------------------------------------------------------------+
|i3 : dx*x^10                                                 |
|                                                             |
|      10        9                                            |
|o3 = x  dx + 10x                                             |
|                                                             |
|o3 : R                                                       |
+-------------------------------------------------------------+
|i4 : dx*y^10                                                 |
|                                                             |
|         10                                                  |
|o4 = dx*y                                                    |
|                                                             |
|o4 : R                                                       |
+-------------------------------------------------------------+

Note that only when the monoid is used to create a polynomial ring the Weyl
algebra variables take effect. There are multiple acceptable ways to populate
this option, but the differential variable always has to come to the right of
the corresponding algebra variable.

+-------------------------------------------------------------+
|i5 : QQ[a,b,x,dx,y,dy, WeylAlgebra => { {2,   3}, {4,   5} }]|
|                                                             |
|o5 = QQ[a..b, x, dx, y, dy]                                  |
|                                                             |
|o5 : PolynomialRing, 2 differential variable(s)              |
+-------------------------------------------------------------+
|i6 : QQ[a,b,x,dx,y,dy, WeylAlgebra => {  2 => 3,   4 => 5  }]|
|                                                             |
|o6 = QQ[a..b, x, dx, y, dy]                                  |
|                                                             |
|o6 : PolynomialRing, 2 differential variable(s)              |
+-------------------------------------------------------------+
|i7 : QQ[a,b,x,dx,y,dy, WeylAlgebra => {  x => dx,  y => dy }]|
|                                                             |
|o7 = QQ[a..b, x, dx, y, dy]                                  |
|                                                             |
|o7 : PolynomialRing, 2 differential variable(s)              |
+-------------------------------------------------------------+
|i8 : QQ[a,b,x,dx,y,dy, WeylAlgebra => { (x, y) => (dx, dy) }]|
|                                                             |
|o8 = QQ[a..b, x, dx, y, dy]                                  |
|                                                             |
|o8 : PolynomialRing, 2 differential variable(s)              |
+-------------------------------------------------------------+

The package Dmodules, contains further methods for
creating and manipulating Weyl algebras.

+------------------------------------------------+
|i9 : needsPackage "Dmodules"                    |
|                                                |
|o9 = Dmodules                                   |
|                                                |
|o9 : Package                                    |
+------------------------------------------------+
|i10 : makeWA(QQ[x,y])                           |
|                                                |
|o10 = QQ[x..y, dx, dy]                          |
|                                                |
|o10 : PolynomialRing, 2 differential variable(s)|
+------------------------------------------------+

Lastly, if a single variable is provided at the end, it is used as a
homogenizing variable.

+-----------------------------------------------------------------------------+
|i11 : QQ[x,dx,y,dy,h, WeylAlgebra => { x => dx, y => dy, h }]                |
|                                                                             |
|o11 = QQ[x, dx, y, dy, h]                                                    |
|                                                                             |
|o11 : PolynomialRing, 3 differential variable(s) and one homogenizing        |
|-----------------------------------------------------------------------------|
|variable                                                                     |
+-----------------------------------------------------------------------------+
|i12 : dx*x^2                                                                 |
|                                                                             |
|       2         2                                                           |
|o12 = x dx + 2x*h                                                            |
|                                                                             |
|o12 : QQ[x, dx, y, dy, h]                                                    |
+-----------------------------------------------------------------------------+
|i13 : dx*x*y                                                                 |
|                                                                             |
|                  2                                                          |
|o13 = x*dx*y + y*h                                                           |
|                                                                             |
|o13 : QQ[x, dx, y, dy, h]                                                    |
+-----------------------------------------------------------------------------+
|i14 : dx*h^2                                                                 |
|                                                                             |
|          2                                                                  |
|o14 = dx*h                                                                   |
|                                                                             |
|o14 : QQ[x, dx, y, dy, h]                                                    |
+-----------------------------------------------------------------------------+
|i15 : isHomogeneous(dx*(x^2+x*y+h^2))                                        |
|                                                                             |
|o15 = true                                                                   |
+-----------------------------------------------------------------------------+

This option may also be used when creating a new ring from an existing ring,
creating a tensor product ring, or symmetric algebra.

Further information
===================

  * Default value: {}
  * Function: monoid, -- make or retrieve a monoid
  * Option key: WeylAlgebra,
    -- specify differential
    operators in the ring

See also
========

  * monoid -- make or retrieve a monoid
  * newRing -- make a copy of a ring, with some features
    changed
  * tensor(Ring,Ring) -- tensor product of
    monoids
  * symmetricAlgebra -- the symmetric algebra of a
    module
  * makeWeylAlgebra (missing documentation)

Functions with optional argument named WeylAlgebra:
===================================================

  * monoid(...,WeylAlgebra=>...)
    -- specify differential
    operators in the ring
  * "newRing(...,WeylAlgebra=>...)" -- see newRing, -- make a
    copy of a ring, with some features changed
  * "symmetricAlgebra(...,WeylAlgebra=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,WeylAlgebra=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids
  * "tensor(Ring,Ring,WeylAlgebra=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

monomial orderings
******************

Every polynomial ring in Macaulay2 comes equipped with an ordering on the
monomials.Polynomials are displayed by ordering the monomials in decreasing
order. The choice of monomial order can make a difference in the time and space
required for various computations, especially Gröbner basis computations.See
below for the definitions of all implemented orderings.

The default ordering is GRevLex, the graded reverse
lexicographic order.This means that terms of higher total degree come first;
and for two terms of the same degree, the term with the higher power of the
last variable comes last; for terms with the same power of the last variable,
the exponent on the next to last variable is consulted, and so on.
+---------------------------------------------------------+
|i1 : R=ZZ/101[a,b,c]                                     |
|                                                         |
|o1 = R                                                   |
|                                                         |
|o1 : PolynomialRing                                      |
+---------------------------------------------------------+
|i2 : (a+b+c+1)^2                                         |
|                                                         |
|      2           2                  2                   |
|o2 = a  + 2a*b + b  + 2a*c + 2b*c + c  + 2a + 2b + 2c + 1|
|                                                         |
|o2 : R                                                   |
+---------------------------------------------------------+
Explicit comparison of monomials with respect to the chosen ordering is
possible.
+--------------+
|i3 : b^2 > a*c|
|              |
|o3 = true     |
+--------------+
The comparison operator ?, returns a symbol indicating the result of
the comparison: the convention is that the larger monomials are printed first
(leftmost).
+--------------+
|i4 : b^2 ? a*c|
|              |
|o4 = >        |
|              |
|o4 : Keyword  |
+--------------+
The monomial ordering is also used when sorting lists with sort.
+----------------------------------------------+
|i5 : sort {1_R, a, a^2, b, b^2, a*b, a^3, b^3}|
|                                              |
|                2        2   3   3            |
|o5 = {1, b, a, b , a*b, a , b , a }           |
|                                              |
|o5 : List                                     |
+----------------------------------------------+

The next ring uses graded lexicographic ordering.  This means that terms of
higher total degree come first; for two terms of the same degree, the term with
the higher power of the first variable comes first: for terms with the same
power of the first variable the power of the second variable is consulted, and
so on.
+---------------------------------------------------------+
|i6 : R=ZZ/101[a,b,c,MonomialOrder=>GLex];                |
+---------------------------------------------------------+
|i7 : (a+b+c+1)^2                                         |
|                                                         |
|      2                  2           2                   |
|o7 = a  + 2a*b + 2a*c + b  + 2b*c + c  + 2a + 2b + 2c + 1|
|                                                         |
|o7 : R                                                   |
+---------------------------------------------------------+
(Notice how similar the result above is to the one obtained when graded reverse
lexicographic ordering is used.)

The next ring uses lexicographic ordering.  This means that terms with the
highest power of the first variable come first: for two terms with the same
power of the first variable the power of the second variable is consulted, and
so on.
+---------------------------------------------------------+
|i8 : R=ZZ/101[a,b,c,MonomialOrder=>Lex];                 |
+---------------------------------------------------------+
|i9 : (a+b+c+1)^2                                         |
|                                                         |
|      2                       2                2         |
|o9 = a  + 2a*b + 2a*c + 2a + b  + 2b*c + 2b + c  + 2c + 1|
|                                                         |
|o9 : R                                                   |
+---------------------------------------------------------+
The next ring uses an elimination order suitable for eliminating the first two
variables, a and b.  In such an ordering we want all terms in which either of
the first two variables appears to come before all of those terms in which the
first two variables don't appear.  This particular ordering accomplishes this
by consulting first the graded reverse lexicographic ordering ignoring all
variables but the first two, and in case of a tie, consulting the graded
reverse lexicographic ordering of the entire monomials.
+----------------------------------------------------------+
|i10 : R=ZZ/101[a,b,c,MonomialOrder=>Eliminate 2];         |
+----------------------------------------------------------+
|i11 : (a+b+c+1)^2                                         |
|                                                          |
|       2           2                            2         |
|o11 = a  + 2a*b + b  + 2a*c + 2b*c + 2a + 2b + c  + 2c + 1|
|                                                          |
|o11 : R                                                   |
+----------------------------------------------------------+
The next ring uses the product ordering that segregates the first variable from
the next two.  This means that terms come first that would come first in the
graded reverse lexicographic ordering when their parts involving the second two
variables are ignored, and in case of equality, the graded reverse
lexicographic ordering of their parts involving just the next two variables is
consulted.
+----------------------------------------------------------+
|i12 : R=ZZ/101[a,b,c,MonomialOrder=>ProductOrder{1,2}];   |
+----------------------------------------------------------+
|i13 : (a+b+c+1)^2                                         |
|                                                          |
|       2                       2           2              |
|o13 = a  + 2a*b + 2a*c + 2a + b  + 2b*c + c  + 2b + 2c + 1|
|                                                          |
|o13 : R                                                   |
+----------------------------------------------------------+

See also
========

  * weightGrevlex (QthPower) -- transform a weight matrix
    into a monomial ordering matrix
  * grevlexWeight (QthPower) -- transform a weight matrix
    into a monomial ordering matrix

Definitions of the specific monomial orders

A succinct summary

Developers' corner

examples of specifying alternate monomial orders
************************************************

For definitions of these monomial orders, see GRevLex,
Lex, Weights, Eliminate,
GroupLex, GroupRevLex, RevLex,
and NCLex.

Graded reverse lexicographic order
==================================

+-------------------+
|i1 : R = ZZ[a..d]; |
+-------------------+
|i2 : a+b^100+c*d   |
|                   |
|      100          |
|o2 = b    + c*d + a|
|                   |
|o2 : R             |
+-------------------+

Lexicographic order
===================

+--------------------------------------+
|i3 : R = ZZ[a..d, MonomialOrder=>Lex];|
+--------------------------------------+
|i4 : a+b^100+c*d                      |
|                                      |
|          100                         |
|o4 = a + b    + c*d                   |
|                                      |
|o4 : R                                |
+--------------------------------------+

Weight order
============

+-------------------------------------------------------+
|i5 : R = ZZ[a..d, MonomialOrder => Weights => {201,2}];|
+-------------------------------------------------------+
|i6 : a+b^100+c*d                                       |
|                                                       |
|          100                                          |
|o6 = a + b    + c*d                                    |
|                                                       |
|o6 : R                                                 |
+-------------------------------------------------------+

Graded lexicographic order
==========================

+-----------------------------------------------------+
|i7 : R = ZZ[a..d, MonomialOrder=>{Weights=>4:1,Lex}];|
+-----------------------------------------------------+
|i8 : a+b^100+c*d                                     |
|                                                     |
|      100                                            |
|o8 = b    + c*d + a                                  |
|                                                     |
|o8 : R                                               |
+-----------------------------------------------------+

Elimination order
=================

To use an elimination order, which eliminates the first 2 variables, use
+----------------------------------------------+
|i9 : R = ZZ[a..f, MonomialOrder=>Eliminate 2];|
+----------------------------------------------+
|i10 : a+b^100+c*d                             |
|                                              |
|       100                                    |
|o10 = b    + a + c*d                          |
|                                              |
|o10 : R                                       |
+----------------------------------------------+
Alternatively, use a weight vector
+------------------------------------------------+
|i11 : R = ZZ[a..f, MonomialOrder=>Weights=>2:1];|
+------------------------------------------------+
|i12 : a+b^100+c*d                               |
|                                                |
|       100                                      |
|o12 = b    + a + c*d                            |
|                                                |
|o12 : R                                         |
+------------------------------------------------+

Product (block) order
=====================

To make a product order where each block has the GRevLex order:
+---------------------------------------------------------------------------+
|i13 : R = ZZ[a..f, MonomialOrder=>{2,4}];                                  |
+---------------------------------------------------------------------------+
|i14 : a^2*(c+d) + b*(c^100+d^100)*(c + e + f)                              |
|                                                                           |
|       2     2       101        100      100       100       100       100 |
|o14 = a c + a d + b*c    + b*c*d    + b*c   e + b*d   e + b*c   f + b*d   f|
|                                                                           |
|o14 : R                                                                    |
+---------------------------------------------------------------------------+
The orders in each block can be other orders as well.
+---------------------------------------------------------------------------+
|i15 : R = ZZ[a..f, MonomialOrder=>{Weights=>2:1,Lex}]                      |
|                                                                           |
|o15 = R                                                                    |
|                                                                           |
|o15 : PolynomialRing                                                       |
+---------------------------------------------------------------------------+
|i16 : a^2*(c+d) + b*(c^100+d^100)*(c + e + f)                              |
|                                                                           |
|       2     2       101      100       100         100      100       100 |
|o16 = a c + a d + b*c    + b*c   e + b*c   f + b*c*d    + b*d   e + b*d   f|
|                                                                           |
|o16 : R                                                                    |
+---------------------------------------------------------------------------+

GroupLex
========

This order is useful for making degree rings, and allows some variables to
appear with negative exponent.
+-----------------------------------------------------------------------------+
|i17 : R = ZZ[a..f, MonomialOrder => GroupLex => 3];                          |
+-----------------------------------------------------------------------------+
|i18 : a^-2*(c+d) + b*(c^100+d^100)*(c + e + f)                               |
|                                                                             |
|         101      100       100         100      100       100     -2     -2 |
|o18 = b*c    + b*c   e + b*c   f + b*c*d    + b*d   e + b*d   f + a  c + a  d|
|                                                                             |
|o18 : R                                                                      |
+-----------------------------------------------------------------------------+

GroupRevLex
===========

This order is useful for making degree rings, and allows some variables to
appear with negative exponent.  Not implemented yet.

RevLex
======

Warning: this is a local ordering, not a global ordering.
+---------------------------------------------------------------------------+
|i19 : R = ZZ[a..f, MonomialOrder=>RevLex, Global=>false];                  |
+---------------------------------------------------------------------------+
|i20 : a^2*(c+d) + b*(c^100+d^100)*(c + e + f)                              |
|                                                                           |
|         100       100         100      100       100       101    2     2 |
|o20 = b*d   f + b*d   e + b*c*d    + b*c   f + b*c   e + b*c    + a d + a c|
|                                                                           |
|o20 : R                                                                    |
+---------------------------------------------------------------------------+

NCLex
=====

For non-commutative Gröbner bases.  Not implemented yet.

See also
========

  * Singular Book 1.2.13 -- monomial orderings

monomial orders for free modules
********************************

In Macaulay2, each free module $F = R^s$ over a ring $R$ has a basis of unit
column vectors $F_0, F_1, ..., F_(s-1)$.  The monomials of $F$ are the elements
$m F_i$, where $m$ is a monomial of the ring $R$. In Macaulay2, orders on the
monomials of $F$ are used for computing Gröbner bases and syzygies, and also to
determine the initial, or lead term of elements of $F$.

The ring $R$ comes equipped with a total order on the monomials of $R$. A total
order on the monomials of $F$ is called compatible (with the order on $R$), if
$m F_i > n F_i$ (in $F$) whenever $m > n$ (in $R$). There are many types of
compatible orders, but several stand out: term over position up (the default in
Macaulay2), term over position down, position up over term, position down over
term, and Schreyer orders.

term over position up:   $m F_i > n F_j$ iff $m>n$ or $m==n$ and $i>j$

term over position down: $m F_i > n F_j$ iff $m>n$ or $m==n$ and $i<j$

position up over term:   $m F_i > n F_j$ iff $i>j$ or $i==j$ and $m>n$

position down over term: $m F_i > n F_j$ iff $i<j$ or $i==j$ and $m>n$

Induced monomial orders are another class of important orders on F, see
Schreyer orders, for their definition and use in Macaulay2.

In Macaulay2, free modules come equipped with a compatible order.  The default
order is: term over position up. This is called Position=>Up.  In the following
example, the lead term is $a F_1$, since $a > b$.
+----------------------+
|i1 : R = ZZ[a..d];    |
+----------------------+
|i2 : F = R^3          |
|                      |
|      3               |
|o2 = R                |
|                      |
|o2 : R-module, free   |
+----------------------+
|i3 : f = b*F_0 + a*F_1|
|                      |
|o3 = | b |            |
|     | a |            |
|     | 0 |            |
|                      |
|      3               |
|o3 : R                |
+----------------------+
|i4 : leadTerm f       |
|                      |
|o4 = | 0 |            |
|     | a |            |
|     | 0 |            |
|                      |
|      3               |
|o4 : R                |
+----------------------+
This is the same as giving the monomial order as:
+-------------------------------------------------------------------+
|i5 : R = ZZ[a..d, MonomialOrder => {GRevLex => 4, Position => Up}];|
+-------------------------------------------------------------------+
|i6 : F = R^3                                                       |
|                                                                   |
|      3                                                            |
|o6 = R                                                             |
|                                                                   |
|o6 : R-module, free                                                |
+-------------------------------------------------------------------+
|i7 : leadTerm(a*F_0 + a*F_1)                                       |
|                                                                   |
|o7 = | 0 |                                                         |
|     | a |                                                         |
|     | 0 |                                                         |
|                                                                   |
|      3                                                            |
|o7 : R                                                             |
+-------------------------------------------------------------------+
Giving Position=>Down instead switches the test above to i < j.  In this case
the monomial order on F is: m*F_i > n*F_j if m>n or m==n and i<j.
+---------------------------------------------------------------------+
|i8 : R = ZZ[a..d, MonomialOrder => {GRevLex => 4, Position => Down}];|
+---------------------------------------------------------------------+
|i9 : F = R^3                                                         |
|                                                                     |
|      3                                                              |
|o9 = R                                                               |
|                                                                     |
|o9 : R-module, free                                                  |
+---------------------------------------------------------------------+
|i10 : leadTerm(a*F_0 + a*F_1)                                        |
|                                                                     |
|o10 = | a |                                                          |
|      | 0 |                                                          |
|      | 0 |                                                          |
|                                                                     |
|       3                                                             |
|o10 : R                                                              |
+---------------------------------------------------------------------+
If one gives Position=>Up or Position=>Down earlier, then the position will be
taken into account earlier. For example
+-----------------------------------------------------------------------------+
|i11 : R = ZZ[a..d, MonomialOrder => {GRevLex => 2, Position => Down, GRevLex |
|-----------------------------------------------------------------------------|
|=> 2}];                                                                      |
+-----------------------------------------------------------------------------+
|i12 : F = R^3                                                                |
|                                                                             |
|       3                                                                     |
|o12 = R                                                                      |
|                                                                             |
|o12 : R-module, free                                                         |
+-----------------------------------------------------------------------------+
|i13 : leadTerm(a*F_0 + a*F_1)                                                |
|                                                                             |
|o13 = | a |                                                                  |
|      | 0 |                                                                  |
|      | 0 |                                                                  |
|                                                                             |
|       3                                                                     |
|o13 : R                                                                      |
+-----------------------------------------------------------------------------+
|i14 : leadTerm(b*F_0 + c^4*F_1)                                              |
|                                                                             |
|o14 = | b |                                                                  |
|      | 0 |                                                                  |
|      | 0 |                                                                  |
|                                                                             |
|       3                                                                     |
|o14 : R                                                                      |
+-----------------------------------------------------------------------------+
|i15 : leadTerm(c*F_0 + d^2*F_1)                                              |
|                                                                             |
|o15 = | c |                                                                  |
|      | 0 |                                                                  |
|      | 0 |                                                                  |
|                                                                             |
|       3                                                                     |
|o15 : R                                                                      |
+-----------------------------------------------------------------------------+
If one wants Position over Term (POT), place the Position element first
+--------------------------------------------------------+
|i16 : R = ZZ[a..d, MonomialOrder => {Position => Down}];|
+--------------------------------------------------------+
|i17 : F = R^3                                           |
|                                                        |
|       3                                                |
|o17 = R                                                 |
|                                                        |
|o17 : R-module, free                                    |
+--------------------------------------------------------+
|i18 : leadTerm(a*F_0 + a*F_1)                           |
|                                                        |
|o18 = | a |                                             |
|      | 0 |                                             |
|      | 0 |                                             |
|                                                        |
|       3                                                |
|o18 : R                                                 |
+--------------------------------------------------------+
|i19 : leadTerm(b*F_0 + c^4*F_1)                         |
|                                                        |
|o19 = | b |                                             |
|      | 0 |                                             |
|      | 0 |                                             |
|                                                        |
|       3                                                |
|o19 : R                                                 |
+--------------------------------------------------------+
|i20 : leadTerm(c*F_0 + d^2*F_1)                         |
|                                                        |
|o20 = | c |                                             |
|      | 0 |                                             |
|      | 0 |                                             |
|                                                        |
|       3                                                |
|o20 : R                                                 |
+--------------------------------------------------------+

Schreyer orders -- induced monomial order on a free module
**********************************************************

The Schreyer order is a monomial order on a free module that is particularly
efficient for computing Gröbner bases and syzygies.  The size of Gröbner bases
of submodules using such orders is often much much smaller than if a position
over term or term over position order would be used.  We call these Schreyer
orders, after Frank-Olaf Schreyer, who used them to give an algorithm for
syzygies, and who also recognized many of their beneficial properties.  See
[S1] and [S2] for the algorithm, and [LS] for improvements and details on the
implementation in Macaulay2
  * [LS] Strategies for computing minimal free resolutions.(R. LaScala and M.
    Stillman, J. Symb. Comp. 26, 409-431, 1998).
  * [S1] Die Berechnung von Syzygien mit dem verallgemeinerten Weierstrassschen
    Divisionssatz.(F.-O. Schreyer, Diplomarbeit, Hamburg, 1980).
  * [S2] A standard basis approach to syzygies of canonical curves.F.-O.
    Schreyer, J. reine angew. Math. 421, 83-123 (1991)

 Given a free $R$-module $G$, a set of monomials $m_0, \ldots, m_{s-1}$ of $G$,
and a monomial order on the monomials of $G$, the induced order, or, Schreyer
order on $F = R^s$ is defined by: $a F_i > b F_j$ (in $F$) iff $a m_i > b m_j$
(in $G$), or $a m_i and b m_j$ are scalar multiples of each other, and $i>j$,
where $F_i$ are the unit column vectors of $F$. Typically the monomials $m_0,
\ldots, m_{s-1}$ are the initial monomials of a Gröbner basis of a submodule of
$G$.

In Macaulay2, free modules with a Schreyer order on them can be created using
schreyerOrder(Matrix).
+----------------------------------+
|i1 : R = ZZ/101[a..f];            |
+----------------------------------+
|i2 : m = matrix{{a,b,c,d}};       |
|                                  |
|             1      4             |
|o2 : Matrix R  <-- R              |
+----------------------------------+
|i3 : m1 = schreyerOrder m         |
|                                  |
|o3 = | a b c d |                  |
|                                  |
|             1      4             |
|o3 : Matrix R  <-- R              |
+----------------------------------+
|i4 : F = source m1                |
|                                  |
|      4                           |
|o4 = R                            |
|                                  |
|o4 : R-module, free, degrees {4:1}|
+----------------------------------+
|i5 : g = syz m1                   |
|                                  |
|o5 = {1} | -b 0  -c 0  0  -d |    |
|     {1} | a  -c 0  0  -d 0  |    |
|     {1} | 0  b  a  -d 0  0  |    |
|     {1} | 0  0  0  c  b  a  |    |
|                                  |
|             4      6             |
|o5 : Matrix R  <-- R              |
+----------------------------------+
|i6 : leadTerm g                   |
|                                  |
|o6 = {1} | 0 0 0 0 0 0 |          |
|     {1} | a 0 0 0 0 0 |          |
|     {1} | 0 b a 0 0 0 |          |
|     {1} | 0 0 0 c b a |          |
|                                  |
|             4      6             |
|o6 : Matrix R  <-- R              |
+----------------------------------+
In Macaulay2, free modules are displayed without any indication of whether they
are endowed with a Schreyer order or not.  To determine whether one is, use
schreyerOrder(Module).  If the result is the
zero matrix, then the monomial order associated with this free module is not a
Schreyer order.  In that case, the monomial order for the free module is the
one determined directly from the ring.
+---------------------------+
|i7 : schreyerOrder target m|
|                           |
|o7 = 0                     |
|                           |
|                   1       |
|o7 : Matrix 0 <-- R        |
+---------------------------+
|i8 : schreyerOrder source g|
|                           |
|o8 = 0                     |
|                           |
|                   6       |
|o8 : Matrix 0 <-- R        |
+---------------------------+
Over quotient rings, the multiplications $a m_i$ and $b m_j$ are over the
ambient polynomial ring, not the quotient.

It is fine for the free module G above to be endowed with a Schreyer order too.

The only places that Schreyer orders are considered is in computation of
Gröbner bases, syzygies, and free resolutions, and with the leadTerm,
routine.

The size of the Gröbner bases of syzygy modules is often dramatically smaller
if the monomial order is the Schreyer order, as in the following example.
+-----------------------------------------------------------------------------+
|i9 : R = QQ[a..f];                                                           |
+-----------------------------------------------------------------------------+
|i10 : I = ideal"abc-def,a2c-d2f,aef-bcd,a3-d3,af2-cd2"                       |
|                                                                             |
|                             2     2                     3    3       2      |
|o10 = ideal (a*b*c - d*e*f, a c - d f, - b*c*d + a*e*f, a  - d , - c*d  +    |
|      -----------------------------------------------------------------------|
|         2                                                                   |
|      a*f )                                                                  |
|                                                                             |
|o10 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i11 : F = syz gens I                                                         |
|                                                                             |
|o11 = {3} | a2+ad+d2 bcd-aef cd2+a2f+d2f a2b+bd2+ade a3-d3    0              |
|      {3} | 0        0       aef-def     abe-bde     0        a3-d3          |
|      {3} | a2+ad+d2 abc-def acd+adf+d2f abd+bd2+d2e 0        0              |
|      {3} | -bc-ef   0       -bcf-cef    -b2c-bce    -abc+def -a2c+d2f       |
|      {3} | 0        0       0           0           0        0              |
|      -----------------------------------------------------------------------|
|      acd-acf          a2c-a2f+acf-d2f  -a2f+acf         a2d-a2f             |
|      -bcd-ace+bcf+aef ace-bcf-aef+def  abc+ace-bcf-aef  -a2e+ade            |
|      d2f-df2          cd2-adf-d2f+df2  cd2-adf-d2f+df2  d3-d2f              |
|      c2e-cef          -bc2-c2e+bcf+cef -bc2-c2e+bcf+cef -bcd+ace-cde+bcf    |
|      -cde+def         cde-def          cde-def          -ade+d2e            |
|      -----------------------------------------------------------------------|
|      a2e+bdf+aef d3-d2f   0        0        0       cd2-af2 0       ad2-adf |
|      ae2-bef     a2e-d2e  -ade+abf 0        a2c-df2 0       cd2-af2 -ade+bdf|
|      ade+d2e+abf ad2-adf  -d3+d2f  -cd2+af2 0       0       0       0       |
|      -bce-ce2    -ace+ef2 cde-bcf  0        -ac2+f3 0       0       cde-bf2 |
|      -abe+de2    -a2e+ade bd2-d2e  bcd-aef  acd-a2f abc-def a2c-d2f a2b-d2e |
|      -----------------------------------------------------------------------|
|      0       abc2-def2  ac2f-df3            ab2c+bdef+ae2f     cdef-bcf2 |  |
|      0       -b2c2+e2f2 ac2e-bc2f-acef+ef3  -b3c+abe2+ae3-be2f 0         |  |
|      0       bcdf-acef  cdf2-af3            bd2e+d2e2+b2df     -bc2d+ef3 |  |
|      cd2-af2 0          -c3e+c2ef           -bce2-ce3          0         |  |
|      a3-d3   0          c2de-acef-cdef+aef2 -b2de+de3          b2c2-e2f2 |  |
|                                                                             |
|              5      23                                                      |
|o11 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i12 : betti gens gb syz F                                                    |
|                                                                             |
|              0  1                                                           |
|o12 = total: 23 67                                                           |
|          5:  1  .                                                           |
|          6: 18 19                                                           |
|          7:  4 27                                                           |
|          8:  .  8                                                           |
|          9:  .  8                                                           |
|         10:  .  5                                                           |
|                                                                             |
|o12 : BettiTally                                                             |
+-----------------------------------------------------------------------------+
|i13 : G = schreyerOrder F                                                    |
|                                                                             |
|o13 = {3} | a2+ad+d2 bcd-aef cd2+a2f+d2f a2b+bd2+ade a3-d3    0              |
|      {3} | 0        0       aef-def     abe-bde     0        a3-d3          |
|      {3} | a2+ad+d2 abc-def acd+adf+d2f abd+bd2+d2e 0        0              |
|      {3} | -bc-ef   0       -bcf-cef    -b2c-bce    -abc+def -a2c+d2f       |
|      {3} | 0        0       0           0           0        0              |
|      -----------------------------------------------------------------------|
|      acd-acf          a2c-a2f+acf-d2f  -a2f+acf         a2d-a2f             |
|      -bcd-ace+bcf+aef ace-bcf-aef+def  abc+ace-bcf-aef  -a2e+ade            |
|      d2f-df2          cd2-adf-d2f+df2  cd2-adf-d2f+df2  d3-d2f              |
|      c2e-cef          -bc2-c2e+bcf+cef -bc2-c2e+bcf+cef -bcd+ace-cde+bcf    |
|      -cde+def         cde-def          cde-def          -ade+d2e            |
|      -----------------------------------------------------------------------|
|      a2e+bdf+aef d3-d2f   0        0        0       cd2-af2 0       ad2-adf |
|      ae2-bef     a2e-d2e  -ade+abf 0        a2c-df2 0       cd2-af2 -ade+bdf|
|      ade+d2e+abf ad2-adf  -d3+d2f  -cd2+af2 0       0       0       0       |
|      -bce-ce2    -ace+ef2 cde-bcf  0        -ac2+f3 0       0       cde-bf2 |
|      -abe+de2    -a2e+ade bd2-d2e  bcd-aef  acd-a2f abc-def a2c-d2f a2b-d2e |
|      -----------------------------------------------------------------------|
|      0       abc2-def2  ac2f-df3            ab2c+bdef+ae2f     cdef-bcf2 |  |
|      0       -b2c2+e2f2 ac2e-bc2f-acef+ef3  -b3c+abe2+ae3-be2f 0         |  |
|      0       bcdf-acef  cdf2-af3            bd2e+d2e2+b2df     -bc2d+ef3 |  |
|      cd2-af2 0          -c3e+c2ef           -bce2-ce3          0         |  |
|      a3-d3   0          c2de-acef-cdef+aef2 -b2de+de3          b2c2-e2f2 |  |
|                                                                             |
|              5      23                                                      |
|o13 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i14 : betti gens gb syz G                                                    |
|                                                                             |
|              0  1                                                           |
|o14 = total: 23 45                                                           |
|          5:  1  .                                                           |
|          6: 18 19                                                           |
|          7:  4 22                                                           |
|          8:  .  4                                                           |
|                                                                             |
|o14 : BettiTally                                                             |
+-----------------------------------------------------------------------------+

See also
========

  * leadTerm -- get the greatest term
  * schreyerOrder(Matrix) -- create a matrix
    with the same entries whose source free module has a Schreyer monomial
    order
  * schreyerOrder(Module) -- obtain Schreyer
    order information
  * gb -- compute a Gröbner basis
  * syz -- the syzygy matrix
  * resolution -- projective resolution
  * betti -- display or modify a Betti diagram

packing monomials for efficiency
********************************

Sometimes for efficiency reasons, it is important to pack exponent vectors
several exponents per machine word.  Polynomials take less space, and monomial
operations such as comparison and multiplication become faster.

The monomial order keys Lex, and GRevLex, allow
packing.  The MonomialSize => n option allows one to set the minimum packing
size, in number of bits. Monomials are stored as signed exponent vectors, so
maximum exponents of 2^(n-1)-1 are possible for packed variables.  Useful
values include 8, 16, 32, and (on 64-bit machines) 64.  The default monomial
size is 32.
+------------------------------------------------------------------+
|i1 : A = QQ[a..d,MonomialSize=>8]                                 |
|                                                                  |
|o1 = A                                                            |
|                                                                  |
|o1 : PolynomialRing                                               |
+------------------------------------------------------------------+
|i2 : B = QQ[x,y,z,w,MonomialSize=>16,MonomialOrder=>Lex]          |
|                                                                  |
|o2 = B                                                            |
|                                                                  |
|o2 : PolynomialRing                                               |
+------------------------------------------------------------------+
The maximum degree for monomials in A is 127.  Monomials of higher degree will
encounter a monomial overflow.  In the second example, the maximum exponent is
32767 (2^15-1).

It is possible to pack different parts of the monomial with different sizes.
For example, the following order has two blocks: a graded reverse lexicographic
block of 3 variables, packed into one 32-bit word, and a second lexicographic
block for 4 variables, taking 4 32-bit words. Each monomial will be packed into
5 32-bit words (on a computer with a 32-bit word size).
+-----------------------------------------------------------------------------+
|i3 : C = QQ[a,b,c,x,y,z,w,MonomialOrder=>{MonomialSize=>8,3,MonomialSize=>32,|
|-----------------------------------------------------------------------------|
|Lex=>4}];                                                                    |
+-----------------------------------------------------------------------------+

+-------------------------------------+
|i4 : D = QQ[a..d,MonomialOrder=>Lex];|
+-------------------------------------+
|i5 : a^1000000000                    |
|                                     |
|      1000000000                     |
|o5 = a                               |
|                                     |
|o5 : D                               |
+-------------------------------------+

This exponent would give a monomial overflow error in the next two rings.
+------------------------------------------------------+
|i6 : E = QQ[a..d,MonomialSize=>16,MonomialOrder=>Lex];|
+------------------------------------------------------+
|i7 : F = QQ[a..d,MonomialSize=>8,MonomialOrder=>Lex]; |
+------------------------------------------------------+

GRevLex -- graded reverse lexicographical monomial order.
*********************************************************

Description
===========

 The graded reverse lexicographic order is defined by: $x^A > x^B$ if either
$degree(x^A) > degree(x^B)$ or $degree(x^A) = degree(x^B)$ and the LAST
non-zero entry of the vector of integers $A-B$ is NEGATIVE.

 This is the default order in Macaulay2, in large part because it is often the
most efficient order for use with Gröbner bases.  By giving GRevLex a list of
integers, one may change the definition of the order: $degree(x^A)$ is the dot
product of $A$ with the argument of GRevLex.
+---------------------------------------------------------+
|i1 : R = QQ[a..d];                                       |
+---------------------------------------------------------+
|i2 : a^3 + b^2 + b*c                                     |
|                                                         |
|      3    2                                             |
|o2 = a  + b  + b*c                                       |
|                                                         |
|o2 : R                                                   |
+---------------------------------------------------------+
|i3 : S = QQ[a..d, MonomialOrder => GRevLex => {1,2,3,4}];|
+---------------------------------------------------------+
|i4 : a^3 + b^2 + b*c                                     |
|                                                         |
|            2    3                                       |
|o4 = b*c + b  + a                                        |
|                                                         |
|o4 : S                                                   |
+---------------------------------------------------------+
The largest possible exponent of variables in the GRevLex order is 2^31-1.  For
efficiency reasons, it is sometimes useful to limit the size of monomials (this
often makes computations more efficient).Use MonomialSize => 16, which allows
maximal exponent 2^15-1, or MonomialSize => 8, which allows maximal exponent
2^7-1.
+-----------------------------------------------------------+
|i5 : B1 = QQ[a..d,MonomialSize=>16,MonomialOrder=>GRevLex];|
+-----------------------------------------------------------+
|i6 : B = QQ[a..d,MonomialSize=>16];                        |
+-----------------------------------------------------------+
|i7 : a^(2^15-1)                                            |
|                                                           |
|      32767                                                |
|o7 = a                                                     |
|                                                           |
|o7 : B                                                     |
+-----------------------------------------------------------+
|i8 : C = QQ[a..d,MonomialSize=>8,MonomialOrder=>GRevLex];  |
+-----------------------------------------------------------+
|i9 : try a^(2^15-1) else "failed"                          |
|                                                           |
|o9 = failed                                                |
+-----------------------------------------------------------+
|i10 : a^(2^7-1)                                            |
|                                                           |
|       127                                                 |
|o10 = a                                                    |
|                                                           |
|o10 : C                                                    |
+-----------------------------------------------------------+

See also
========

  * packing monomials for efficiency

For the programmer
==================

The object GRevLex, is a symbol.

Lex -- lexicographical monomial order.
**************************************

Description
===========

The lexicographic order is defined by: $x^A > x^B$ if the FIRST non-zero entry
of the vector of integers A-B is POSITIVE.
+----------------------------------------+
|i1 : R = QQ[a..d, MonomialOrder => Lex];|
+----------------------------------------+
|i2 : a^3 + a^2*b^2 + b*c                |
|                                        |
|      3    2 2                          |
|o2 = a  + a b  + b*c                    |
|                                        |
|o2 : R                                  |
+----------------------------------------+
The largest possible exponent of variables in Lex order is 2^31-1.  For
efficiency reasons, the size of the exponents of variables may be restricted.
Then instead of Lex, one can use  MonomialSize=>16, which allows maximal
exponent 2^15-1, or MonomialSize=>8, which allows maximal exponent 2^7-1.
+------------------------------------------------------+
|i3 : B = QQ[a..d,MonomialOrder=>Lex,MonomialSize=>16];|
+------------------------------------------------------+
|i4 : a^(2^15-1)                                       |
|                                                      |
|      32767                                           |
|o4 = a                                                |
|                                                      |
|o4 : B                                                |
+------------------------------------------------------+
|i5 : C = QQ[a..d,MonomialOrder=>Lex,MonomialSize=>8]; |
+------------------------------------------------------+
|i6 : try a^(2^15-1) else "failed"                     |
|                                                      |
|o6 = failed                                           |
+------------------------------------------------------+
|i7 : a^(2^7-1)                                        |
|                                                      |
|      127                                             |
|o7 = a                                                |
|                                                      |
|o7 : C                                                |
+------------------------------------------------------+
Any of these versions of Lex order may be combined, for example, with a weight
order given by a weight vector: x^A > x^B if weight(x^A) > weight(x^B) or if
weight(x^A) = weight(x^B) and if the FIRST non-zero entry of the vector of
integers A-B is POSITIVE.
+-----------------------------------------------------------------------------+
|i8 : B = QQ[a..d,MonomialSize=>16,MonomialOrder=>{Weights => {1,2,3,4},      |
|-----------------------------------------------------------------------------|
|Lex}];                                                                       |
+-----------------------------------------------------------------------------+
|i9 : a^2 + b+ c + b*d                                                        |
|                                                                             |
|                2                                                            |
|o9 = b*d + c + a  + b                                                        |
|                                                                             |
|o9 : B                                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * Weights -- assigning weights to the variables

For the programmer
==================

The object Lex, is a symbol.

GLex -- graded lexicographic ordering
*************************************

Description
===========

The option GLex => n is a shortcut for Weights => n:1, Lex=>n in creating a
monomial ordering,
+-------------------------------------+
|i1 : R = QQ[a..d,MonomialOrder=>GLex]|
|                                     |
|o1 = R                               |
|                                     |
|o1 : PolynomialRing                  |
+-------------------------------------+
|i2 : a^3*b+a^4+b^100                 |
|                                     |
|      100    4    3                  |
|o2 = b    + a  + a b                 |
|                                     |
|o2 : R                               |
+-------------------------------------+

See also
========

  * MonomialOrder -- monomial ordering

For the programmer
==================

The object GLex, is a symbol.

Weights -- assigning weights to the variables
*********************************************

Description
===========

Given a list L of n integers, the weight order on a polynomial ring in n
variables is defined by: x^A > x^B if A_1 L_1 + ... + A_n L_n > B_1 L_1 + ... +
B_n L_n.

The leading component of a polynomial under a weight order need not be a
monomial.  When two monomials have the same weight, by default they are further
distinguished with the GRevLex order.
+-----------------------------------------------------------------------+
|i1 : R = QQ[a..d,MonomialOrder=>{Weights => {-1,2,3,4}},Global=>false];|
+-----------------------------------------------------------------------+
|i2 : f = a^2 + b+ c^2 + b*d                                            |
|                                                                       |
|      2              2                                                 |
|o2 = c  + b*d + b + a                                                  |
|                                                                       |
|o2 : R                                                                 |
+-----------------------------------------------------------------------+
|i3 : leadTerm f                                                        |
|                                                                       |
|      2                                                                |
|o3 = c                                                                 |
|                                                                       |
|o3 : R                                                                 |
+-----------------------------------------------------------------------+
However, we can retrieve the entire leading component with the command
leadTerm(1,f). The plain leadTerm f is in this case the same as leadTerm(2,f):
they both use the full specification of the monomial ordering, first by weight
and then by the GRevLex order.  In contrast, leadTerm(1,f)only distinguishes
monomials by the first, i.e., weight, specification.
+-------------------------+
|i4 : leadTerm(1,ideal(f))|
|                         |
|o4 = | c2+bd |           |
|                         |
|             1      1    |
|o4 : Matrix R  <-- R     |
+-------------------------+
The weight order may be combined with further ordering elements to break ties.
In the following example, we use a second weight vector to break ties under
first weight vector.
+-----------------------------------------------------------------------------+
|i5 : R = QQ[a..d,MonomialOrder=>{Weights => {1,2,3,4}, Weights =>            |
|-----------------------------------------------------------------------------|
|{2,4,2,1}}];                                                                 |
+-----------------------------------------------------------------------------+
|i6 : f = a^6 + b^3+ c^2                                                      |
|                                                                             |
|      6    3    2                                                            |
|o6 = a  + b  + c                                                             |
|                                                                             |
|o6 : R                                                                       |
+-----------------------------------------------------------------------------+
|i7 : leadTerm(f)                                                             |
|                                                                             |
|      6                                                                      |
|o7 = a                                                                       |
|                                                                             |
|o7 : R                                                                       |
+-----------------------------------------------------------------------------+
|i8 : leadTerm(1, ideal(f))                                                   |
|                                                                             |
|o8 = | a6+b3+c2 |                                                            |
|                                                                             |
|             1      1                                                        |
|o8 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i9 : leadTerm(2, ideal(f))                                                   |
|                                                                             |
|o9 = | a6+b3 |                                                               |
|                                                                             |
|             1      1                                                        |
|o9 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i10 : leadTerm(3, ideal(f))                                                  |
|                                                                             |
|o10 = | a6 |                                                                 |
|                                                                             |
|              1      1                                                       |
|o10 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
leadTerm(3, ideal(f)) uses both the specified weights and the GRevLex order to
calculate the leading component.

When the number of weights is smaller than the number of variables, the
remaining variables are given weight 0. In the following example, c and d have
weight 0.
+----------------------------------------------------------+
|i11 : R = QQ[a..d,MonomialOrder=>{Weights => {1,2}, Lex}];|
+----------------------------------------------------------+
|i12 : f = a^2 + b+ c^2 + b*d                              |
|                                                          |
|       2              2                                   |
|o12 = a  + b*d + b + c                                    |
|                                                          |
|o12 : R                                                   |
+----------------------------------------------------------+

See also
========

  * leadTerm -- get the greatest term

Functions with optional argument named Weights:
===============================================

  * "betti(...,Weights=>...)" -- see betti(BettiTally),
    -- view and set the weight vector of a Betti diagram
  * "minimalBetti(...,Weights=>...)" -- see minimalBetti,
    -- minimal betti numbers of (the minimal free resolution of) a homogeneous
    ideal or module
  * monoid(...,Weights=>...),
    -- specify weights of the variables
  * "newRing(...,Weights=>...)" -- see newRing, -- make a copy
    of a ring, with some features changed
  * "regularity(...,Weights=>...)" -- see regularity, --
    compute the Castelnuovo-Mumford regularity
  * "symmetricAlgebra(...,Weights=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Weights=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Weights=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

For the programmer
==================

The object Weights, is a symbol.

Eliminate -- elimination order
******************************

Description
===========

The option Eliminate => n is a shortcut for Weights => {n:1} The remaining
variables are given weight 0.The monomial order is the elimination order
eliminating the first n variables, refined by the graded reverse lexicographic
order.
+------------------------------------------------+
|i1 : R = QQ[a..i, MonomialOrder => Eliminate 3];|
+------------------------------------------------+
This order enables intersections with the subring consisting of all but the
first 3 variables. For this, use the command selectInSubring.
+-------------------------------------+
|i2 : I = ideal(a^2, b-f, d^4, i - b);|
|                                     |
|o2 : Ideal of R                      |
+-------------------------------------+
|i3 : selectInSubring(1, gens gb I)   |
|                                     |
|o3 = | f-i d4 |                      |
|                                     |
|             1      2                |
|o3 : Matrix R  <-- R                 |
+-------------------------------------+
Eliminate may be combined with block orders as well.
+------------------------------------------------------+
|i4 : R = QQ[a..i, MonomialOrder => {Eliminate 3,4,2}];|
+------------------------------------------------------+
|i5 : d^3 - a*e^4 + b^2*i + a*c*d*f +a*c^2*g + a*c*g   |
|                                                      |
|        2               2               4    3        |
|o5 = a*c g + a*c*d*f + b i + a*c*g - a*e  + d         |
|                                                      |
|o5 : R                                                |
+------------------------------------------------------+
In the last example, the order is block order: the first four variables are in
the first block, the subsequent two variables are in the second block, the
remaining variables are in the third block, and the weights of the variables
are 1,1,1,0,..., 0. We illustrate the usage of selectInSubring.
+--------------------------------------+
|i6 : I = ideal(a..i)                  |
|                                      |
|o6 = ideal (a, b, c, d, e, f, g, h, i)|
|                                      |
|o6 : Ideal of R                       |
+--------------------------------------+
|i7 : selectInSubring(1, gens gb I);   |
|                                      |
|             1      6                 |
|o7 : Matrix R  <-- R                  |
+--------------------------------------+
|i8 : selectInSubring(2, gens gb I);   |
|                                      |
|             1      5                 |
|o8 : Matrix R  <-- R                  |
+--------------------------------------+
|i9 : selectInSubring(3, gens gb I);   |
|                                      |
|             1      3                 |
|o9 : Matrix R  <-- R                  |
+--------------------------------------+

Caveat
======

If the number of degree vectors is greater than one, this is currently only
graded using the first degree vector.  This will eventually change.

See also
========

  * Weights -- assigning weights to the variables
  * definition of product (block) orders
  * selectInSubring -- select columns in a subring

For the programmer
==================

The object Eliminate, is a self initializing type,
with ancestor classes BasicList, <
Thing.

GroupLex -- defines a ring where some variables are inverted
************************************************************

Description
===========

MonomialOrder => GroupLex => n inverts the first n variables in the polynomial
ring. In the following example, a^-1 is in the ring, but c^-1 is not.
+-----------------------------------------------+
|i1 : R = QQ[a..d, MonomialOrder=> GroupLex=>2];|
+-----------------------------------------------+
|i2 : a^-1                                      |
|                                               |
|      -1                                       |
|o2 = a                                         |
|                                               |
|o2 : R                                         |
+-----------------------------------------------+
|i3 : try c^(-1) else "failed"                  |
|                                               |
|o3 = failed                                    |
+-----------------------------------------------+

Caveat
======

The element a/b is in the fraction ring, while a*b^(-1) belongs to R.

Currently, one cannot compute Gröbner bases in this ring.

For the programmer
==================

The object GroupLex, is a symbol.

GroupRevLex
***********

Description
===========

MonomialOrder => GroupRevLex => n inverts the first n variables in the
polynomial ring. In the following example, a^-1 is in the ring, but c^-1 is
not.
+----------------------------------------------------------------+
|i1 : R = QQ[a..d, MonomialOrder=>GroupRevLex=>2, Global=>false];|
+----------------------------------------------------------------+
|i2 : a^-1                                                       |
|                                                                |
|      -1                                                        |
|o2 = a                                                          |
|                                                                |
|o2 : R                                                          |
+----------------------------------------------------------------+
|i3 : try c^(-1) else "failed"                                   |
|                                                                |
|o3 = failed                                                     |
+----------------------------------------------------------------+

Caveat
======

This feature has not been implemented yet.

For the programmer
==================

The object GroupRevLex, is a symbol.

definition of product (block) orders
************************************

MonomialOrder => {n_1, ..., n_l} divides the variables of the ring into l
blocks, the first block consisting of the first n_1 variables, the second block
consisting of the subsequent n_2 variables, and so on.  For each block of
variables, we can compute the total degree of a monomial with respect to the
variables in that block.  This gives a length l vector of total degrees for
each monomial.  We say x^A > x^B if the total degree vector of x^A is
lexicographically greater than the total degree vector of x^B, or if the two
total degree vectors are equal and if in the first block of variables where A
and B differ, A > B in GRevLex order.
+----------------------------------------------+
|i1 : R = QQ[a..l, MonomialOrder => {3,3,3,3}];|
+----------------------------------------------+
|i2 : a*e^3 + a^2*c*i + a*b^2*i + b^2*e*i      |
|                                              |
|        2     2       2         3             |
|o2 = a*b i + a c*i + b e*i + a*e              |
|                                              |
|o2 : R                                        |
+----------------------------------------------+
We may replace MonomialOrder => {3,3,3,3} with the shorter MonomialOrder =>
{4:3}

The default GRevLex order on any block may be changed to other orders, as
follows.
+------------------------------------------------------------+
|i3 : R = QQ[a..i, MonomialOrder => {Lex =>3,3:1,3}];        |
+------------------------------------------------------------+
|i4 : a*e^3 + a^2*c*i + a*b^2*i + b^2*e*i + d^2*f*h + d*e^2*h|
|                                                            |
|      2         2       3    2       2         2            |
|o4 = a c*i + a*b i + a*e  + b e*i + d f*h + d*e h           |
|                                                            |
|o4 : R                                                      |
+------------------------------------------------------------+
Note: Weights and Eliminate do not create blocks, they only assign weights to
the variables.

See also
========

  * Weights -- assigning weights to the variables
  * Eliminate -- elimination order

RevLex -- reverse lexicographic ordering
****************************************

Description
===========

The reverse lexicographic order is defined by: $x^A > x^B$ if the FIRST
non-zero entry of the vector of integers A-B is NEGATIVE. This is a local
order, not a global order.  Therefore Gröbner bases over this ring only give
generators over the local ring whose fractions are all elements not in the
ideal generated by the variables.
+-----------------------------------------------------------+
|i1 : R = QQ[a..d,MonomialOrder => RevLex, Global => false];|
+-----------------------------------------------------------+
|i2 : a^3 + b^2 + b*c + a*c^2 + b^2*c + a + b + c           |
|                                                           |
|                    2    2           2    3                |
|o2 = c + b + b*c + b  + b c + a + a*c  + a                 |
|                                                           |
|o2 : R                                                     |
+-----------------------------------------------------------+
Computations of Gröbner bases for local orders are done using Mora's algorithm.

See also
========

  * GRevLex -- graded reverse lexicographical monomial order.
  * Global -- monomial ordering

For the programmer
==================

The object RevLex, is a symbol.

NCLex -- Non-commutative lexicographical order.
***********************************************

Description
===========

This feature has not been implemented yet.

For the programmer
==================

The object NCLex, is a symbol.

MonomialOrder -- monomial ordering
**********************************

Description
===========

MonomialOrder -- an optional argument used with polynomial rings and monoids to
indicate a monomial ordering other than the default (graded reverse
lexicographic).

In Macaulay2, each polynomial ring (and also each monoid) is equipped with a
monomial order, which is used for display of polynomials (terms are listed in
descending monomial order), and also for Gröbner basis computations.

In the most general setting, a monomial ordering is given by a list of ordering
tests, of various types listed and described below, each of which provides a
partial ordering on the monomials.  The ordering tests are applied
sequentially, starting with the first one, until one monomial is judged greater
than the other. At the end, if necessary, the graded reverse lexicographic
order is used to compare the monomials. For examples, see below, or see
monomial orderings.

Permissible elements:
  * GRevLex, => n -- A graded reverse lexicographic block of
    variables
  * Lex, => n
  * Weights, => {...}
  * Position, => Up  or  Position => Down
  * RevLex, => n
  * GroupLex, => n
  * GroupRevLex, => n
  * MonomialSize, => n, n being 8,16,32, or 64.  Set the
    packing size for exponents for further variables

Some examples of monomial orders.  Note that if only one item is in the list,
we can dispense with the list.
  * MonomialOrder => {GRevLex=>2, GRevLex=>3} -- a product order
  * MonomialOrder => {2, 3} -- same
  * MonomialOrder => {Weights=>{1,13,6,2}} -- a weight order
  * MonomialOrder => Weights=>{1,13,6,2} -- same
If any monomials will be less than 1 in the ordering, then the option Global =>
false should be used.
+------------------------------------------------+
|i1 : QQ[x,y, Weights => {-1,1}, Global => false]|
|                                                |
|o1 = QQ[x..y]                                   |
|                                                |
|o1 : PolynomialRing                             |
+------------------------------------------------+
|i2 : x<1                                        |
|                                                |
|o2 = true                                       |
+------------------------------------------------+
|i3 : y<1                                        |
|                                                |
|o3 = false                                      |
+------------------------------------------------+

See also
========

  * monomial orderings
  * weightGrevlex (QthPower) -- transform a weight matrix
    into a monomial ordering matrix
  * grevlexWeight (QthPower) -- transform a weight matrix
    into a monomial ordering matrix

Functions with optional argument named MonomialOrder:
=====================================================

  * "graphIdeal(...,MonomialOrder=>...)" -- see graphIdeal(RingMap),
    -- the ideal of the graph of the regular map
    corresponding to a ring map
  * "graphRing(...,MonomialOrder=>...)" -- see graphRing(RingMap),
    -- the coordinate ring of the graph of the regular
    map corresponding to a ring map
  * monoid(...,MonomialOrder=>...)
    -- specify the monomial
    ordering
  * "newRing(...,MonomialOrder=>...)" -- see newRing, -- make a
    copy of a ring, with some features changed
  * "pushForward(...,MonomialOrder=>...)" -- see
    pushForward(RingMap,Module),
  * rsort(...,MonomialOrder=>...)
    -- specify Ascending or
    Descending monomial order
  * sort(...,MonomialOrder=>...)
    -- specify Ascending or
    Descending monomial order
  * sortColumns(...,MonomialOrder=>...)
    -- specify Ascending
    or Descending monomial order
  * "symmetricAlgebra(...,MonomialOrder=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,MonomialOrder=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids
  * "tensor(Ring,Ring,MonomialOrder=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

For the programmer
==================

The object MonomialOrder, is a symbol.

obtaining the monomial order of a ring
**************************************

The monomial order of a ring is stored as an option.
+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_1 .. x_10, MonomialOrder=>{4,6}];                              |
+-----------------------------------------------------------------------------+
|i2 : options R                                                               |
|                                                                             |
|o2 = OptionTable{Constants => false                                          |
|                                  1                                          |
|                 DegreeGroup => ZZ                                           |
|                 DegreeLift => null                                          |
|                 DegreeMap => null                                           |
|                 DegreeRank => 1                                             |
|                 Degrees => {{1}, {1}, {1}, {1}, {1}, {1}, {1}, {1}, {1},    |
|                 Global => true                                              |
|                 Heft => {1}                                                 |
|                 Inverses => false                                           |
|                 Join => null                                                |
|                 Local => false                                              |
|                 MonomialOrder => {MonomialSize => 32           }            |
|                                  {GRevLex => {1, 1, 1, 1}      }            |
|                                  {GRevLex => {1, 1, 1, 1, 1, 1}}            |
|                                  {Position => Up               }            |
|                 SkewCommutative => {}                                       |
|                 Variables => {x , x , x , x , x , x , x , x , x , x  }      |
|                                1   2   3   4   5   6   7   8   9   10       |
|                 WeylAlgebra => {}                                           |
|                                                                             |
|o2 : OptionTable                                                             |
|-----------------------------------------------------------------------------|
|    }                                                                        |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|{1}}                                                                         |
+-----------------------------------------------------------------------------+
|i3 : (options R).MonomialOrder                                               |
|                                                                             |
|o3 = {MonomialSize => 32           }                                         |
|     {GRevLex => {1, 1, 1, 1}      }                                         |
|     {GRevLex => {1, 1, 1, 1, 1, 1}}                                         |
|     {Position => Up               }                                         |
|                                                                             |
|o3 : VerticalList                                                            |
+-----------------------------------------------------------------------------+
|i4 : S = QQ[a..d];                                                           |
+-----------------------------------------------------------------------------+
|i5 : (options S).MonomialOrder                                               |
|                                                                             |
|o5 = {MonomialSize => 32     }                                               |
|     {GRevLex => {1, 1, 1, 1}}                                               |
|     {Position => Up         }                                               |
|                                                                             |
|o5 : VerticalList                                                            |
+-----------------------------------------------------------------------------+

graded and multigraded polynomial rings
***************************************

It is possible to set up a polynomial ring so that the degree of an element is
a vector of integers.  For this, the option Degrees, is used,
together with a list of degrees for the variables in the ring.  Each degree is
itself a list of integers.  The degrees given must all be of the same length,
and length zero is allowed, to get an ungraded ring.
+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c,Degrees=>{{1,2},{2,1},{1,0}}]                          |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : describe R                                                              |
|                                                                             |
|      ZZ                                                                     |
|o2 = ---[a..c, Degrees => {{1}, {2}, {1}}, Heft => {1, 0}, MonomialOrder =>  |
|     101                   {2}  {1}  {0}                                     |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32  }]                                                      |
|{GRevLex => {1..2, 1}}                                                       |
|{Position => Up      }                                                       |
+-----------------------------------------------------------------------------+
+-------------------+
|i3 : degree a      |
|                   |
|o3 = {1, 2}        |
|                   |
|o3 : List          |
+-------------------+
|i4 : degree b^2    |
|                   |
|o4 = {4, 2}        |
|                   |
|o4 : List          |
+-------------------+
|i5 : degree 0_R    |
|                   |
|o5 = -infinity     |
|                   |
|o5 : InfiniteNumber|
+-------------------+
|i6 : degree 1_R    |
|                   |
|o6 = {0, 0}        |
|                   |
|o6 : List          |
+-------------------+
A random element of bi-degree {m,n} can be obtained with random.
+-----------------------------------+
|i7 : random({15,15},R)             |
|                                   |
|          5 5      6 3 3      7   6|
|o7 = - 30a b  - 36a b c  + 24a b*c |
|                                   |
|o7 : R                             |
+-----------------------------------+
The function degree, applied to a polynomial will return the
least upper bound of the degrees of its monomials.
+-----------------+
|i8 : degree (a+b)|
|                 |
|o8 = {2, 2}      |
|                 |
|o8 : List        |
+-----------------+
We may recover the number of integers in each degree list for our ring as
follows.
+---------------------+
|i9 : degreeLength R  |
|                     |
|o9 = 2               |
+---------------------+
|i10 : degreeLength ZZ|
|                     |
|o10 = 0              |
+---------------------+
One restriction on degrees of variables is that the entries be small integer
values, possibly zero or negative.  The notion of small depends on the size of
exponents one wants: the degree of each monomial occurring should fit in a 32
bit integer (or 64 bit integer, on 64 bit machines).

Another restriction on degrees, at least if all the computational facilities of
Macaulay2 are needed, is that a heft vector exists for them.  A heft vector is
a list of integers whose length is the same as the length of the degrees (see
degreeLength), such that its dot product with the degree
of each variable is positive.  Heft vectors are computed automatically for you,
as in the following example, or they may be provided by the user (see
Heft).

+---------------------------------------------------+
|i11 : R = QQ[a,b,c,Degrees=>{{1,0},{-2,1},{-3,1}}];|
+---------------------------------------------------+
|i12 : random({1,1},R)                              |
|                                                   |
|      1 3    9 4                                   |
|o12 = -a b + -a c                                  |
|      2      4                                     |
|                                                   |
|o12 : R                                            |
+---------------------------------------------------+
|i13 : basis({1,1},R)                               |
|                                                   |
|o13 = | a4c a3b |                                  |
|                                                   |
|              1      2                             |
|o13 : Matrix R  <-- R                              |
+---------------------------------------------------+

The heft vector computed behind the scenes is available to the user.

+----------------------+
|i14 : (options R).Heft|
|                      |
|o14 = {1, 4}          |
|                      |
|o14 : List            |
+----------------------+

If the heft vector is not provided, many computations will work (e.g., Gröbner
bases and computation of resolutions), but certain other operations (such as
basis and random) will raise errors.

heft vectors
************

A heft vector for a polynomial ring is a vector with integer entries, of the
same length as the degree vectors of the variables of the ring, whose dot
product with each of them is (strictly) positive. Unless one is specified
explicitly, then a good one will be found automatically. The heft vector is
used in various internal algorithms, such as the one in basis, as
a way of organizing the sequence of steps, proceeding incrementally to larger
values of the dot product of the degree of a monomial with the heft vector.

+---------------------------------------------------------------+
|i1 : R = QQ[a..d];                                             |
+---------------------------------------------------------------+
|i2 : degrees R                                                 |
|                                                               |
|o2 = {{1}, {1}, {1}, {1}}                                      |
|                                                               |
|o2 : List                                                      |
+---------------------------------------------------------------+
|i3 : heft R                                                    |
|                                                               |
|o3 = {1}                                                       |
|                                                               |
|o3 : List                                                      |
+---------------------------------------------------------------+
|i4 : S = QQ[a..d, DegreeRank => 4];                            |
+---------------------------------------------------------------+
|i5 : degrees S                                                 |
|                                                               |
|o5 = {{1, 0, 0, 0}, {0, 1, 0, 0}, {0, 0, 1, 0}, {0, 0, 0, 1}}  |
|                                                               |
|o5 : List                                                      |
+---------------------------------------------------------------+
|i6 : heft S                                                    |
|                                                               |
|o6 = {1, 1, 1, 1}                                              |
|                                                               |
|o6 : List                                                      |
+---------------------------------------------------------------+
|i7 : T = QQ[a,b, Degrees => {1,-1}]                            |
|                                                               |
|o7 = T                                                         |
|                                                               |
|o7 : PolynomialRing                                            |
+---------------------------------------------------------------+
|i8 : degrees T                                                 |
|                                                               |
|o8 = {{1}, {-1}}                                               |
|                                                               |
|o8 : List                                                      |
+---------------------------------------------------------------+
|i9 : heft T                                                    |
+---------------------------------------------------------------+
|i10 : U = QQ[a..d, Degrees => {{2,0}, {1,-1}, {0,-2}, {-1,-3}}]|
|                                                               |
|o10 = U                                                        |
|                                                               |
|o10 : PolynomialRing                                           |
+---------------------------------------------------------------+
|i11 : degrees U                                                |
|                                                               |
|o11 = {{2, 0}, {1, -1}, {0, -2}, {-1, -3}}                     |
|                                                               |
|o11 : List                                                     |
+---------------------------------------------------------------+
|i12 : heft U                                                   |
|                                                               |
|o12 = {3, -2}                                                  |
|                                                               |
|o12 : List                                                     |
+---------------------------------------------------------------+

The heft vector, multiplied by -1, is used as the weight vector in the monomial
ordering of the degrees ring, and the order of the series expansions of the
Hilbert series refers to the weight formed with respect to that weight vector.

+-----------------------------------------------------------------------------+
|i13 : hilbertSeries U                                                        |
|                                                                             |
|                          1                                                  |
|o13 = ----------------------------------------                               |
|            2         -1       -2       -1 -3                                |
|      (1 - T )(1 - T T  )(1 - T  )(1 - T  T  )                               |
|            0       0 1        1        0  1                                 |
|                                                                             |
|o13 : Expression of class Divide                                             |
+-----------------------------------------------------------------------------+
|i14 : describe ring numerator oo                                             |
|                                                                             |
|o14 = ZZ[T ..T , Degrees => {3, -2}, MonomialOrder => {MonomialSize => 32},  |
|          0   1                                       {Weights => {-3, 2}}   |
|                                                      {GroupLex => 2     }   |
|                                                      {Position => Up    }   |
|-----------------------------------------------------------------------------|
|Inverses => true, Global => false]                                           |
+-----------------------------------------------------------------------------+
|i15 : hilbertSeries(U, Order => 8)                                           |
|                                                                             |
|           -1 -3    -2      -1    2    -2 -6    -1 -5                        |
|o15 = 1 + T  T   + T   + T T   + T  + T  T   + T  T                          |
|           0  1     1     0 1     0    0  1     0  1                         |
|                                                                             |
|o15 : ZZ[T ..T ]                                                             |
|          0   1                                                              |
+-----------------------------------------------------------------------------+

The heft vector is used in the computation of degrees of modules over a
polynomial ring R, because it gives a homomorphism from the degrees ring of R
to the Laurent polynomial ring in one variable T that sends monomials
corresponding to the degrees of variables of R to positive powers of T. See
degree(Module).

+-------------------------------+
|i16 : R = QQ[x,y, Heft => {3}];|
+-------------------------------+
|i17 : degree ideal x           |
|                               |
|o17 = 3                        |
+-------------------------------+

See also
========

  * monoid(...,Heft=>...), --
    specify a heft vector
  * degreesRing -- the ring or monoid of degrees
  * multidegree -- multidegree
  * hilbertSeries(...,Order=>...)
    -- display the truncated
    power series expansion

heft -- heft vector of ring or monoid
*************************************

Synopsis
========

  * Usage:
        heft R
  * Inputs:
      * R, a ring, or a monoid,
  * Outputs:
      * a list, a weight co-vector of integers with length the
        same as degree length, of R, or
      * null, if there is no heft vector.

Description
===========

heft returns the heft vector, in use for R,

+-------------------------------------------------------------+
|i1 : S = QQ[a..d, DegreeRank => 4];                          |
+-------------------------------------------------------------+
|i2 : degrees S                                               |
|                                                             |
|o2 = {{1, 0, 0, 0}, {0, 1, 0, 0}, {0, 0, 1, 0}, {0, 0, 0, 1}}|
|                                                             |
|o2 : List                                                    |
+-------------------------------------------------------------+
|i3 : heft S                                                  |
|                                                             |
|o3 = {1, 1, 1, 1}                                            |
|                                                             |
|o3 : List                                                    |
+-------------------------------------------------------------+

See also
========

  * findHeft -- find a heft vector for a list of degrees

Ways to use heft:
=================

  * "heft(Monoid)"
  * "heft(PolynomialRing)"
  * "heft(QuotientRing)"
  * "heft(Ring)"

For the programmer
==================

The object heft, is a method function.

findHeft -- find a heft vector for a list of degrees
****************************************************

Synopsis
========

  * Usage:
        findHeft(degs, DegreeRank => r)
  * Inputs:
      * degs, a list, of multi-degrees, each of which is a list of
        integers of fixed length r
  * Optional inputs,:
      * DegreeRank => an integer, default value null
      * DegreeGroup (missing documentation) => ..., default value null,
  * Outputs:
      * a list, of integers of length r, or
      * null, if there is none

Description
===========

findHeft returns a weight co-vector whose dot product with each member of degs
is strictly positive.

+-----------------------------------------------+
|i1 : findHeft({{-1,0}, {2,1}}, DegreeRank => 2)|
|                                               |
|o1 = {-1, 3}                                   |
|                                               |
|o1 : List                                      |
+-----------------------------------------------+
|i2 : findHeft({}, DegreeRank => 0)             |
|                                               |
|o2 = {}                                        |
|                                               |
|o2 : List                                      |
+-----------------------------------------------+

See also
========

  * heft -- heft vector of ring or monoid

Ways to use findHeft:
=====================

  * "findHeft(List)"

For the programmer
==================

The object findHeft, is a method function with options.

quotient rings
**************

The usual notation is used to form quotient rings.  For quotients of polynomial
rings, a Gröbner basis is computed and used to reduce ring elements to normal
form after arithmetic operations.
+-----------------+
|i1 : R = ZZ/11   |
|                 |
|o1 = R           |
|                 |
|o1 : QuotientRing|
+-----------------+
|i2 : 6_R + 7_R   |
|                 |
|o2 = 2           |
|                 |
|o2 : R           |
+-----------------+
+------------------------------------------+
|i3 : S = QQ[x,y,z]/(x^2-y, y^3-z)         |
|                                          |
|o3 = S                                    |
|                                          |
|o3 : QuotientRing                         |
+------------------------------------------+
|i4 : {1,x,x^2,x^3,x^4,x^5,x^6,x^7,x^8}    |
|                                          |
|                     2     2              |
|o4 = {1, x, y, x*y, y , x*y , z, x*z, y*z}|
|                                          |
|o4 : List                                 |
+------------------------------------------+
In the example above you might have wondered whether typing x would give an
element of S or an element of QQ[x,y,z].  Our convention is that typing x gives
an element of the last ring that has been assigned to a global variable.  Here
is another example.
+----------------------+
|i5 : T = ZZ/101[r,s,t]|
|                      |
|o5 = T                |
|                      |
|o5 : PolynomialRing   |
+----------------------+
|i6 : T/(r^3+s^3+t^3)  |
|                      |
|           T          |
|o6 = ------------     |
|      3    3    3     |
|     r  + s  + t      |
|                      |
|o6 : QuotientRing     |
+----------------------+
|i7 : r^3+s^3+t^3      |
|                      |
|      3    3    3     |
|o7 = r  + s  + t      |
|                      |
|o7 : T                |
+----------------------+
Notice that this time, the variables end up in the ring T, because we didn't
assign the quotient ring to a global variable.  The command use,
would install the variables for us, or we could assign the ring to a global
variable.
+-----------------+
|i8 : U = ooo     |
|                 |
|o8 = U           |
|                 |
|o8 : QuotientRing|
+-----------------+
|i9 : r^3+s^3+t^3 |
|                 |
|o9 = 0           |
|                 |
|o9 : U           |
+-----------------+
The functions lift, and substitute, can be used
to transfer elements between the polynomial ring and its quotient ring.
+-------------------------+
|i10 : lift("r"_U,T)      |
|                         |
|o10 = r                  |
|                         |
|o10 : T                  |
+-------------------------+
|i11 : substitute("r"_T,U)|
|                         |
|o11 = r                  |
|                         |
|o11 : U                  |
+-------------------------+
A random element of degree n can be obtained with random.
+-----------------------------------+
|i12 : random(2,S)                  |
|                                   |
|      9      9 2   1      1       2|
|o12 = -x*y + -y  + -x*z + -y*z + z |
|      2      4     2      2        |
|                                   |
|o12 : S                            |
+-----------------------------------+
In a program we can tell whether a ring is a quotient ring.
+-----------------------+
|i13 : isQuotientRing ZZ|
|                       |
|o13 = false            |
+-----------------------+
|i14 : isQuotientRing S |
|                       |
|o14 = true             |
+-----------------------+
We can recover the ring of which a given ring is a quotient.
+--------------------+
|i15 : ambient S     |
|                    |
|o15 = QQ[x..z]      |
|                    |
|o15 : PolynomialRing|
+--------------------+
We can also recover the coefficient ring, as we could for the original
polynomial ring.
+-----------------------+
|i16 : coefficientRing S|
|                       |
|o16 = QQ               |
|                       |
|o16 : Ring             |
+-----------------------+
Here's how we can tell whether the defining relations of a quotient ring were
homogeneous.
+---------------------+
|i17 : isHomogeneous S|
|                     |
|o17 = false          |
+---------------------+
|i18 : isHomogeneous U|
|                     |
|o18 = true           |
+---------------------+
We can obtain the characteristic of a ring with char.
+------------------+
|i19 : char (ZZ/11)|
|                  |
|o19 = 11          |
+------------------+
|i20 : char S      |
|                  |
|o20 = 0           |
+------------------+
|i21 : char U      |
|                  |
|o21 = 101         |
+------------------+
The presentation of the quotient ring can be obtained as a matrix with
presentation.
+----------------------------------------+
|i22 : presentation S                    |
|                                        |
|o22 = | x2-y y3-z |                     |
|                                        |
|                       1               2|
|o22 : Matrix (QQ[x..z])  <-- (QQ[x..z]) |
+----------------------------------------+
If a quotient ring has redundant defining relations, a new ring can be made in
which these are eliminated with trim.
+-------------------------------------+
|i23 : R = ZZ/101[x,y,z]/(x-y,y-z,z-x)|
|                                     |
|o23 = R                              |
|                                     |
|o23 : QuotientRing                   |
+-------------------------------------+
|i24 : trim R                         |
|                                     |
|          ZZ                         |
|         ---[x..z]                   |
|         101                         |
|o24 = --------------                 |
|      (y - z, x - z)                 |
|                                     |
|o24 : QuotientRing                   |
+-------------------------------------+
For more information see QuotientRing.

manipulating polynomials
************************

  * + -- a unary or binary operator, usually used for addition
  * - -- a unary or binary operator, usually used for negation or
    subtraction
  * * -- a binary operator, usually used for multiplication
  * ^ -- a binary operator, usually used for powers
  * // -- a binary operator, usually used for quotient
  * % -- a binary operator, usually used for remainder and reduction
  * terms -- provide a list of terms of a polynomial
  * diff -- differentiate or take difference
  * listForm -- convert to list form
  * degree
  * homogenize -- homogenize with respect to a variable
  * exponents -- the exponents of a polynomial
  * leadCoefficient -- the coefficient of the leading
    term
  * leadTerm -- get the greatest term
  * size -- the size of an object
Let's set up some polynomials.
+----------------------------------------------------------------+
|i1 : R = ZZ/10007[a,b];                                         |
+----------------------------------------------------------------+
|i2 : f = (2*a+3)^4 + 5                                          |
|                                                                |
|        4      3       2                                        |
|o2 = 16a  + 96a  + 216a  + 216a + 86                            |
|                                                                |
|o2 : R                                                          |
+----------------------------------------------------------------+
|i3 : g = (2*a+b+1)^3                                            |
|                                                                |
|       3      2        2    3      2             2              |
|o3 = 8a  + 12a b + 6a*b  + b  + 12a  + 12a*b + 3b  + 6a + 3b + 1|
|                                                                |
|o3 : R                                                          |
+----------------------------------------------------------------+
The number of terms in a polynomial is obtained with size.
+-------------------+
|i4 : size f, size g|
|                   |
|o4 = (5, 10)       |
|                   |
|o4 : Sequence      |
+-------------------+
The degree of a polynomial is obtained with degree.
+-------------+
|i5 : degree f|
|             |
|o5 = {4}     |
|             |
|o5 : List    |
+-------------+
|i6 : degree g|
|             |
|o6 = {3}     |
|             |
|o6 : List    |
+-------------+
(Notice that the degree is a list containing one integer, rather than an
integer.  The degree is actually a vector of integers, represented as a list,
with one component by default.)

The list of terms of a polynomial is obtained with terms.
+---------------------------------------------------------+
|i7 : terms g                                             |
|                                                         |
|        3     2       2   3     2           2            |
|o7 = {8a , 12a b, 6a*b , b , 12a , 12a*b, 3b , 6a, 3b, 1}|
|                                                         |
|o7 : List                                                |
+---------------------------------------------------------+
We may combine that with select, to select terms satisfying
certain conditions.  Here we select the terms of degree 2, subsequently summing
them, keeping in mind that the degree of a polynomial is always a list of
integers.
+------------------------------------------+
|i8 : select(terms g, i -> degree i == {2})|
|                                          |
|         2           2                    |
|o8 = {12a , 12a*b, 3b }                   |
|                                          |
|o8 : List                                 |
+------------------------------------------+
|i9 : sum oo                               |
|                                          |
|        2             2                   |
|o9 = 12a  + 12a*b + 3b                    |
|                                          |
|o9 : R                                    |
+------------------------------------------+
Of course, if the list of selected terms is empty, the sum would turn out to be
the zero integer, rather than the zero element of the ring R. Fortunately, we
have another way to select the elements of given degree or multi-degree (see
part).
+------------------------------+
|i10 : part(0,g)               |
|                              |
|o10 = 1                       |
|                              |
|o10 : R                       |
+------------------------------+
|i11 : part(1,g)               |
|                              |
|o11 = 6a + 3b                 |
|                              |
|o11 : R                       |
+------------------------------+
|i12 : part(2,g)               |
|                              |
|         2             2      |
|o12 = 12a  + 12a*b + 3b       |
|                              |
|o12 : R                       |
+------------------------------+
|i13 : part(3,g)               |
|                              |
|        3      2        2    3|
|o13 = 8a  + 12a b + 6a*b  + b |
|                              |
|o13 : R                       |
+------------------------------+
A string representing the polynomial, suitable for entry into other programs,
can be obtained with toString.
+--------------------------------------------------------------+
|i14 : toString f                                              |
|                                                              |
|o14 = 16*a^4+96*a^3+216*a^2+216*a+86                          |
+--------------------------------------------------------------+
|i15 : toString g                                              |
|                                                              |
|o15 = 8*a^3+12*a^2*b+6*a*b^2+b^3+12*a^2+12*a*b+3*b^2+6*a+3*b+1|
+--------------------------------------------------------------+

The usual algebraic operations on polynomials are available, but there are some
special remarks to make about division.  The result of division depends on the
ordering of monomials chosen when the ring is created, for division of f by g
proceeds by locating monomials in f divisible by the leading monomial of g, and
substituting for it the negation of the rest of g.  The quotient is provided by
the expression f//g, and the remainder is obtained with f%g.
+-----------------------------------------------------------------------------+
|i16 : quot = f//g                                                            |
|                                                                             |
|o16 = 2a - 3b + 9                                                            |
|                                                                             |
|o16 : R                                                                      |
+-----------------------------------------------------------------------------+
|i17 : rem = f%g                                                              |
|                                                                             |
|         2 2        3     4      2         2      2              2           |
|o17 = 24a b  + 16a*b  + 3b  - 96a b - 24a*b  + 96a  - 96a*b - 18b  + 160a -  |
|      -----------------------------------------------------------------------|
|      24b + 77                                                               |
|                                                                             |
|o17 : R                                                                      |
+-----------------------------------------------------------------------------+
|i18 : f == quot * g + rem                                                    |
|                                                                             |
|o18 = true                                                                   |
+-----------------------------------------------------------------------------+
Notice that as in the example above, comparison of polynomials is done with the
operator ==.

Polynomials can be homogenized with respect to one of the variables in the ring
with homogenize.
+---------------------------------------------+
|i19 : homogenize(f,b)                        |
|                                             |
|         4      3        2 2         3      4|
|o19 = 16a  + 96a b + 216a b  + 216a*b  + 86b |
|                                             |
|o19 : R                                      |
+---------------------------------------------+

The ring containing a ring element can be obtained with ring.
+--------------------+
|i20 : ring f        |
|                    |
|o20 = R             |
|                    |
|o20 : PolynomialRing|
+--------------------+
You can use this in a program to check whether two ring elements come from the
same ring.
+-----------------------+
|i21 : ring f === ring g|
|                       |
|o21 = true             |
+-----------------------+
Notice that in the comparison above, the strict equality operator ===,
is used.

The coefficient of a monomial in a polynomial can be obtained with _.
+---------------+
|i22 : part(1,f)|
|               |
|o22 = 216a     |
|               |
|o22 : R        |
+---------------+
|i23 : f_a      |
|               |
|o23 = 216      |
|               |
|        ZZ     |
|o23 : -----    |
|      10007    |
+---------------+
|i24 : g_(a*b)  |
|               |
|o24 = 12       |
|               |
|        ZZ     |
|o24 : -----    |
|      10007    |
+---------------+
(Notice that the coefficients are elements of the coefficient ring.)

We may get parts of the leading term of a polynomial as follows.
+-----------------------+
|i25 : leadTerm g       |
|                       |
|        3              |
|o25 = 8a               |
|                       |
|o25 : R                |
+-----------------------+
|i26 : leadCoefficient g|
|                       |
|o26 = 8                |
|                       |
|        ZZ             |
|o26 : -----            |
|      10007            |
+-----------------------+
|i27 : leadMonomial g   |
|                       |
|       3               |
|o27 = a                |
|                       |
|o27 : R                |
+-----------------------+
The exponents of a monomial or term can be extracted with exponents.
+------------------------------+
|i28 : exponents leadMonomial g|
|                              |
|o28 = {{3, 0}}                |
|                              |
|o28 : List                    |
+------------------------------+
|i29 : exponents leadTerm g    |
|                              |
|o29 = {{3, 0}}                |
|                              |
|o29 : List                    |
+------------------------------+
We can get all of the coefficients at once, assembled in a one-rowed matrix,
along with a matrix containing the corresponding monomials.
+----------------------------------------------------+
|i30 : coefficients f                                |
|                                                    |
|o30 = (| a4 a3 a2 a 1 |, {4} | 16  |)               |
|                         {3} | 96  |                |
|                         {2} | 216 |                |
|                         {1} | 216 |                |
|                         {0} | 86  |                |
|                                                    |
|o30 : Sequence                                      |
+----------------------------------------------------+
|i31 : coefficients g                                |
|                                                    |
|o31 = (| a3 a2b ab2 b3 a2 ab b2 a b 1 |, {3} | 8  |)|
|                                         {3} | 12 | |
|                                         {3} | 6  | |
|                                         {3} | 1  | |
|                                         {2} | 12 | |
|                                         {2} | 12 | |
|                                         {2} | 3  | |
|                                         {1} | 6  | |
|                                         {1} | 3  | |
|                                         {0} | 1  | |
|                                                    |
|o31 : Sequence                                      |
+----------------------------------------------------+
A list of lists of exponents appearing in a polynomial can be obtained with
exponents.
+-----------------------------------------------------------------------------+
|i32 : exponents f                                                            |
|                                                                             |
|o32 = {{4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}}                               |
|                                                                             |
|o32 : List                                                                   |
+-----------------------------------------------------------------------------+
|i33 : exponents g                                                            |
|                                                                             |
|o33 = {{3, 0}, {2, 1}, {1, 2}, {0, 3}, {2, 0}, {1, 1}, {0, 2}, {1, 0}, {0,   |
|      -----------------------------------------------------------------------|
|      1}, {0, 0}}                                                            |
|                                                                             |
|o33 : List                                                                   |
+-----------------------------------------------------------------------------+
The entire structure of a polynomial can be provided in an accessible form
based on lists with listForm.
+-----------------------------------------------------------------------------+
|i34 : listForm f                                                             |
|                                                                             |
|o34 = {({4, 0}, 16), ({3, 0}, 96), ({2, 0}, 216), ({1, 0}, 216), ({0, 0},    |
|      -----------------------------------------------------------------------|
|      86)}                                                                   |
|                                                                             |
|o34 : List                                                                   |
+-----------------------------------------------------------------------------+
|i35 : S = listForm g                                                         |
|                                                                             |
|o35 = {({3, 0}, 8), ({2, 1}, 12), ({1, 2}, 6), ({0, 3}, 1), ({2, 0}, 12),    |
|      -----------------------------------------------------------------------|
|      ({1, 1}, 12), ({0, 2}, 3), ({1, 0}, 6), ({0, 1}, 3), ({0, 0}, 1)}      |
|                                                                             |
|o35 : List                                                                   |
+-----------------------------------------------------------------------------+
The lists above are lists of pairs, where the first member of each pair is a
list of exponents in a monomial, and the second member is the corresponding
coefficient.  Standard list operations can be used to manipulate the result.
+----------------+
|i36 : S / print;|
|({3, 0}, 8)     |
|({2, 1}, 12)    |
|({1, 2}, 6)     |
|({0, 3}, 1)     |
|({2, 0}, 12)    |
|({1, 1}, 12)    |
|({0, 2}, 3)     |
|({1, 0}, 6)     |
|({0, 1}, 3)     |
|({0, 0}, 1)     |
+----------------+
The structure of a polynomial can also be provided in a form based on hash
tables with standardForm.
+-----------------------------------------+
|i37 : S = standardForm f                 |
|                                         |
|o37 = HashTable{HashTable{} => 86       }|
|                HashTable{0 => 1} => 216 |
|                HashTable{0 => 2} => 216 |
|                HashTable{0 => 3} => 96  |
|                HashTable{0 => 4} => 16  |
|                                         |
|o37 : HashTable                          |
+-----------------------------------------+
|i38 : standardForm g                     |
|                                         |
|o38 = HashTable{HashTable{} => 1       } |
|                HashTable{0 => 1} => 12  |
|                          1 => 1         |
|                HashTable{0 => 1} => 6   |
|                          1 => 2         |
|                HashTable{0 => 1} => 6   |
|                HashTable{0 => 2} => 12  |
|                          1 => 1         |
|                HashTable{0 => 2} => 12  |
|                HashTable{0 => 3} => 8   |
|                HashTable{1 => 1} => 3   |
|                HashTable{1 => 2} => 3   |
|                HashTable{1 => 3} => 1   |
|                                         |
|o38 : HashTable                          |
+-----------------------------------------+
The hash tables above present the same information, except that only nonzero
exponents need to be provided.  The information can be extracted with #.
+-------------------------------------+
|i39 : S#(new HashTable from {0 => 2})|
|                                     |
|o39 = 216                            |
|                                     |
|        ZZ                           |
|o39 : -----                          |
|      10007                          |
+-------------------------------------+

Comparison of polynomials is possible, and proceeds by simply examining the
lead monomials and comparing them.
+--------------------------------+
|i40 : f < g                     |
|                                |
|o40 = false                     |
+--------------------------------+
|i41 : sort {b^2-1,a*b,a+1,a,b}  |
|                                |
|                     2          |
|o41 = {b, a, a + 1, b  - 1, a*b}|
|                                |
|o41 : List                      |
+--------------------------------+
The comparison operator ?, returns a symbol indicating how two
polynomials, or rather, their lead monomials, stand with respect to each other
in the monomial ordering.
+-------------+
|i42 : f ? g  |
|             |
|o42 = >      |
|             |
|o42 : Keyword|
+-------------+

factoring polynomials
*********************

Polynomials can be factored with factor.  Factorization works in
polynomial rings over prime finite fields, ZZ, or QQ.
+----------------------------------------------------------------+
|i1 : R = ZZ/10007[a,b];                                         |
+----------------------------------------------------------------+
|i2 : f = (2*a+3)^4 + 5                                          |
|                                                                |
|        4      3       2                                        |
|o2 = 16a  + 96a  + 216a  + 216a + 86                            |
|                                                                |
|o2 : R                                                          |
+----------------------------------------------------------------+
|i3 : g = (2*a+b+1)^3                                            |
|                                                                |
|       3      2        2    3      2             2              |
|o3 = 8a  + 12a b + 6a*b  + b  + 12a  + 12a*b + 3b  + 6a + 3b + 1|
|                                                                |
|o3 : R                                                          |
+----------------------------------------------------------------+
|i4 : S = factor f                                               |
|                                                                |
|                         2                                      |
|o4 = (a - 402)(a + 405)(a  + 3a - 2301)(16)                     |
|                                                                |
|o4 : Expression of class Product                                |
+----------------------------------------------------------------+
|i5 : T = factor g                                               |
|                                                                |
|                       3                                        |
|o5 = (a - 5003b - 5003) (8)                                     |
|                                                                |
|o5 : Expression of class Product                                |
+----------------------------------------------------------------+

The results have been packaged for easy viewing.  The number of factors is
obtained using
+-------+
|i6 : #T|
|       |
|o6 = 2 |
+-------+
Each factor is represented as a power (exponents equal to 1 don't appear in the
display.)  The parts can be extracted with #.
+------------------------------+
|i7 : T#0                      |
|                              |
|                       3      |
|o7 = (a - 5003b - 5003)       |
|                              |
|o7 : Expression of class Power|
+------------------------------+
|i8 : T#0#0                    |
|                              |
|o8 = a - 5003b - 5003         |
|                              |
|o8 : R                        |
+------------------------------+
|i9 : T#0#1                    |
|                              |
|o9 = 3                        |
+------------------------------+

fraction fields
***************

The fraction field of a ring (which must be an integral domain) is obtained
with the function frac.
+------------------------------------+
|i1 : frac ZZ                        |
|                                    |
|o1 = QQ                             |
|                                    |
|o1 : Ring                           |
+------------------------------------+
|i2 : R = ZZ/101[x,y]/(x^3 + 1 + y^3)|
|                                    |
|o2 = R                              |
|                                    |
|o2 : QuotientRing                   |
+------------------------------------+
|i3 : frac R                         |
|                                    |
|o3 = frac R                         |
|                                    |
|o3 : FractionField                  |
+------------------------------------+
After defining a ring such as R, fractions in its fraction field can be
obtained by writing them explicitly.
+-----------+
|i4 : x     |
|           |
|o4 = x     |
|           |
|o4 : R     |
+-----------+
|i5 : 1/x   |
|           |
|     1     |
|o5 = -     |
|     x     |
|           |
|o5 : frac R|
+-----------+
|i6 : x/1   |
|           |
|o6 = x     |
|           |
|o6 : R     |
+-----------+
Alternatively, after applying the function use, or assigning the
fraction ring to a global variable, the symbols you used become associated with
the corresponding elements of the fraction field.
+------------------+
|i7 : use frac R   |
|                  |
|o7 = frac R       |
|                  |
|o7 : FractionField|
+------------------+
|i8 : x            |
|                  |
|o8 = x            |
|                  |
|o8 : frac R       |
+------------------+
Fractions are reduced to the extent possible.  This is done by computing the
syzygies between the numerator and denominator, and picking one of low degree.
+------------------------+
|i9 : f = (x-y)/(x^6-y^6)|
|                        |
|           -1           |
|o9 = -------------      |
|      2          2      |
|     x  + x*y + y       |
|                        |
|o9 : frac R             |
+------------------------+
|i10 : (x^3 - y^3) * f   |
|                        |
|o10 = - x + y           |
|                        |
|o10 : frac R            |
+------------------------+
The parts of a fraction may be extracted.
+-------------------+
|i11 : numerator f  |
|                   |
|o11 = -1           |
|                   |
|o11 : R            |
+-------------------+
|i12 : denominator f|
|                   |
|       2          2|
|o12 = x  + x*y + y |
|                   |
|o12 : R            |
+-------------------+
Alternatively, the functions lift, and liftable,
can be used.
+---------------------+
|i13 : liftable(1/f,R)|
|                     |
|o13 = true           |
+---------------------+
|i14 : liftable(f,R)  |
|                     |
|o14 = false          |
+---------------------+
|i15 : lift(1/f,R)    |
|                     |
|         2          2|
|o15 = - x  - x*y - y |
|                     |
|o15 : R              |
+---------------------+
Note that computations, such as Gröbner bases, over fraction fields can be
quite slow.

See also
========

  * frac -- construct a fraction field
  * numerator -- numerator of a fraction
  * denominator -- denominator of a fraction
  * liftable -- whether lifting to another ring is possible
  * lift -- lift to another ring
  * kernel(RingMap) -- kernel of a ringmap

finite field extensions
***********************

  * toField -- declare that a ring is a field

exterior algebras
*****************

An exterior algebra is a polynomial ring where multiplication is mildly
non-commutative, in that, for every x and y in the ring, y*x = (-1)^(deg(x)
deg(y)) x*y, and that for every x of odd degree, x*x = 0.In Macaulay2, deg(x)
is the degree of x, or the first degree of x, in case a multi-graded ring is
being used.  The default degree for each variable is 1, so in this case, y*x =
-x*y, if x and y are variables in the ring.

Create an exterior algebra with explicit generators by creating a polynomial
ring with the option SkewCommutative.
+---------------------------------------------------+
|i1 : R = QQ[x,y,z, SkewCommutative => true]        |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing, 3 skew commutative variable(s)|
+---------------------------------------------------+
|i2 : y*x                                           |
|                                                   |
|o2 = -x*y                                          |
|                                                   |
|o2 : R                                             |
+---------------------------------------------------+
|i3 : (x+y+z)^2                                     |
|                                                   |
|o3 = 0                                             |
|                                                   |
|o3 : R                                             |
+---------------------------------------------------+
|i4 : basis R                                       |
|                                                   |
|o4 = | 1 x xy xyz xz y yz z |                      |
|                                                   |
|             1      8                              |
|o4 : Matrix R  <-- R                               |
+---------------------------------------------------+
|i5 : basis(2,R)                                    |
|                                                   |
|o5 = | xy xz yz |                                  |
|                                                   |
|             1      3                              |
|o5 : Matrix R  <-- R                               |
+---------------------------------------------------+
+--------------------------------------------------------------------+
|i6 : S = QQ[a,b,r,s,t, SkewCommutative=>true, Degrees=>{2,2,1,1,1}];|
+--------------------------------------------------------------------+
|i7 : r*a == a*r                                                     |
|                                                                    |
|o7 = false                                                          |
+--------------------------------------------------------------------+
|i8 : a*a                                                            |
|                                                                    |
|o8 = 0                                                              |
|                                                                    |
|o8 : S                                                              |
+--------------------------------------------------------------------+
|i9 : f = a*r+b*s; f^2                                               |
|                                                                    |
|o10 = -2a*b*r*s                                                     |
|                                                                    |
|o10 : S                                                             |
+--------------------------------------------------------------------+
|i11 : basis(2,S)                                                    |
|                                                                    |
|o11 = | a b rs rt st |                                              |
|                                                                    |
|              1      5                                              |
|o11 : Matrix S  <-- S                                               |
+--------------------------------------------------------------------+
All modules over exterior algebras are right modules.  This means that matrices
multiply from the opposite side:
+-------------------------------+
|i12 : x*y                      |
|                               |
|o12 = x*y                      |
|                               |
|o12 : R                        |
+-------------------------------+
|i13 : matrix{{x}} * matrix{{y}}|
|                               |
|o13 = | -xy |                  |
|                               |
|              1      1         |
|o13 : Matrix R  <-- R          |
+-------------------------------+
You may compute Gröbner bases, syzygies, and form quotient rings of these skew
commutative rings.

symmetric algebras
******************

Polynomial rings are symmetric algebras with explicit generators, and we have
already seen how to construct them.  But if you have a module, then its
symmetric algebra can be constructed with symmetricAlgebra.
+-------------------------+
|i1 : R = QQ[a..d];       |
+-------------------------+
|i2 : symmetricAlgebra R^3|
|                         |
|o2 = R[p ..p ]           |
|        0   2            |
|                         |
|o2 : PolynomialRing      |
+-------------------------+
Maps between symmetric algebras can be constructed functorially.
+--------------------------------------------------------------------+
|i3 : vars R                                                         |
|                                                                    |
|o3 = | a b c d |                                                    |
|                                                                    |
|             1      4                                               |
|o3 : Matrix R  <-- R                                                |
+--------------------------------------------------------------------+
|i4 : symmetricAlgebra vars R                                        |
|                                                                    |
|o4 = map (R[p ], R[p ..p ], {a*p , b*p , c*p , d*p , a, b, c, d})   |
|             0      0   3       0     0     0     0                 |
|                                                                    |
|o4 : RingMap R[p ] <-- R[p ..p ]                                    |
|                0         0   3                                     |
+--------------------------------------------------------------------+
|i5 : symmetricAlgebra transpose vars R                              |
|                                                                    |
|o5 = map (R[p ..p ], R[p ], {a*p  + b*p  + c*p  + d*p , a, b, c, d})|
|             0   3      0       0      1      2      3              |
|                                                                    |
|o5 : RingMap R[p ..p ] <-- R[p ]                                    |
|                0   3         0                                     |
+--------------------------------------------------------------------+
Until the ring is used with use, or assigned to a global variable,
its generators are not assigned to global variables.
+--------------------+
|i6 : a              |
|                    |
|o6 = a              |
|                    |
|o6 : R              |
+--------------------+
|i7 : p_0            |
|                    |
|o7 = p              |
|      0             |
|                    |
|o7 : IndexedVariable|
+--------------------+
|i8 : S = o2;        |
+--------------------+
|i9 : a              |
|                    |
|o9 = a              |
|                    |
|o9 : R              |
+--------------------+
|i10 : p_0           |
|                    |
|o10 = p             |
|       0            |
|                    |
|o10 : S             |
+--------------------+
To specify the names of the variables when creating the ring, use the
Variables, option or the VariableBaseName,
option.
+--------------------------------------------------+
|i11 : symmetricAlgebra(R^3, Variables => {t,u,v}) |
|                                                  |
|o11 = R[t..v]                                     |
|                                                  |
|o11 : PolynomialRing                              |
+--------------------------------------------------+
|i12 : symmetricAlgebra(R^3, VariableBaseName => t)|
|                                                  |
|o12 = R[t ..t ]                                   |
|         0   2                                    |
|                                                  |
|o12 : PolynomialRing                              |
+--------------------------------------------------+
We can construct the symmetric algebra of a module that isn't necessarily free.
+-----------------------------------+
|i13 : use R                        |
|                                   |
|o13 = R                            |
|                                   |
|o13 : PolynomialRing               |
+-----------------------------------+
|i14 : symmetricAlgebra(R^1/(a,b^3))|
|                                   |
|          R[p ]                    |
|             0                     |
|o14 = ------------                 |
|              3                    |
|      (a*p , b p )                 |
|          0     0                  |
|                                   |
|o14 : QuotientRing                 |
+-----------------------------------+

tensor products of rings
************************

The operator **, or the function tensor, can be
used to construct tensor products of rings.
+---------------------------------------------------+
|i1 : ZZ/101[x,y]/(x^2-y^2) ** ZZ/101[a,b]/(a^3+b^3)|
|                                                   |
|        ZZ                                         |
|       ---[x..y, a..b]                             |
|       101                                         |
|o1 = ------------------                            |
|       2    2   3    3                             |
|     (x  - y , a  + b )                            |
|                                                   |
|o1 : QuotientRing                                  |
+---------------------------------------------------+
Other monomial orderings can be specified.
+-----------------------------------------------------------------------+
|i2 : T = tensor(ZZ/101[x,y], ZZ/101[a,b], MonomialOrder => Eliminate 2)|
|                                                                       |
|o2 = T                                                                 |
|                                                                       |
|o2 : PolynomialRing                                                    |
+-----------------------------------------------------------------------+
The options to tensor can be discovered with options.
+-------------------+
|i3 : options tensor|
+-------------------+
Given two (quotients of) polynomial rings, say, R = A[x1, ..., xn]/I, S =
A[y1,...,yn]/J, then R ** S = A[x1,...,xn,y1, ..., yn]/(I + J).  The variables
in the two rings are always considered as different.  If they have name
conflicts, you may still use the variables with indexing, but the display will
be confusing:
+-----------------------------------------------------------------------------+
|i4 : R = QQ[x,y]/(x^3-y^2);                                                  |
+-----------------------------------------------------------------------------+
|i5 : T = R ** R                                                              |
|warning: clearing value of symbol x to allow access to subscripted           |
|       : debug with expression   debug 9868   or with command line           |
|warning: clearing value of symbol y to allow access to subscripted           |
|       : debug with expression   debug 9371   or with command line           |
|                                                                             |
|o5 = T                                                                       |
|                                                                             |
|o5 : QuotientRing                                                            |
|-----------------------------------------------------------------------------|
|variables based on it                                                        |
|option   --debug 9868                                                        |
|variables based on it                                                        |
|option   --debug 9371                                                        |
+-----------------------------------------------------------------------------+
|i6 : generators T                                                            |
|                                                                             |
|o6 = {x , y , x , y }                                                        |
|       0   0   1   1                                                         |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : {T_0 + T_1, T_0 + T_2}                                                  |
|                                                                             |
|o7 = {x  + y , x  + x }                                                      |
|       0    0   0    1                                                       |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
We can change the variable names with the Variables, option.
+---------------------------------------------+
|i8 : U = tensor(R,R,Variables => {x,y,x',y'})|
|                                             |
|o8 = U                                       |
|                                             |
|o8 : QuotientRing                            |
+---------------------------------------------+
|i9 : x + y + x' + y'                         |
|                                             |
|o9 = x + y + x' + y'                         |
|                                             |
|o9 : U                                       |
+---------------------------------------------+

Weyl algebras
*************

A Weyl algebra is the non-commutative algebra of algebraic differential
operators on a polynomial ring.  To each variable x corresponds the operator dx
that differentiates with respect to that variable.  The evident commutation
relation takes the form dx*x == x*dx + 1.

We can give any names we like to the variables in a Weyl algebra, provided we
specify the correspondence between the variables and the derivatives, with the
WeylAlgebra, option, as
follows.

+------------------------------------------------------+
|i1 : R = QQ[x,y,dx,dy,t,WeylAlgebra => {x=>dx, y=>dy}]|
|                                                      |
|o1 = R                                                |
|                                                      |
|o1 : PolynomialRing, 2 differential variable(s)       |
+------------------------------------------------------+
|i2 : dx*dy*x*y                                        |
|                                                      |
|o2 = x*y*dx*dy + x*dx + y*dy + 1                      |
|                                                      |
|o2 : R                                                |
+------------------------------------------------------+
|i3 : dx*x^5                                           |
|                                                      |
|      5       4                                       |
|o3 = x dx + 5x                                        |
|                                                      |
|o3 : R                                                |
+------------------------------------------------------+
All modules over Weyl algebras are, in Macaulay2, right modules.  This means
that multiplication of matrices is from the opposite side:
+-------------------------------+
|i4 : dx*x                      |
|                               |
|o4 = x*dx + 1                  |
|                               |
|o4 : R                         |
+-------------------------------+
|i5 : matrix{{dx}} * matrix{{x}}|
|                               |
|o5 = | xdx |                   |
|                               |
|             1      1          |
|o5 : Matrix R  <-- R           |
+-------------------------------+

All Gröbner basis and related computations work over this ring.  For an
extensive collection of D-module routines (A D-module is a module over a Weyl
algebra), see Dmodules.

The function isWeylAlgebra can be used to determine whether a polynomial ring
has been constructed as a Weyl algebra.

+--------------------+
|i6 : isWeylAlgebra R|
|                    |
|o6 = true           |
+--------------------+
|i7 : S = QQ[x,y]    |
|                    |
|o7 = S              |
|                    |
|o7 : PolynomialRing |
+--------------------+
|i8 : isWeylAlgebra S|
|                    |
|o8 = false          |
+--------------------+

associative algebras
********************

Associative (i.e., not necessarily commutative) algebras are implemented in the
AssociativeAlgebras, package.

ideals
******

An overview
===========

In Macaulay2, once a ring (see rings) is defined, ideals are
constructed in the usual way by giving a set of generators.

For those operations where we consider an ideal as a module, such as computing
Hilbert functions and polynomials, syzygies, free resolutions, see
modules.

For additional common operations and a comprehensive list of all routines in
Macaulay2 which return or use ideals, see Ideal.

The following link differs from the previous one in case only: ideal.

conversions

basic operations on ideals

components of ideals

creating an ideal
*****************

ideal
=====

An ideal I is represented by its generators. We use the function ideal,
to construct an ideal.
+--------------------------------------------+
|i1 : R = QQ[a..d];                          |
+--------------------------------------------+
|i2 : I = ideal (a^2*b-c^2, a*b^2-d^3, c^5-d)|
|                                            |
|             2     2     2    3   5         |
|o2 = ideal (a b - c , a*b  - d , c  - d)    |
|                                            |
|o2 : Ideal of R                             |
+--------------------------------------------+

monomial ideals
===============

For a monomial ideal you can use the function monomialIdeal.
+------------------------------------------+
|i3 : J = monomialIdeal (a^2*b, b*c*d, c^5)|
|                                          |
|                     2    5               |
|o3 = monomialIdeal (a b, c , b*c*d)       |
|                                          |
|o3 : MonomialIdeal of R                   |
+------------------------------------------+
The distinction is small since a monomial ideal can be constructed using ideal
.  However, there are a few functions, like primaryDecomposition (PrimaryDecomposition),
that run faster if you define a
monomial ideal using monomialIdeal.

monomialCurveIdeal
==================

An interesting class of ideals can be obtained as the defining ideals in
projective space of monomial curves. For example the twisted cubic is the
closure of the set of points (1,t^1,t^2,t^3) in projective space.  We use a
list of the exponents and monomialCurveIdeal, to get
the ideal.
+------------------------------------------+
|i4 : monomialCurveIdeal(R,{1,2,3})        |
|                                          |
|             2                    2       |
|o4 = ideal (c  - b*d, b*c - a*d, b  - a*c)|
|                                          |
|o4 : Ideal of R                           |
+------------------------------------------+

See also
========

  * ideal -- make an ideal
  * monomialIdeal -- make a monomial ideal
  * monomialCurveIdeal -- make the ideal of a
    monomial curve

ideals to and from matrices
***************************

forming an ideal from a matrix
==============================

After defining a matrix (see inputting a matrix) ,
M, the ideal generated by the entries of the matrix is obtained using the
command ideal.
+------------------------------------------------------------------+
|i1 : R = ZZ/101[a..e];                                            |
+------------------------------------------------------------------+
|i2 : M = matrix{{a^2*b-c^2, a*b^2-d^3, c^5-d},{a^2*b, b*c*d, c^5}}|
|                                                                  |
|o2 = | a2b-c2 ab2-d3 c5-d |                                       |
|     | a2b    bcd    c5   |                                       |
|                                                                  |
|             2      3                                             |
|o2 : Matrix R  <-- R                                              |
+------------------------------------------------------------------+
|i3 : ideal M                                                      |
|                                                                  |
|             2     2   2      2    3          5       5           |
|o3 = ideal (a b - c , a b, a*b  - d , b*c*d, c  - d, c )          |
|                                                                  |
|o3 : Ideal of R                                                   |
+------------------------------------------------------------------+

forming a matrix from an ideal
==============================

In much the same way we can construct a 1 by n (where n is the number of
generators of I), matrix from the n generators of an ideal I using the command,
see generators.
+----------------------------------------------------+
|i4 : I = ideal(a^2*b-c^2+c*d, a*b^2-b*d^3, c^5,d+e);|
|                                                    |
|o4 : Ideal of R                                     |
+----------------------------------------------------+
|i5 : generators I                                   |
|                                                    |
|o5 = | a2b-c2+cd -bd3+ab2 c5 d+e |                  |
|                                                    |
|             1      4                               |
|o5 : Matrix R  <-- R                                |
+----------------------------------------------------+
The abbreviation gens can be used for generators.

ideals to and from modules
**************************

from ideals to modules
======================

An ideal I is also an R-submodule.  In Macaulay2 we distinguish between when we
are thinking of I as as ideal or a module.  If it is first defined as an ideal,
it is easily turned into a module using the function module, and
for any submodule of the rank one free module R we can obtain an ideal of the
generators using the function ideal.
+------------------------------+
|i1 : R = ZZ/32003[x,y,z];     |
+------------------------------+
|i2 : I = ideal(x^2,y*z-x);    |
|                              |
|o2 : Ideal of R               |
+------------------------------+
|i3 : module I                 |
|                              |
|o3 = image | x2 yz-x |        |
|                              |
|                             1|
|o3 : R-module, submodule of R |
+------------------------------+

from modules to ideals
======================

For any submodule of the rank one free module R we can obtain an ideal of the
generators using the function ideal.
+------------------------------+
|i4 : A = matrix{{x*y-z,z^3}}; |
|                              |
|             1      2         |
|o4 : Matrix R  <-- R          |
+------------------------------+
|i5 : M = image A              |
|                              |
|o5 = image | xy-z z3 |        |
|                              |
|                             1|
|o5 : R-module, submodule of R |
+------------------------------+
|i6 : ideal M                  |
|                              |
|                      3       |
|o6 = ideal (x*y - z, z )      |
|                              |
|o6 : Ideal of R               |
+------------------------------+

getting the quotient module corresponding to an ideal
=====================================================

We also often work with R/I as an R-module.  Simply typing R/I at a prompt in
Macaulay2 constructs the quotient ring (see quotient rings).
There are two ways to tell Macaulay2 that we want to work with this as
a module.
+-----------------------------+
|i7 : coker generators I      |
|                             |
|o7 = cokernel | x2 yz-x |    |
|                             |
|                            1|
|o7 : R-module, quotient of R |
+-----------------------------+
|i8 : R^1/I                   |
|                             |
|o8 = cokernel | x2 yz-x |    |
|                             |
|                            1|
|o8 : R-module, quotient of R |
+-----------------------------+

modules versus ideals for computations
======================================

Some functions in Macaulay2 try to make an informed decision about ideal and
modules.  For example, if resolution, is given an ideal I, it
will compute a resolution of the module R^1/I, as in the following example.
+---------------------------+
|i9 : resolution I          |
|                           |
|      1      2      1      |
|o9 = R  <-- R  <-- R  <-- 0|
|                           |
|     0      1      2      3|
|                           |
|o9 : ChainComplex          |
+---------------------------+
The functions dim, and degree, also operate on R^1/I
if the input is I or R^1/I.  However, the function hilbertPolynomial,
computes the Hilbert polynomial of the module I if the input
is hilbertPolynomial I.

For basic information about working with modules see modules.

sums, products, and powers of ideals
************************************

Arithmetic for ideals uses the standard symbols.  Below are examples of the
basic arithmetic functions for ideal.
+------------------------------------------------+
|i1 : R = ZZ/101[a..d]/(b*c-a*d,c^2-b*d,b^2-a*c);|
+------------------------------------------------+
For more information about quotient rings see quotient rings.
+--------------------------------------------------------------------+
|i2 : I = ideal (a*b-c,d^3);                                         |
|                                                                    |
|o2 : Ideal of R                                                     |
+--------------------------------------------------------------------+
|i3 : J = ideal (a^3,b*c-d);                                         |
|                                                                    |
|o3 : Ideal of R                                                     |
+--------------------------------------------------------------------+
|i4 : I+J                                                            |
|                                                                    |
|                      3   3                                         |
|o4 = ideal (a*b - c, d , a , a*d - d)                               |
|                                                                    |
|o4 : Ideal of R                                                     |
+--------------------------------------------------------------------+
|i5 : I*J                                                            |
|                                                                    |
|             4     3    2                            3 3     4    4 |
|o5 = ideal (a b - a c, a b*d - a*b*d - a*c*d + c*d, a d , a*d  - d )|
|                                                                    |
|o5 : Ideal of R                                                     |
+--------------------------------------------------------------------+
|i6 : I^2                                                            |
|                                                                    |
|             3      2              3      3   6                     |
|o6 = ideal (a c - 2a d + b*d, a*b*d  - c*d , d )                    |
|                                                                    |
|o6 : Ideal of R                                                     |
+--------------------------------------------------------------------+
For more information see Ideal + Ideal, Ideal * Ideal,
and Ideal ^ ZZ.

equality and containment
************************

Equality and containment between two ideals in a polynomial ring (or quotient
of a polynomial ring) is checked by comparing their respective Groebner bases.

equal and not equal
===================

Use Ideal == Ideal (missing documentation) to test if two ideals in the same
ring are equal.
+---------------------------------------------+
|i1 : R = QQ[a..d];                           |
+---------------------------------------------+
|i2 : I = ideal (a^2*b-c^2, a*b^2-d^3, c^5-d);|
|                                             |
|o2 : Ideal of R                              |
+---------------------------------------------+
|i3 : J = ideal (a^2,b^2,c^2,d^2);            |
|                                             |
|o3 : Ideal of R                              |
+---------------------------------------------+
|i4 : I == J                                  |
|                                             |
|o4 = false                                   |
+---------------------------------------------+
|i5 : I != J                                  |
|                                             |
|o5 = true                                    |
+---------------------------------------------+

normal form with respect to a Groebner basis and membership
===========================================================

The function RingElement % Ideal,
reduces an element with respect to a Groebner basis of the ideal.
+----------------------+
|i6 : (1+a+a^3+a^4) % J|
|                      |
|o6 = a + 1            |
|                      |
|o6 : R                |
+----------------------+
We can then test membership in the ideal by comparing the answer to 0 using
==.
+---------------------------+
|i7 : (1+a+a^3+a^4) % J == 0|
|                           |
|o7 = false                 |
+---------------------------+
|i8 : a^4 % J == 0          |
|                           |
|o8 = true                  |
+---------------------------+

containment for two ideals
==========================

Containment for two ideals is tested using isSubset.
+---------------------+
|i9 : isSubset(I,J)   |
|                     |
|o9 = false           |
+---------------------+
|i10 : isSubset(I,I+J)|
|                     |
|o10 = true           |
+---------------------+
|i11 : isSubset(I+J,I)|
|                     |
|o11 = false          |
+---------------------+

ideal equal to 1 or 0
=====================

Use the expression I == 1 to see if the ideal is equal to the ring.  Use I == 0
to see if the ideal is identically zero in the given ring.
+------------------------------+
|i12 : I = ideal (a^2-1,a^3+3);|
|                              |
|o12 : Ideal of R              |
+------------------------------+
|i13 : I == 1                  |
|                              |
|o13 = true                    |
+------------------------------+
|i14 : S = R/I                 |
|                              |
|o14 = S                       |
|                              |
|o14 : QuotientRing            |
+------------------------------+
|i15 : S == 0                  |
|                              |
|o15 = true                    |
+------------------------------+

See also
========

  * Ideal == Ideal (missing documentation)
  * Ideal == ZZ (missing documentation)
  * != -- inequality
  * RingElement % Ideal, --
    normal form of ring elements and matrices
  * isSubset(Ideal,Ideal) -- whether one
    object is a subset of another
  * radicalContainment (MinimalPrimes) -- whether an
    element is contained in the radical of an ideal

extracting generators of an ideal
*********************************

obtain a single generator as an element
=======================================

Once an ideal has been constructed it is possible to obtain individual elements
using _.   As always in Macaulay2, indexing starts at 0.
+-----------------------------------------------------+
|i1 : R = ZZ[w,x,y,z];                                |
+-----------------------------------------------------+
|i2 : I = ideal(z*w-2*x*y, 3*w^3-z^3,w*x^2-4*y*z^2,x);|
|                                                     |
|o2 : Ideal of R                                      |
+-----------------------------------------------------+
|i3 : I_0                                             |
|                                                     |
|o3 = - 2x*y + w*z                                    |
|                                                     |
|o3 : R                                               |
+-----------------------------------------------------+
|i4 : I_3                                             |
|                                                     |
|o4 = x                                               |
|                                                     |
|o4 : R                                               |
+-----------------------------------------------------+

the generators as a matrix or list of elements
==============================================

Use generators, or its abbreviation gens to get the
generators of an ideal I as a matrix. Applying first entries to this matrix
converts it to a list.
+----------------------------------------------+
|i5 : gens I                                   |
|                                              |
|o5 = | -2xy+wz 3w3-z3 wx2-4yz2 x |            |
|                                              |
|             1      4                         |
|o5 : Matrix R  <-- R                          |
+----------------------------------------------+
|i6 : first entries gens I                     |
|                                              |
|                      3    3     2       2    |
|o6 = {- 2x*y + w*z, 3w  - z , w*x  - 4y*z , x}|
|                                              |
|o6 : List                                     |
+----------------------------------------------+

number of generators
====================

The command numgens, gives the number of generators of an ideal
I.
+--------------+
|i7 : numgens I|
|              |
|o7 = 4        |
+--------------+

minimal generating set
======================

To obtain a minimal generating set of a homogeneous ideal use mingens,
to get the minimal generators as a matrix and use trim, to
get the minimal generators as an ideal.
+------------------------------------+
|i8 : mingens I                      |
|                                    |
|o8 = | x wz 4yz2 3w3-z3 |           |
|                                    |
|             1      4               |
|o8 : Matrix R  <-- R                |
+------------------------------------+
|i9 : trim I                         |
|                                    |
|                        2    3    3 |
|o9 = ideal (x, w*z, 4y*z , 3w  - z )|
|                                    |
|o9 : Ideal of R                     |
+------------------------------------+
The function mingens is only well-defined for a homogeneous ideal or in a local
ring.  However, one can still try to get as small a generating set as possible
and when it is implemented this function will be done by trim.

obtaining the input form of an ideal
====================================

If the ideal was defined using a function like monomialCurveIdeal and the
generators are desired in the usual format for input of an ideal, the function
toString, is very useful. (Note:  We are changing rings because
monomialCurveIdeal, is not implemented for rings over
ZZ.)
+----------------------------------------+
|i10 : R = QQ[a..d];                     |
+----------------------------------------+
|i11 : I = monomialCurveIdeal(R,{1,2,3});|
|                                        |
|o11 : Ideal of R                        |
+----------------------------------------+
|i12 : toString I                        |
|                                        |
|o12 = ideal(c^2-b*d,b*c-a*d,b^2-a*c)    |
+----------------------------------------+

dimension, codimension, and degree
**********************************

Use dim, codim, and degree, to compute
the dimension, codimension and degree, respectively, of an ideal.  The
functions dim, and degree, compute the dimension and
degree of the ring R/I.
+--------------------------------------+
|i1 : R = ZZ/101[x,y,z];               |
+--------------------------------------+
|i2 : I = ideal(x^3-y*z^2,x*y-z^2,x*z);|
|                                      |
|o2 : Ideal of R                       |
+--------------------------------------+
|i3 : dim I                            |
|                                      |
|o3 = 1                                |
+--------------------------------------+
|i4 : codim I                          |
|                                      |
|o4 = 2                                |
+--------------------------------------+
|i5 : degree I                         |
|                                      |
|o5 = 2                                |
+--------------------------------------+

intersection of ideals
**********************

Use intersect, to compute the intersection of two or more
ideals.
+--------------------------------------------------------+
|i1 : R = QQ[a..d];                                      |
+--------------------------------------------------------+
|i2 : intersect(ideal(a,b),ideal(c*d,a*b),ideal(b*d,a*c))|
|                                                        |
|o2 = ideal (b*c*d, a*c*d, a*b*d, a*b*c)                 |
|                                                        |
|o2 : Ideal of R                                         |
+--------------------------------------------------------+
The command intersect, will only work with proper ideals. To
intersect an ideal with a ring, use selectInSubring,
along with the elimination ordering, see Eliminate.

matrices
********

An overview
===========

In Macaulay2, each matrix is defined over a ring, (see rings).
Matrices are perhaps the most common data type in Macaulay2.

For additional common operations and a comprehensive list of all routines in
Macaulay2 which return or use matrices, see Matrix.

making matrices

operations involving matrices

determinants and related computations

display of matrices and saving matrices to a file

inputting a matrix
******************

by its entries
==============

Using the function matrix, is the most basic method for inputting
a matrix.  The entries are typed in by rows as a doubly nested list of ring
elements.
+----------------------------------------------------+
|i1 : R = ZZ/5[s..z];                                |
+----------------------------------------------------+
|i2 : M = matrix {{ x^2+y, z^3}, {y^3-z,3*z-6*x-5*y}}|
|                                                    |
|o2 = | x2+y z3    |                                 |
|     | y3-z -x-2z |                                 |
|                                                    |
|             2      2                               |
|o2 : Matrix R  <-- R                                |
+----------------------------------------------------+
One way to construct a doubly nested list of ring elements is with the
table, command.
+-----------------------------------------+
|i3 : table(3,3,(i,j) -> R_i^j)           |
|                                         |
|              2           2           2  |
|o3 = {{1, s, s }, {1, t, t }, {1, u, u }}|
|                                         |
|o3 : List                                |
+-----------------------------------------+
|i4 : p = matrix oo                       |
|                                         |
|o4 = | 1 s s2 |                          |
|     | 1 t t2 |                          |
|     | 1 u u2 |                          |
|                                         |
|             3      3                    |
|o4 : Matrix R  <-- R                     |
+-----------------------------------------+
|i5 : q = matrix table(3,3,(i,j) -> R_j^i)|
|                                         |
|o5 = | 1  1  1  |                        |
|     | s  t  u  |                        |
|     | s2 t2 u2 |                        |
|                                         |
|             3      3                    |
|o5 : Matrix R  <-- R                     |
+-----------------------------------------+

by a function
=============

The function map, can be used to construct matrices.
+--------------------------------------------+
|i6 : G = map(R^3,3,(i,j)->R_i^j)            |
|                                            |
|o6 = | 1 s s2 |                             |
|     | 1 t t2 |                             |
|     | 1 u u2 |                             |
|                                            |
|             3      3                       |
|o6 : Matrix R  <-- R                        |
+--------------------------------------------+
|i7 : f = 3*s^2*v-t*u*v+s*t^2                |
|                                            |
|        2     2                             |
|o7 = s*t  - 2s v - t*u*v                    |
|                                            |
|o7 : R                                      |
+--------------------------------------------+
|i8 : H = map(R^4,R^4,(i,j)->diff(R_j*R_i,f))|
|                                            |
|o8 = | v  2t 0  s  |                        |
|     | 2t 2s -v -u |                        |
|     | 0  -v 0  -t |                        |
|     | s  -u -t 0  |                        |
|                                            |
|             4      4                       |
|o8 : Matrix R  <-- R                        |
+--------------------------------------------+

identity matrix
===============

The function id, is used to form the identity matrix as a map from a
module to itself.
+----------------------+
|i9 : id_(R^3)         |
|                      |
|o9 = | 1 0 0 |        |
|     | 0 1 0 |        |
|     | 0 0 1 |        |
|                      |
|             3      3 |
|o9 : Matrix R  <-- R  |
+----------------------+
|i10 : id_(source M)   |
|                      |
|o10 = {3} | 1 0 |     |
|      {3} | 0 1 |     |
|                      |
|              2      2|
|o10 : Matrix R  <-- R |
+----------------------+
The first example gives a 3x3 identity matrix with entries in the ring R.  The
second gives a 2x2 identity matrix whose source and target are the (graded)
source of the matrix M.

projections, inclusions, and permutations
*****************************************

random and generic matrices
***************************

random matrices
===============

To construct a random m by n matrix with entries in a ring R use the function
random, by typing random(R^m,R^n).
+-------------------------------+
|i1 : R = GF(3^2,Variable => a);|
+-------------------------------+
|i2 : random(R^3,R^4)           |
|                               |
|o2 = | a  1   -a-1 a-1  |      |
|     | -a a+1 -a-1 a-1  |      |
|     | 0  a   -a   -a-1 |      |
|                               |
|             3      4          |
|o2 : Matrix R  <-- R           |
+-------------------------------+
Over a polynomial ring, this will select elements in the base ring or field. To
obtain a matrix of (say) linear polynomials, use
+-------------------------------------------------------------------+
|i3 : T = R[x,y];                                                   |
+-------------------------------------------------------------------+
|i4 : random(T^3,T^{4:-1})                                          |
|                                                                   |
|o4 = | -x+(-a-1)y    -ax+y          (a-1)x+(-a-1)y -ax+y          ||
|     | (a+1)x+(a-1)y -x+y           (-a-1)x+(a-1)y ax+y           ||
|     | (a-1)x+(a-1)y (a-1)x+(-a+1)y -x+ay          (-a-1)x+(a+1)y ||
|                                                                   |
|             3      4                                              |
|o4 : Matrix T  <-- T                                               |
+-------------------------------------------------------------------+

matrices of variables
=====================

To build an m by n matrix of variables drawn from the ring R, use
genericMatrix.  The syntax is genericMatrix(R,x,m,n) where R is
the ring, x is the variable where we start and m and n specify the size of the
matrix.
+---------------------------+
|i5 : S = R[p..z];          |
+---------------------------+
|i6 : genericMatrix(S,t,3,2)|
|                           |
|o6 = | t w |               |
|     | u x |               |
|     | v y |               |
|                           |
|             3      2      |
|o6 : Matrix S  <-- S       |
+---------------------------+
Note that to use the function genericMatrix the number of variables in the ring
R must be at least as large as m*n.

genericSymmetricMatrix
======================

To construct an n by n symmetric matrix whose entries on and above the diagonal
are the variables of R use genericSymmetricMatrix.
The syntax is genericSymmetricMatrix(R,x,n) where R is
the ring, x is the variable you want to start with and n is the size of the
matrix.
+----------------------------------+
|i7 : genericSymmetricMatrix(S,s,3)|
|                                  |
|o7 = | s t u |                    |
|     | t v w |                    |
|     | u w x |                    |
|                                  |
|             3      3             |
|o7 : Matrix S  <-- S              |
+----------------------------------+

genericSkewMatrix
=================

To construct an n by n skew symmetric matrix whose entries above the diagonal
are the variables of R use genericSkewMatrix.  The
syntax is genericSkewMatrix(R,x,n) where R is the ring, x is the variable you
want to start with and n is the size of the matrix.
+-----------------------------+
|i8 : genericSkewMatrix(S,u,3)|
|                             |
|o8 = | 0  u  v |             |
|     | -u 0  w |             |
|     | -v -w 0 |             |
|                             |
|             3      3        |
|o8 : Matrix S  <-- S         |
+-----------------------------+

extracting information about a matrix
*************************************

Consider the ring R and the matrix f.
+---------------------------------------+
|i1 : R = QQ[x,y,z];                    |
+---------------------------------------+
|i2 : f = matrix{{2,x,y,x^2},{z,32,2,x}}|
|                                       |
|o2 = | 2 x  y x2 |                     |
|     | z 32 2 x  |                     |
|                                       |
|             2      4                  |
|o2 : Matrix R  <-- R                   |
+---------------------------------------+

target
======

From the above output, one sees that Macaulay2 considers f as a linear
transformation. Use the target, command to obtain the target of
the linear transformation f.
+-------------------+
|i3 : M = target f  |
|                   |
|      2            |
|o3 = R             |
|                   |
|o3 : R-module, free|
+-------------------+
Free modules are actually graded free modules, with the same sort of grading
that the ring comes with.  The degrees of the basis vectors of the target are
always zero.
+---------------+
|i4 : degree M_0|
|               |
|o4 = {0}       |
|               |
|o4 : List      |
+---------------+
|i5 : degree M_1|
|               |
|o5 = {0}       |
|               |
|o5 : List      |
+---------------+

source
======

Likewise, to obtain the source of our linear transformation, use the
source, command.
+-------------------------------------+
|i6 : N = source f                    |
|                                     |
|      4                              |
|o6 = R                               |
|                                     |
|o6 : R-module, free, degrees {3:1, 2}|
+-------------------------------------+
If possible, the degrees of the basis vectors of the source are set so that the
map f turns out to a homogeneous map of degree zero. This opportunism is
important because certain algorithms will run faster on homogeneous maps.
+---------------------+
|i7 : degree N_0      |
|                     |
|o7 = {1}             |
|                     |
|o7 : List            |
+---------------------+
|i8 : degree N_1      |
|                     |
|o8 = {1}             |
|                     |
|o8 : List            |
+---------------------+
|i9 : degree N_2      |
|                     |
|o9 = {1}             |
|                     |
|o9 : List            |
+---------------------+
|i10 : degree N_3     |
|                     |
|o10 = {2}            |
|                     |
|o10 : List           |
+---------------------+
|i11 : isHomogeneous f|
|                     |
|o11 = false          |
+---------------------+
A list of the degrees of all the basis vectors can be obtained with
degrees.
+--------------------------+
|i12 : degrees N           |
|                          |
|o12 = {{1}, {1}, {1}, {2}}|
|                          |
|o12 : List                |
+--------------------------+
It may happen that the matrix can not be made homogeneous.  In that case, the
degree of a basis vector is currently set to the degree of the largest monomial
occurring in the corresponding column of the matrix.  In a future version of
the program it might be more sensible to set the degrees of the basis vectors
all to zero.
+----------------------------------------+
|i13 : g = matrix {{x,0,y*z},{y^2,x^2,0}}|
|                                        |
|o13 = | x  0  yz |                      |
|      | y2 x2 0  |                      |
|                                        |
|              2      3                  |
|o13 : Matrix R  <-- R                   |
+----------------------------------------+
|i14 : isHomogeneous g                   |
|                                        |
|o14 = false                             |
+----------------------------------------+
|i15 : degrees source g                  |
|                                        |
|o15 = {{2}, {2}, {2}}                   |
|                                        |
|o15 : List                              |
+----------------------------------------+

number of rows or columns
=========================

Use numgens, to obtain the rank of a free module. Combining it
with the commands target, or source, gives us a way
to determine the number of rows or columns of a matrix f.
+----------------------+
|i16 : numgens target f|
|                      |
|o16 = 2               |
+----------------------+
|i17 : numgens source f|
|                      |
|o17 = 4               |
+----------------------+

extracting an element from a matrix
===================================

To extract the (i,j)-th element of a matrix, type f_(i,j).
+-------------+
|i18 : f_(1,3)|
|             |
|o18 = x      |
|             |
|o18 : R      |
+-------------+
Note that the first number selects the row, starting at 0 and the second number
selects the column, also starting at 0.

entries of a matrix
===================

To obtain the entries of a matrix in the form of a list of lists, use the
entries, command.
+------------------------------------+
|i19 : entries f                     |
|                                    |
|                  2                 |
|o19 = {{2, x, y, x }, {z, 32, 2, x}}|
|                                    |
|o19 : List                          |
+------------------------------------+
Note that each inner list is a list of elements from a row of f.

ring
====

The ring, command can be used to return the ring of the matrix,
that is, the ring containing entries of the matrix.
+--------------------+
|i20 : ring f        |
|                    |
|o20 = R             |
|                    |
|o20 : PolynomialRing|
+--------------------+
Use the describe, command to recover how the ring of f was
constructed.
+---------------------------------------------+
|i21 : describe ring f                        |
|                                             |
|o21 = QQ[x..z, Degrees => {3:1}, Heft => {1}]|
+---------------------------------------------+

basic arithmetic of matrices
****************************

+
==

To add two matrices, use the +, operator.
+---------------------------------+
|i1 : ff = matrix{{1,2,3},{4,5,6}}|
|                                 |
|o1 = | 1 2 3 |                   |
|     | 4 5 6 |                   |
|                                 |
|              2       3          |
|o1 : Matrix ZZ  <-- ZZ           |
+---------------------------------+
|i2 : gg = matrix{{4,5,6},{1,2,3}}|
|                                 |
|o2 = | 4 5 6 |                   |
|     | 1 2 3 |                   |
|                                 |
|              2       3          |
|o2 : Matrix ZZ  <-- ZZ           |
+---------------------------------+
|i3 : ff+gg                       |
|                                 |
|o3 = | 5 7 9 |                   |
|     | 5 7 9 |                   |
|                                 |
|              2       3          |
|o3 : Matrix ZZ  <-- ZZ           |
+---------------------------------+
The matrices in question must have the same number of rows and columns and also
must have the same ring.

Scalars are converted to scalar matrices when necessary.
+--------------------------------+
|i4 : matrix {{1, 2}, {3, 4}} + 5|
|                                |
|o4 = | 6 2 |                    |
|     | 3 9 |                    |
|                                |
|              2       2         |
|o4 : Matrix ZZ  <-- ZZ          |
+--------------------------------+
This is also true for the other arithmetic operations discussed below.

-
==

To subtract two matrices, use the -, operator.
+-----------------------+
|i5 : ff-gg             |
|                       |
|o5 = | -3 -3 -3 |      |
|     | 3  3  3  |      |
|                       |
|              2       3|
|o5 : Matrix ZZ  <-- ZZ |
+-----------------------+
The matrices in question must have the same number of rows and columns and also
must have the same ring.

*
==

To multiply two matrices use the *, operator.
+------------------------------------+
|i6 : R = ZZ/17[a..l];               |
+------------------------------------+
|i7 : ff = matrix {{a,b,c},{d,e,f}}  |
|                                    |
|o7 = | a b c |                      |
|     | d e f |                      |
|                                    |
|             2      3               |
|o7 : Matrix R  <-- R                |
+------------------------------------+
|i8 : gg = matrix {{g,h},{i,j},{k,l}}|
|                                    |
|o8 = | g h |                        |
|     | i j |                        |
|     | k l |                        |
|                                    |
|             3      2               |
|o8 : Matrix R  <-- R                |
+------------------------------------+
|i9 : ff * gg                        |
|                                    |
|o9 = | ag+bi+ck ah+bj+cl |          |
|     | dg+ei+fk dh+ej+fl |          |
|                                    |
|             2      2               |
|o9 : Matrix R  <-- R                |
+------------------------------------+
Suppose we multiply a homogeneous polynomial by a homogeneous matrix. The
result ought to be homogeneous, but how can we arrange that?  Scalar
multiplication should not change the source or target of a map!  Instead, we
introduce one final complication: each matrix records a degree of its own,
which is normally zero, and is used when deciding whether the matrix is
homogeneous.
+-----------------------------------------+
|i10 : R = ZZ/101[x,y,z];                 |
+-----------------------------------------+
|i11 : degree matrix {{x^10}}             |
|                                         |
|o11 = {0}                                |
|                                         |
|o11 : List                               |
+-----------------------------------------+
|i12 : f = matrix {{x,0,y*z},{0,y^2,x^2}};|
|                                         |
|              2      3                   |
|o12 : Matrix R  <-- R                    |
+-----------------------------------------+
|i13 : degree f                           |
|                                         |
|o13 = {0}                                |
|                                         |
|o13 : List                               |
+-----------------------------------------+
Multiplying a matrix by a homogeneous polynomial adds the degree of the
polynomial to the degree of the map.
+-------------------------+
|i14 : h = x^10 * f       |
|                         |
|o14 = | x11 0     x10yz ||
|      | 0   x10y2 x12   ||
|                         |
|              2      3   |
|o14 : Matrix R  <-- R    |
+-------------------------+
|i15 : degree h           |
|                         |
|o15 = {10}               |
|                         |
|o15 : List               |
+-------------------------+
|i16 : degrees source h   |
|                         |
|o16 = {{1}, {2}, {2}}    |
|                         |
|o16 : List               |
+-------------------------+
|i17 : isHomogeneous h    |
|                         |
|o17 = true               |
+-------------------------+
If you don't like this, you have an alternative.  The degree of a tensor
product of two matrices is the sum of the degrees, and its source module is the
tensor product of the source modules.
+-------------------------+
|i18 : h = x^10 ** f      |
|                         |
|o18 = | x11 0     x10yz ||
|      | 0   x10y2 x12   ||
|                         |
|              2      3   |
|o18 : Matrix R  <-- R    |
+-------------------------+
|i19 : degree h           |
|                         |
|o19 = {0}                |
|                         |
|o19 : List               |
+-------------------------+
|i20 : degrees source h   |
|                         |
|o20 = {{11}, {12}, {12}} |
|                         |
|o20 : List               |
+-------------------------+
|i21 : isHomogeneous h    |
|                         |
|o21 = true               |
+-------------------------+

^
==

To raise a square matrix to a power, use the ^, operator.
+------------------------------------------+
|i22 : ff = matrix{{1,2,3},{4,5,6},{7,8,9}}|
|                                          |
|o22 = | 1 2 3 |                           |
|      | 4 5 6 |                           |
|      | 7 8 9 |                           |
|                                          |
|               3       3                  |
|o22 : Matrix ZZ  <-- ZZ                   |
+------------------------------------------+
|i23 : ff^4                                |
|                                          |
|o23 = | 7560  9288  11016 |               |
|      | 17118 21033 24948 |               |
|      | 26676 32778 38880 |               |
|                                          |
|               3       3                  |
|o23 : Matrix ZZ  <-- ZZ                   |
+------------------------------------------+

inverse of a matrix
===================

If a matrix f is invertible, then f^-1 will work.

==
==

To check whether two matrices are equal, one can use ==.
+--------------+
|i24 : ff == gg|
|              |
|o24 = false   |
+--------------+
|i25 : ff == ff|
|              |
|o25 = true    |
+--------------+
However, given two matrices ff and gg, it can be the case that ff - gg == 0
returns true, but ff == gg returns false.
+------------------------------------------+
|i26 : M = R^{1,2,3}                       |
|                                          |
|       3                                  |
|o26 = R                                   |
|                                          |
|o26 : R-module, free, degrees {-1, -2, -3}|
+------------------------------------------+
|i27 : N = R^3                             |
|                                          |
|       3                                  |
|o27 = R                                   |
|                                          |
|o27 : R-module, free                      |
+------------------------------------------+
|i28 : ff = id_M                           |
|                                          |
|o28 = {-1} | 1 0 0 |                      |
|      {-2} | 0 1 0 |                      |
|      {-3} | 0 0 1 |                      |
|                                          |
|              3      3                    |
|o28 : Matrix R  <-- R                     |
+------------------------------------------+
|i29 : gg = id_N                           |
|                                          |
|o29 = | 1 0 0 |                           |
|      | 0 1 0 |                           |
|      | 0 0 1 |                           |
|                                          |
|              3      3                    |
|o29 : Matrix R  <-- R                     |
+------------------------------------------+
|i30 : ff - gg == 0                        |
|                                          |
|o30 = true                                |
+------------------------------------------+
|i31 : ff == gg                            |
|                                          |
|o31 = false                               |
+------------------------------------------+
Since the degrees attached to the matrices were different, see ==,
returned the value false.

!=
==

To check whether two matrices are not equal, one can use !=,:
+--------------+
|i32 : ff != gg|
|              |
|o32 = true    |
+--------------+
From the definition above of ff and gg we see that !=, will return a
value of true, if the degrees attached to the matrices are
different, even if the entries are the same.

**
==

Since tensor product (also known as Kronecker product and outer product) is a
functor of two variables, we may compute the tensor product of two matrices.
Recalling that a matrix is a map between modules, we may write:

       ff : K ---> L
       gg : M ---> N
       ff ** gg : K ** M  ---> L ** N

+-------------------------------------+
|i33 : R = ZZ/17[a..l];               |
+-------------------------------------+
|i34 : ff = matrix {{a,b,c},{d,e,f}}  |
|                                     |
|o34 = | a b c |                      |
|      | d e f |                      |
|                                     |
|              2      3               |
|o34 : Matrix R  <-- R                |
+-------------------------------------+
|i35 : gg = matrix {{g,h},{i,j},{k,l}}|
|                                     |
|o35 = | g h |                        |
|      | i j |                        |
|      | k l |                        |
|                                     |
|              3      2               |
|o35 : Matrix R  <-- R                |
+-------------------------------------+
|i36 : ff ** gg                       |
|                                     |
|o36 = | ag ah bg bh cg ch |          |
|      | ai aj bi bj ci cj |          |
|      | ak al bk bl ck cl |          |
|      | dg dh eg eh fg fh |          |
|      | di dj ei ej fi fj |          |
|      | dk dl ek el fk fl |          |
|                                     |
|              6      6               |
|o36 : Matrix R  <-- R                |
+-------------------------------------+

See also
========

  * extracting information about a matrix

concatenating matrices
**********************

Before Macaulay2 can concatenate matrices, the matrices in question must have
entries in the same ring.

concatenate horizontally
========================

Use |, to concatenate two matrices horizontally.
+------------------------------------------+
|i1 : R = ZZ/32003[a..f];                  |
+------------------------------------------+
|i2 : M = genericMatrix(R,a,3,2)           |
|                                          |
|o2 = | a d |                              |
|     | b e |                              |
|     | c f |                              |
|                                          |
|             3      2                     |
|o2 : Matrix R  <-- R                      |
+------------------------------------------+
|i3 : N = matrix{{d^2,a*d},{b*c,b*d},{a,c}}|
|                                          |
|o3 = | d2 ad |                            |
|     | bc bd |                            |
|     | a  c  |                            |
|                                          |
|             3      2                     |
|o3 : Matrix R  <-- R                      |
+------------------------------------------+
|i4 : M|N                                  |
|                                          |
|o4 = | a d d2 ad |                        |
|     | b e bc bd |                        |
|     | c f a  c  |                        |
|                                          |
|             3      4                     |
|o4 : Matrix R  <-- R                      |
+------------------------------------------+

concatenate vertically
======================

Use ||, to concatenate two matrices vertically.
+----------------------------------------------------+
|i5 : P = matrix{{d^2,a*d,e*f},{b*c,b*d,b*e},{a,c,d}}|
|                                                    |
|o5 = | d2 ad ef |                                   |
|     | bc bd be |                                   |
|     | a  c  d  |                                   |
|                                                    |
|             3      3                               |
|o5 : Matrix R  <-- R                                |
+----------------------------------------------------+
|i6 : transpose(M)||P                                |
|                                                    |
|o6 = {-1} | a  b  c  |                              |
|     {-1} | d  e  f  |                              |
|     {0}  | d2 ad ef |                              |
|     {0}  | bc bd be |                              |
|     {0}  | a  c  d  |                              |
|                                                    |
|             5      3                               |
|o6 : Matrix R  <-- R                                |
+----------------------------------------------------+

making block matrices
=====================

The matrix function can take matrices as input as long as the sizes match up.
+-----------------------------------------------------------------------------+
|i7 : matrix{{id_(R^3),M,P},{random(R^1,R^3),random(R^1,R^3),random(R^1,R^2)}}|
|                                                                             |
|o7 = | 1   0    0     a    d    d2    ad   ef     |                          |
|     | 0   1    0     b    e    bc    bd   be     |                          |
|     | 0   0    1     c    f    a     c    d      |                          |
|     | 107 4376 -5570 3187 3783 -5307 8570 -15344 |                          |
|                                                                             |
|             4      8                                                        |
|o7 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
Also, the number input entries in each row must be equal.  It might seem like
we could form the same matrix with the input
matrix{{id_(R^3),M,P},{random(R^1,R^8)}} since random(R^1,R^8) will construct a
1 by 8 matrix that has the same number of columns as matrix
matrix{{id_(R^3),M,P}} but as input into the matrix function that row entry
must have 3 entries.

direct sum of matrices as maps between modules
==============================================

Use ++, to find the direct sum of two matrices.
+------------------------------------------+
|i8 : R = ZZ/101[x,y,z];                   |
+------------------------------------------+
|i9 : p = matrix table(3,3,(i,j) -> R_i^j) |
|                                          |
|o9 = | 1 x x2 |                           |
|     | 1 y y2 |                           |
|     | 1 z z2 |                           |
|                                          |
|             3      3                     |
|o9 : Matrix R  <-- R                      |
+------------------------------------------+
|i10 : q = matrix table(3,3,(i,j) -> R_j^i)|
|                                          |
|o10 = | 1  1  1  |                        |
|      | x  y  z  |                        |
|      | x2 y2 z2 |                        |
|                                          |
|              3      3                    |
|o10 : Matrix R  <-- R                     |
+------------------------------------------+
|i11 : r=p++q                              |
|                                          |
|o11 = | 1 x x2 0  0  0  |                 |
|      | 1 y y2 0  0  0  |                 |
|      | 1 z z2 0  0  0  |                 |
|      | 0 0 0  1  1  1  |                 |
|      | 0 0 0  x  y  z  |                 |
|      | 0 0 0  x2 y2 z2 |                 |
|                                          |
|              6      6                    |
|o11 : Matrix R  <-- R                     |
+------------------------------------------+
The components of a direct sum can be recovered later.
+--------------------------------+
|i12 : components r              |
|                                |
|o12 = {| 1 x x2 |, | 1  1  1  |}|
|       | 1 y y2 |  | x  y  z  | |
|       | 1 z z2 |  | x2 y2 z2 | |
|                                |
|o12 : List                      |
+--------------------------------+

differentiation
***************

diff
====

diff'
=====

contract
========

contract'
=========

jacobian
========

rank of a matrix
****************

rank
====

rank of a matrix, determined probabilistically
==============================================

determinants and minors
***********************

The command det, can be used to compute the determinant of a
square matrix.
+----------------------------+
|i1 : R = ZZ[a..i];          |
+----------------------------+
|i2 : det matrix{{a,b},{c,d}}|
|                            |
|o2 = - b*c + a*d            |
|                            |
|o2 : R                      |
+----------------------------+
Macaulay2 can use three different algorithms to compute determinants: the
Cofactor, method, which expands a determinant using the standard
cofactor approach, and Bareiss, which uses a fraction-free
variant of Gaussian elimination to compute a determinant. The Dynamic,
algorithm implements a version of cofactor expansion, with caching of
intermediate results. The algorithm to use may be chosen using the optional
Strategy, argument:
+-----------------------------------------------------------------------------+
|i3 : m = matrix{{0,a,b},{a+b,a,d},{e,f,g}}                                   |
|                                                                             |
|o3 = | 0   a b |                                                             |
|     | a+b a d |                                                             |
|     | e   f g |                                                             |
|                                                                             |
|             3      3                                                        |
|o3 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i4 : det(m, Strategy => Cofactor)                                            |
|                                                                             |
|                                2     2                                      |
|o4 = - a*b*e + a*d*e + a*b*f + b f - a g - a*b*g                             |
|                                                                             |
|o4 : R                                                                       |
+-----------------------------------------------------------------------------+
|i5 : minors(2,m, Strategy => Bareiss)                                        |
|                                                                             |
|               2                                          2                  |
|o5 = ideal (- a  - a*b, -a*e, - a*e + a*f + b*f, - a*b - b , -b*e, - d*e +   |
|     ------------------------------------------------------------------------|
|     a*g + b*g, - a*b + a*d, - b*f + a*g, - d*f + a*g)                       |
|                                                                             |
|o5 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i6 : exteriorPower(2,m, Strategy => Dynamic)                                 |
|                                                                             |
|o6 = | -a2-ab    -ab-b2    -ab+ad |                                          |
|     | -ae       -be       -bf+ag |                                          |
|     | -ae+af+bf -de+ag+bg -df+ag |                                          |
|                                                                             |
|             3      3                                                        |
|o6 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
One warning is in order here: the Bareiss algorithm requires division in the
base ring, and so can yield the INCORRECT answer if the base ring contains zero
divisors.  However, the Bareiss algorithm is often dramatically faster than the
cofactor method, unless the matrix is particularly sparse.  Consequently, the
default strategy for rings which are fields or are not quotients of polynomial
rings is Bareiss, while the default for quotients of polynomial
rings that are not (declared to be) fields is Cofactor. The
Dynamic, algorithm can sometimes also result in significant
speedups compared to Cofactor, and Bareiss, at
the cost of a slight memory overhead.

The command minors, can be used to construct the
ideal generated by the n by n minors of a matrix. Recall that the n by n minors
of a matrix are the determinants of the n by n submatrices of a matrix.
+-------------------------------------------+
|i7 : R = QQ[x,y,z];                        |
+-------------------------------------------+
|i8 : f = matrix{{x,y,z},{y,z,x^2}}         |
|                                           |
|o8 = | x y z  |                            |
|     | y z x2 |                            |
|                                           |
|             2      3                      |
|o8 : Matrix R  <-- R                       |
+-------------------------------------------+
|i9 : I = minors(2,f)                       |
|                                           |
|               2         3         2     2 |
|o9 = ideal (- y  + x*z, x  - y*z, x y - z )|
|                                           |
|o9 : Ideal of R                            |
+-------------------------------------------+
Sometimes finer control is needed when one is computing the ideal of minors of
a larger matrix.  Compute the ideal of some determinants using minors,
with optional arguments as in
+----------------------------------------------------+
|i10 : R = ZZ[a..i];                                 |
+----------------------------------------------------+
|i11 : M = genericMatrix(R,a,3,3);                   |
|                                                    |
|              3      3                              |
|o11 : Matrix R  <-- R                               |
+----------------------------------------------------+
|i12 : minors(2,M,First => {{0,1},{1,2}}, Limit => 3)|
|                                                    |
|o12 = ideal (- e*g + d*h, - f*g + d*i, - f*h + e*i) |
|                                                    |
|o12 : Ideal of R                                    |
+----------------------------------------------------+
The argument to the optional argument First, is the list of row
and column positions to use for the first minor.  Starting at this first minor,
we then compute three minors.

Pfaffians
*********

pfaffians
=========

exterior power of a matrix
**************************

Since the i-th exterior power is a functor, it applies to matrices as well as
to modules.
+-----------------------------------------------------------------------------+
|i1 : R = ZZ[vars(0..19)]                                                     |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : ff = genericMatrix(R,4,5)                                               |
|                                                                             |
|o2 = | a e i m q |                                                           |
|     | b f j n r |                                                           |
|     | c g k o s |                                                           |
|     | d h l p t |                                                           |
|                                                                             |
|             4      5                                                        |
|o2 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i3 : exteriorPower (2,ff)                                                    |
|                                                                             |
|o3 = | -be+af -bi+aj -fi+ej -bm+an -fm+en -jm+in -bq+ar -fq+er -jq+ir -nq+mr |
|     | -ce+ag -ci+ak -gi+ek -cm+ao -gm+eo -km+io -cq+as -gq+es -kq+is -oq+ms |
|     | -cf+bg -cj+bk -gj+fk -cn+bo -gn+fo -kn+jo -cr+bs -gr+fs -kr+js -or+ns |
|     | -de+ah -di+al -hi+el -dm+ap -hm+ep -lm+ip -dq+at -hq+et -lq+it -pq+mt |
|     | -df+bh -dj+bl -hj+fl -dn+bp -hn+fp -ln+jp -dr+bt -hr+ft -lr+jt -pr+nt |
|     | -dg+ch -dk+cl -hk+gl -do+cp -ho+gp -lo+kp -ds+ct -hs+gt -ls+kt -ps+ot |
|     ------------------------------------------------------------------------|
|     |                                                                       |
|     |                                                                       |
|     |                                                                       |
|     |                                                                       |
|     |                                                                       |
|     |                                                                       |
|                                                                             |
|             6      10                                                       |
|o3 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
Note that each entry of in the above matrix is a 2 by 2 minor (the determinant
of a 2 by 2 submatrix) of the matrix ff.

The signs are chosen so that this operation commutes with multiplication:
+--------------------------------------------------------------------+
|i4 : S = QQ[x_(1,1) .. x_(3,5), y_(1,1) .. y_(5,4)]                 |
|                                                                    |
|o4 = S                                                              |
|                                                                    |
|o4 : PolynomialRing                                                 |
+--------------------------------------------------------------------+
|i5 : M = transpose genericMatrix(S,x_(1,1),5,3)                     |
|                                                                    |
|o5 = {-1} | x_(1,1) x_(1,2) x_(1,3) x_(1,4) x_(1,5) |               |
|     {-1} | x_(2,1) x_(2,2) x_(2,3) x_(2,4) x_(2,5) |               |
|     {-1} | x_(3,1) x_(3,2) x_(3,3) x_(3,4) x_(3,5) |               |
|                                                                    |
|             3      5                                               |
|o5 : Matrix S  <-- S                                                |
+--------------------------------------------------------------------+
|i6 : N = transpose genericMatrix(S,y_(1,1),4,5)                     |
|                                                                    |
|o6 = {-1} | y_(1,1) y_(1,2) y_(1,3) y_(1,4) |                       |
|     {-1} | y_(2,1) y_(2,2) y_(2,3) y_(2,4) |                       |
|     {-1} | y_(3,1) y_(3,2) y_(3,3) y_(3,4) |                       |
|     {-1} | y_(4,1) y_(4,2) y_(4,3) y_(4,4) |                       |
|     {-1} | y_(5,1) y_(5,2) y_(5,3) y_(5,4) |                       |
|                                                                    |
|             5      4                                               |
|o6 : Matrix S  <-- S                                                |
+--------------------------------------------------------------------+
|i7 : exteriorPower(3,M*N) == exteriorPower(3,M) * exteriorPower(3,N)|
|                                                                    |
|o7 = true                                                           |
+--------------------------------------------------------------------+

See also
========

  * exterior power of a module

format and display of matrices in Macaulay2
*******************************************

By default, Macaulay2 displays matrices in a compact form.
+------------------------------------------+
|i1 : QQ[x,y];                             |
+------------------------------------------+
|i2 : f = matrix{{x^2, x*y},{x*y, y^2}}    |
|                                          |
|o2 = | x2 xy |                            |
|     | xy y2 |                            |
|                                          |
|                      2               2   |
|o2 : Matrix (QQ[x..y])  <-- (QQ[x..y])    |
+------------------------------------------+
|i3 : dual f                               |
|                                          |
|o3 = {-2} | x2 xy |                       |
|     {-2} | xy y2 |                       |
|                                          |
|                      2               2   |
|o3 : Matrix (QQ[x..y])  <-- (QQ[x..y])    |
+------------------------------------------+
|i4 : source f                             |
|                                          |
|               2                          |
|o4 = (QQ[x..y])                           |
|                                          |
|o4 : QQ[x..y]-module, free, degrees {2:2} |
+------------------------------------------+
|i5 : target dual f                        |
|                                          |
|               2                          |
|o5 = (QQ[x..y])                           |
|                                          |
|o5 : QQ[x..y]-module, free, degrees {2:-2}|
+------------------------------------------+
Integers inside braces to the left of the matrix give the degrees of the basis
elements of the target of the matrix; they are omitted if the degrees are all
zero.

Note how the exponents have been placed to the right of the variables rather
than formatted in superscript.  While this format is generally considered to be
desirable, this can be turned off by setting the variable
compactMatrixForm, to false.
+---------------------------------------------------+
|i6 : compactMatrixForm = false                     |
|                                                   |
|o6 = false                                         |
+---------------------------------------------------+
|i7 : matrix{{x^2 + 3, x^4 + 1},{x^13 - 5, x^7 - 1}}|
|                                                   |
|     |    2       4      |                         |
|o7 = |   x  + 3  x  + 1  |                         |
|     |                   |                         |
|     |   13       7      |                         |
|     |  x   - 5  x  - 1  |                         |
|                                                   |
|                      2               2            |
|o7 : Matrix (QQ[x..y])  <-- (QQ[x..y])             |
+---------------------------------------------------+
To have Macaulay2 display matrices in compact form again, type:
+---------------------------------------------------+
|i8 : compactMatrixForm = true                      |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+
|i9 : matrix{{x^2 + 3, x^4 + 1},{x^13 - 5, x^7 - 1}}|
|                                                   |
|o9 = | x2+3  x4+1 |                                |
|     | x13-5 x7-1 |                                |
|                                                   |
|                      2               2            |
|o9 : Matrix (QQ[x..y])  <-- (QQ[x..y])             |
+---------------------------------------------------+

importing and exporting matrices
********************************

toString
========

toExternalString
================

substitution and maps between rings
***********************************

An overview
===========

For additional common operations and a comprehensive list of all routines in
Macaulay2 which return or use ring maps, see RingMap.

Substitution

Ring maps

substitute -- substituting values for variables
***********************************************

Synopsis
========

  * Usage:
        substitute(f,v)
        sub(f,v)
  * Inputs:
      * f, a ring element, a matrix, an
        ideal, a module, a vector,
        or an expression, over a ring R
      * v, a ring, a matrix, an option,
        or a list, of options,
  * Outputs:
      * An object of the same sort as f, obtained by substituting values for
        the variables in the ring R of f using v.

Description
===========

A convenient abbreviation for substitute, is sub.

This function allows you to substitute values for some variables.  There are
three ways to describe the kind of substitution, depending on the second
argument v.
  * give specific values for (some of) the variables.  An option x=>r specifies
    that a generator x should be replaced by the ring element r.  Generators
    not mentioned will be preserved.
  * give a matrix, the entries determines the values of each of the variables
  * give a ring, the effect will be to substitute variables with variables of
    the same name, into this new ring
+-------------------------------------------------+
|i1 : A = QQ[a..f]; B = QQ[a..d]; C = ZZ/101[x,y];|
+-------------------------------------------------+
|i4 : F = 3*a^2-b-d+101*c                         |
|                                                 |
|       2                                         |
|o4 = 3a  - b + 101c - d                          |
|                                                 |
|o4 : B                                           |
+-------------------------------------------------+
The following line substitutes values for a and b, and the result is in the
same ring B of F.
+---------------------------+
|i5 : sub(F, {a=>1, b=>b^4})|
|                           |
|        4                  |
|o5 = - b  + 101c - d + 3   |
|                           |
|o5 : B                     |
+---------------------------+
Substitute a by x, b by y and so on.  The result is a polynomial in the ring C.
+------------------------------+
|i6 : sub(F, matrix{{x,y,1,0}})|
|                              |
|       2                      |
|o6 = 3x  - y                  |
|                              |
|o6 : C                        |
+------------------------------+
Using a ring as the second argument substitutes variables with the same name.
The following produces the polynomial F in the rings A and D.
+-----------------------+
|i7 : sub(F, A)         |
|                       |
|       2               |
|o7 = 3a  - b + 101c - d|
|                       |
|o7 : A                 |
+-----------------------+
|i8 : D = B/(a*b*c*d);  |
+-----------------------+
|i9 : sub(F,D)          |
|                       |
|       2               |
|o9 = 3a  - b + 101c - d|
|                       |
|o9 : D                 |
+-----------------------+
If the values of all of the variables are in a different ring, then the result
will be in that ring.
+----------------------------------------+
|i10 : use ring F;                       |
+----------------------------------------+
|i11 : sub(F, {a=>1, b=>3, c=> 1, d=>13})|
|                                        |
|o11 = 88                                |
|                                        |
|o11 : QQ                                |
+----------------------------------------+
If f is an ideal or a submodule of a free module over R, then substitution
amounts to substitution in the matrix of generators of f.  This is not the same
as tensor product!
+--------------------------------------+
|i12 : use B;                          |
+--------------------------------------+
|i13 : M = image(vars B ++ vars B)     |
|                                      |
|o13 = image | a b c d 0 0 0 0 |       |
|            | 0 0 0 0 a b c d |       |
|                                      |
|                              2       |
|o13 : B-module, submodule of B        |
+--------------------------------------+
|i14 : N = substitute(M, {a=>b+c,c=>1})|
|                                      |
|o14 = image | b+c b 1 d 0   0 0 0 |   |
|            | 0   0 0 0 b+c b 1 d |   |
|                                      |
|                              2       |
|o14 : B-module, submodule of B        |
+--------------------------------------+
Although we cannot use substitute directly on modules which are not submodules,
here is a useful idiom for moving a cokernel module to another ring.  One must
be careful though: the degrees of the generators might not be the desired ones.
+----------------------------------------------------------------+
|i15 : M' = prune M                                              |
|                                                                |
|o15 = cokernel {1} | -b 0  -c 0  0  -d 0  0  0  0  0  0  |      |
|               {1} | a  -c 0  0  -d 0  0  0  0  0  0  0  |      |
|               {1} | 0  b  a  -d 0  0  0  0  0  0  0  0  |      |
|               {1} | 0  0  0  c  b  a  0  0  0  0  0  0  |      |
|               {1} | 0  0  0  0  0  0  -b 0  -c 0  0  -d |      |
|               {1} | 0  0  0  0  0  0  a  -c 0  0  -d 0  |      |
|               {1} | 0  0  0  0  0  0  0  b  a  -d 0  0  |      |
|               {1} | 0  0  0  0  0  0  0  0  0  c  b  a  |      |
|                                                                |
|                             8                                  |
|o15 : B-module, quotient of B                                   |
+----------------------------------------------------------------+
|i16 : N' = coker substitute(presentation M', {a=>b+c,c=>1})     |
|                                                                |
|o16 = cokernel {1} | -b  0  -1  0  0  -d  0   0  0   0  0  0   ||
|               {1} | b+c -1 0   0  -d 0   0   0  0   0  0  0   ||
|               {1} | 0   b  b+c -d 0  0   0   0  0   0  0  0   ||
|               {1} | 0   0  0   1  b  b+c 0   0  0   0  0  0   ||
|               {1} | 0   0  0   0  0  0   -b  0  -1  0  0  -d  ||
|               {1} | 0   0  0   0  0  0   b+c -1 0   0  -d 0   ||
|               {1} | 0   0  0   0  0  0   0   b  b+c -d 0  0   ||
|               {1} | 0   0  0   0  0  0   0   0  0   1  b  b+c ||
|                                                                |
|                             8                                  |
|o16 : B-module, quotient of B                                   |
+----------------------------------------------------------------+
Unevaluated expressions (i.e. from hilbertSeries) may
also have variables substituted in all of the ways mentioned so far.
+--------------------------------------------------+
|i17 : hf = hilbertSeries coker matrix{{a,b^3,d^5}}|
|                                                  |
|               3    4    5    6    8    9         |
|      1 - T - T  + T  - T  + T  + T  - T          |
|o17 = -----------------------------------         |
|                           4                      |
|                    (1 - T)                       |
|                                                  |
|o17 : Expression of class Divide                  |
+--------------------------------------------------+
|i18 : hf1 = reduceHilbert hf                      |
|                                                  |
|                 2     3     4     5    6         |
|      1 + 2T + 3T  + 3T  + 3T  + 2T  + T          |
|o18 = -----------------------------------         |
|                    (1 - T)                       |
|                                                  |
|o18 : Expression of class Divide                  |
+--------------------------------------------------+
|i19 : use ring numerator hf;                      |
+--------------------------------------------------+
|i20 : sub(hf1, T => -1)                           |
|                                                  |
|      1                                           |
|o20 = -                                           |
|      2                                           |
|                                                  |
|o20 : Expression of class Divide                  |
+--------------------------------------------------+
Of course, we can change the ring too:
+-------------------------------------------+
|i21 : sub(hf, T => a)                      |
|                                           |
|         9    8    6    5    4    3        |
|      - a  + a  + a  - a  + a  - a  - a + 1|
|o21 = -------------------------------------|
|                             4             |
|                    (- a + 1)              |
|                                           |
|o21 : Expression of class Divide           |
+-------------------------------------------+
|i22 : value oo                             |
|                                           |
|         6     5     4     3     2         |
|      - a  - 2a  - 3a  - 3a  - 3a  - 2a - 1|
|o22 = -------------------------------------|
|                      a - 1                |
|                                           |
|o22 : frac B                               |
+-------------------------------------------+
|i23 : oo == value sub(hf1, T=>a)           |
|                                           |
|o23 = true                                 |
+-------------------------------------------+

If you plan on using the same substitution over and over, it is wise to create
a ring map that will perform the same substitution.

For example, in the first example above, we can make a ring map,
G, and then apply it to F.

+---------------------------------+
|i24 : use B;                     |
+---------------------------------+
|i25 : G = map(B,B,{a=>1, b=>b^4})|
|                                 |
|                      4          |
|o25 = map (B, B, {1, b , c, d})  |
|                                 |
|o25 : RingMap B <-- B            |
+---------------------------------+
|i26 : G F                        |
|                                 |
|         4                       |
|o26 = - b  + 101c - d + 3        |
|                                 |
|o26 : B                          |
+---------------------------------+

Caveat
======

The specified substitution is not checked to see whether the corresponding ring
homomorphism is well-defined; this may produce surprising results, especially
if rational coefficients are converted to integer coefficients.

See also
========

  * RingMap -- the class of all ring maps
  * hilbertSeries -- compute the Hilbert series
  * value -- evaluate
  * Expression -- the class of all expressions

Ways to use substitute:
=======================

  * "substitute(Ideal,List)"
  * "substitute(Ideal,Matrix)"
  * "substitute(Ideal,Option)"
  * "substitute(Ideal,Ring)"
  * "substitute(Ideal,RingFamily)"
  * "substitute(Matrix,List)"
  * "substitute(Matrix,Matrix)"
  * "substitute(Matrix,Option)"
  * "substitute(Matrix,Ring)"
  * "substitute(Matrix,RingFamily)"
  * "substitute(Matrix,ZZ)"
  * "substitute(Module,List)"
  * "substitute(Module,Matrix)"
  * "substitute(Module,Option)"
  * "substitute(Module,Ring)"
  * "substitute(Module,RingFamily)"
  * "substitute(Number,Ring)"
  * "substitute(Number,RingFamily)"
  * "substitute(RingElement,List)"
  * "substitute(RingElement,Matrix)"
  * "substitute(RingElement,Option)"
  * "substitute(RingElement,Ring)"
  * "substitute(RingElement,RingFamily)"
  * "substitute(Vector,List)"
  * "substitute(Vector,Matrix)"
  * "substitute(Vector,Option)"
  * "substitute(Vector,Ring)"
  * "substitute(Vector,RingFamily)"

For the programmer
==================

The object substitute, is a method function.

RingElement Sequence -- evaluation of polynomials
*************************************************

Synopsis
========

  * Operator: SPACE,
  * Usage:
        f(a,b,c)
  * Inputs:
      * f, a ring element,
      * (a,b,c), a sequence of numbers or ring elements
  * Outputs:
      * r, a ring element, the result of evaluating f at
        the provided values

Description
===========

+---------------------------+
|i1 : R = QQ[x,y,z];        |
+---------------------------+
|i2 : f = x^3 - y^2 + 999*z;|
+---------------------------+
|i3 : f(10,0,0)             |
|                           |
|o3 = 1000                  |
|                           |
|o3 : QQ                    |
+---------------------------+
|i4 : f(0,1,0)              |
|                           |
|o4 = -1                    |
|                           |
|o4 : QQ                    |
+---------------------------+
|i5 : f(0,0,1)              |
|                           |
|o5 = 999                   |
|                           |
|o5 : QQ                    |
+---------------------------+
|i6 : f(10,1,-1)            |
|                           |
|o6 = 0                     |
|                           |
|o6 : QQ                    |
+---------------------------+
|i7 : x^3 * f(0,0,1)        |
|                           |
|         3                 |
|o7 = 999x                  |
|                           |
|o7 : R                     |
+---------------------------+
|i8 : f(0,0,x+y+z) / 999    |
|                           |
|o8 = x + y + z             |
|                           |
|o8 : R                     |
+---------------------------+
|i9 : f(z,y,x)              |
|                           |
|      3    2               |
|o9 = z  - y  + 999x        |
|                           |
|o9 : R                     |
+---------------------------+
|i10 : f(x,x,x)             |
|                           |
|       3    2              |
|o10 = x  - x  + 999x       |
|                           |
|o10 : R                    |
+---------------------------+

Note that giving fewer variables results in partial evaluation.

+------------------------+
|i11 : f(10)             |
|                        |
|         2              |
|o11 = - y  + 999z + 1000|
|                        |
|o11 : R                 |
+------------------------+
|i12 : f(10,y,z)         |
|                        |
|         2              |
|o12 = - y  + 999z + 1000|
|                        |
|o12 : R                 |
+------------------------+

See also
========

  * RingMap RingElement -- apply a ring map

Ways to use this method:
========================

  * "RingElement Number"
  * "RingElement RingElement"
  * RingElement Sequence -- evaluation of
    polynomials

working with multiple rings
***************************

Working with multiple rings is more subtle than simply replacing values of the
variables in a ring.  On the other hand it is particularly easy in Macaulay2.
We define a sequence of rings below and move between each to show both the
dangers and the convenience.

defining multiple rings
=======================

+--------------------------------------------+
|i1 : R1 = ZZ/101;                           |
+--------------------------------------------+
|i2 : R2 = ZZ/101[s,t];                      |
+--------------------------------------------+
|i3 : describe R2                            |
|                                            |
|o3 = R1[s..t, Degrees => {2:1}, Heft => {1}]|
+--------------------------------------------+
Notice that Macaulay2 sees the coefficient ring as R1, we could just as easily
defined R2 as R1[s,t] . Movement and addition between these rings is easy.
+---------------------------+
|i4 : I = ideal (s^4+t^2+1);|
|                           |
|o4 : Ideal of R2           |
+---------------------------+
|i5 : R3 = R2/I;            |
+---------------------------+
|i6 : describe R3           |
|                           |
|          R2               |
|o6 = -----------           |
|      4    2               |
|     s  + t  + 1           |
+---------------------------+
Since I is defined as an ideal in R2 we cannot type ZZ/101[s,t]/I as the
computer sees ZZ/101[s,t] as different from R2 and so does not see I as being
in this ring.  For more about defining rings see rings.  We now
work with moving between R2 and R3.

moving between rings using use and substitute
=============================================

+------------------+
|i7 : f = s^4+1    |
|                  |
|       2          |
|o7 = -t           |
|                  |
|o7 : R3           |
+------------------+
|i8 : g = s^4+t^2+1|
|                  |
|o8 = 0            |
|                  |
|o8 : R3           |
+------------------+
f and g are elements in R3 now and this is shown by the fact that Macaulay2
sees them as -t^2 and 0.  To recover these elements as polynomials in R2 type
use R2 and define them again in R2.  The command substitute does not work well
here, where as if we want to see the image of elements of R2 in R3 it does work
well and without using the command use.  Macaulay2 always tells you which ring
an element is in on the line after it prints the ring element.
+----------------------+
|i9 : use R2;          |
+----------------------+
|i10 : substitute(g,R2)|
|                      |
|o10 = 0               |
|                      |
|o10 : R2              |
+----------------------+
|i11 : f = s^4+1       |
|                      |
|       4              |
|o11 = s  + 1          |
|                      |
|o11 : R2              |
+----------------------+
|i12 : g = s^4+t^2+1   |
|                      |
|       4    2         |
|o12 = s  + t  + 1     |
|                      |
|o12 : R2              |
+----------------------+
|i13 : substitute(f,R3)|
|                      |
|        2             |
|o13 = -t              |
|                      |
|o13 : R3              |
+----------------------+

subtleties of substitute and describe
=====================================

Now we complicate things further by constructing a fraction field and then
further constructing polynomial rings and quotient rings.  First we see that
while describe, helped us to see how we defined R2 and R3, the
same does not hold when a fraction field is constructed.  Note that R3 is a
domain.
+-----------------------+
|i14 : describe R3      |
|                       |
|           R2          |
|o14 = -----------      |
|       4    2          |
|      s  + t  + 1      |
+-----------------------+
|i15 : R4 = frac R3;    |
+-----------------------+
|i16 : describe R4      |
|                       |
|          /     R2    \|
|o16 = frac|-----------||
|          | 4    2    ||
|          \s  + t  + 1/|
+-----------------------+
The command substitute, works well to move elements from R2
or R3 to R4. An alternative to substitute is to form the canonical injection of
R3 into R4 (the same can be done for the canonical projection from R2 to R3
above - we do the example here).  To move elements from R4 back to R3 an
alternate method must be used.  Also, the method of constructing a map does not
work well in the reverse direction for the same reasons substitute,
does not.
+---------------------------+
|i17 : use R2;              |
+---------------------------+
|i18 : f = s^4+1;           |
+---------------------------+
|i19 : substitute(f,R4)     |
|                           |
|        2                  |
|o19 = -t                   |
|                           |
|o19 : R4                   |
+---------------------------+
|i20 : use R3;              |
+---------------------------+
|i21 : g = substitute(f,R3);|
+---------------------------+
|i22 : substitute(g,R4)     |
|                           |
|        2                  |
|o22 = -t                   |
|                           |
|o22 : R4                   |
+---------------------------+
|i23 : F = map(R4,R3)       |
|                           |
|o23 = map (R4, R3, {s, t}) |
|                           |
|o23 : RingMap R4 <-- R3    |
+---------------------------+
|i24 : F(f)                 |
|                           |
|        2                  |
|o24 = -t                   |
|                           |
|o24 : R4                   |
+---------------------------+

non-standard coefficient fields
===============================

We can go through the whole process again using R4 now as the field.
+-----------------------------------------------------+
|i25 : R5 = R4[u,v,w];                                |
+-----------------------------------------------------+
|i26 : describe R5                                    |
|                                                     |
|o26 = R4[u..w, Degrees => {3:1}, Heft => {1}]        |
+-----------------------------------------------------+
|i27 : J = ideal(u^3-v^2*w+w^3,v^2+w^2,u*v-v*w+u*w)   |
|                                                     |
|              3    2     3   2    2                  |
|o27 = ideal (u  - v w + w , v  + w , u*v + u*w - v*w)|
|                                                     |
|o27 : Ideal of R5                                    |
+-----------------------------------------------------+
|i28 : R6 = R5/J;                                     |
+-----------------------------------------------------+
|i29 : describe R6                                    |
|                                                     |
|                          R5                         |
|o29 = -----------------------------------------      |
|        3    2     3   2    2                        |
|      (u  - v w + w , v  + w , u*v + u*w - v*w)      |
+-----------------------------------------------------+
Notice that at each stage Macaulay2 only refers back to the last ring we
defined.  All of the methods above still work here in theory, but caution is
advised.  We give an example below to illustrate.  Also, note that many other
computations will no longer work, because Gröbner basis computations only work
over ZZ, ZZ/n and QQ, at this time.

using maps to move between rings
================================

+--------------------------+
|i30 : map(R6,R2)          |
|                          |
|o30 = map (R6, R2, {s, t})|
|                          |
|o30 : RingMap R6 <-- R2   |
+--------------------------+
|i31 : substitute(f,R6)    |
|                          |
|        2                 |
|o31 = -t                  |
|                          |
|o31 : R6                  |
+--------------------------+
Macaulay2 claims this is the zero map, and that the image of f is 1, but we
know better.  By forming a series of maps and composing them we see the map
that makes sense.  We also contrast the map with using substitute.
+----------------------------+
|i32 : use R2;               |
+----------------------------+
|i33 : f = s^4+1;            |
+----------------------------+
|i34 : F = map(R4,R2);       |
|                            |
|o34 : RingMap R4 <-- R2     |
+----------------------------+
|i35 : G = map(R5,R4);       |
|                            |
|o35 : RingMap R5 <-- R4     |
+----------------------------+
|i36 : H = map(R6,R5);       |
|                            |
|o36 : RingMap R6 <-- R5     |
+----------------------------+
|i37 : H(G(F(f)))            |
|                            |
|        2                   |
|o37 = -t                    |
|                            |
|o37 : R6                    |
+----------------------------+
|i38 : f1 = substitute(f,R4) |
|                            |
|        2                   |
|o38 = -t                    |
|                            |
|o38 : R4                    |
+----------------------------+
|i39 : f2 = substitute(f1,R5)|
|                            |
|        2                   |
|o39 = -t                    |
|                            |
|o39 : R5                    |
+----------------------------+
|i40 : substitute(f2,R6)     |
|                            |
|        2                   |
|o40 = -t                    |
|                            |
|o40 : R6                    |
+----------------------------+

elements versus matrices
========================

Finally, note that everywhere we used the element f we can place a matrix or an
ideal and get similar results.

substitute(J,vars R)
====================

We close this long example with a brief discussion of substitute(J,vars R).
This command is more sensitive than substitute as it will give an error message
when the variables involved do not match up.
+--------------------------------------------------+
|i41 : substitute(f,vars R3)                       |
|                                                  |
|        2                                         |
|o41 = -t                                          |
|                                                  |
|o41 : R3                                          |
+--------------------------------------------------+
|i42 : try substitute(f,vars R5) else "found error"|
|                                                  |
|o42 = found error                                 |
+--------------------------------------------------+

basic construction, source and target of a ring map
***************************************************

constructing a ring map
=======================

Use the function map, to construct a map between two rings.  The
input, in order, is the target, the source, and the images of the variables of
the source ring.  The images can be given as a matrix or a list.
+--------------------------------------+
|i1 : S = QQ[x,y,z]/ideal(x^3+y^3+z^3);|
+--------------------------------------+
|i2 : T = QQ[u,v,w]/ideal(u^3+v^3+w^3);|
+--------------------------------------+
|i3 : G = map(T,S,matrix{{u,v,w^2}})   |
|                                      |
|                        2             |
|o3 = map (T, S, {u, v, w })           |
|                                      |
|o3 : RingMap T <-- S                  |
+--------------------------------------+
|i4 : G(x^3+y^3+z)                     |
|                                      |
|        6    2                        |
|o4 = - w  + w                         |
|                                      |
|o4 : T                                |
+--------------------------------------+
If the third argument is not given there are two possibilities.  If a variable
in the source ring also appears in the target ring then that variable is mapped
to itself and if a variable does not appear in the target ring then it is
mapped to zero.
+--------------------------+
|i5 : R = QQ[x,y,w];       |
+--------------------------+
|i6 : F = map(S,R)         |
|                          |
|o6 = map (S, R, {x, y, 0})|
|                          |
|o6 : RingMap S <-- R      |
+--------------------------+
|i7 : F(x^3)               |
|                          |
|        3    3            |
|o7 = - y  - z             |
|                          |
|o7 : S                    |
+--------------------------+

source and target
=================

Once a ring map is defined the functions source, and
target, can be used to find out what the source and target of a map
are.  These functions are particularly useful when working with matrices (see
the next example).
+---------------------------------------------------+
|i8 : U = QQ[s,t,u, Degrees => {{1,2},{1,1},{1,3}}];|
+---------------------------------------------------+
|i9 : H = map(U,R,matrix{{s^2,t^3,u^4}})            |
|                                                   |
|                  2   3   4                        |
|o9 = map (U, R, {s , t , u })                      |
|                                                   |
|o9 : RingMap U <-- R                               |
+---------------------------------------------------+
|i10 : use R; H(x^2+y^2+w^2)                        |
|                                                   |
|       8    6    4                                 |
|o11 = u  + t  + s                                  |
|                                                   |
|o11 : U                                            |
+---------------------------------------------------+
|i12 : source H                                     |
|                                                   |
|o12 = R                                            |
|                                                   |
|o12 : PolynomialRing                               |
+---------------------------------------------------+
|i13 : target H                                     |
|                                                   |
|o13 = U                                            |
|                                                   |
|o13 : PolynomialRing                               |
+---------------------------------------------------+

obtaining the matrix defining a map
===================================

Use F.matrix to obtain the matrix defining the map F.
+----------------------+
|i14 : H.matrix        |
|                      |
|o14 = | s2 t3 u4 |    |
|                      |
|              1      3|
|o14 : Matrix U  <-- U |
+----------------------+
|i15 : source H.matrix |
|                      |
|       3              |
|o15 = U               |
|                      |
|o15 : U-module, free  |
+----------------------+
|i16 : target H.matrix |
|                      |
|       1              |
|o16 = U               |
|                      |
|o16 : U-module, free  |
+----------------------+
For more on matrices from maps see inputting a matrix.

evaluation and composition of ring maps
***************************************

evaluating ring maps
====================

Once a ring map F is defined, the image of an element m in the source ring can
be found by applying the map as F(m).
+-------------------------------------------------------------------+
|i1 : R = ZZ[x,y,z];                                                |
+-------------------------------------------------------------------+
|i2 : S = ZZ/101[x,y,z,Degrees => {{1,2},{1,3},{1,3}}]/ideal(x+z^3);|
+-------------------------------------------------------------------+
|i3 : F = map(S,R,{x,y^2,z^3})                                      |
|                                                                   |
|                     2                                             |
|o3 = map (S, R, {x, y , -x})                                       |
|                                                                   |
|o3 : RingMap S <-- R                                               |
+-------------------------------------------------------------------+
|i4 : use R; F(107*x+y+z)                                           |
|                                                                   |
|      2                                                            |
|o5 = y  + 5x                                                       |
|                                                                   |
|o5 : S                                                             |
+-------------------------------------------------------------------+

composition of ring maps
========================

The function RingMap * RingMap, performs a composition of ring maps.
Evaluation of elements in the source of a ring map G can also be done using
F(G(m)).
+----------------------------+
|i6 : T = ZZ/5[x,y];         |
+----------------------------+
|i7 : G = map(T,S);          |
|                            |
|o7 : RingMap T <-- S        |
+----------------------------+
|i8 : G*F                    |
|                            |
|                     2      |
|o8 = map (T, R, {x, y , -x})|
|                            |
|o8 : RingMap T <-- R        |
+----------------------------+
|i9 : use R; G(F(107*x+y+z)) |
|                            |
|       2                    |
|o10 = y                     |
|                            |
|o10 : T                     |
+----------------------------+

kernel and coimage of a ring map
********************************

The kernel and coimage of a ring map can be computed using coimage,
and ker, .  The output of ker is an ideal and the output
of coimage is a ring or quotient ring.
+-----------------------------------------------+
|i1 : R = QQ[x,y,w]; U = QQ[s,t]/ideal(s^4+t^4);|
+-----------------------------------------------+
|i3 : H = map(U,R,matrix{{s^2,s*t,t^2}})        |
|                                               |
|                  2        2                   |
|o3 = map (U, R, {s , s*t, t })                 |
|                                               |
|o3 : RingMap U <-- R                           |
+-----------------------------------------------+
|i4 : ker H                                     |
|                                               |
|             2         2    2                  |
|o4 = ideal (y  - x*w, x  + w )                 |
|                                               |
|o4 : Ideal of R                                |
+-----------------------------------------------+
|i5 : coimage H                                 |
|                                               |
|              R                                |
|o5 = -------------------                       |
|       2         2    2                        |
|     (y  - x*w, x  + w )                       |
|                                               |
|o5 : QuotientRing                              |
+-----------------------------------------------+

graphIdeal(RingMap) -- the ideal of the graph of the regular map corresponding to a ring map
********************************************************************************************

Synopsis
========

  * Function: graphIdeal,
  * Usage:
        graphIdeal f
  * Inputs:
      * f
  * Optional inputs,:
      * MonomialOrder => ..., default value {GRevLex, Position => Up}, a
        monomial ordering, see monomial orderings,
      * MonomialSize => an integer, default value 32, the monomial
        size, see MonomialSize,
      * VariableBaseName => a symbol, default value "p", the
        variable base name, see VariableBaseName,
  * Outputs:
      * an ideal, the ideal of the graph of regular map
        corresponding to f

Description
===========

+----------------------------------------------+
|i1 : R = QQ[x,y]                              |
|                                              |
|o1 = R                                        |
|                                              |
|o1 : PolynomialRing                           |
+----------------------------------------------+
|i2 : S = QQ[s,t,u]                            |
|                                              |
|o2 = S                                        |
|                                              |
|o2 : PolynomialRing                           |
+----------------------------------------------+
|i3 : f = map(R,S,{x^2,x*y,y^2})               |
|                                              |
|                  2        2                  |
|o3 = map (R, S, {x , x*y, y })                |
|                                              |
|o3 : RingMap R <-- S                          |
+----------------------------------------------+
|i4 : graphIdeal f                             |
|                                              |
|               2                       2      |
|o4 = ideal (- p  + p , - p p  + p , - p  + p )|
|               0    2     0 1    3     1    4 |
|                                              |
|o4 : Ideal of QQ[p ..p ]                      |
|                  0   4                       |
+----------------------------------------------+

See also
========

  * graphRing -- the coordinate ring of the
    graph of the regular map corresponding to a ring map

Ways to use this method:
========================

  * graphIdeal(RingMap) -- the ideal of the
    graph of the regular map corresponding to a ring map

graphRing(RingMap) -- the coordinate ring of the graph of the regular map corresponding to a ring map
*****************************************************************************************************

Synopsis
========

  * Function: graphRing,
  * Usage:
        graphRing f
  * Inputs:
      * f
  * Optional inputs,:
      * MonomialOrder => ..., default value {GRevLex, Position => Up}, a
        monomial ordering, see monomial orderings,
      * MonomialSize => an integer, default value 32, the monomial
        size, see MonomialSize,
      * VariableBaseName => a symbol, default value "p", the
        variable base name, see VariableBaseName,
  * Outputs:
      * the coordinate ring of the graph of regular map corresponding to f

Description
===========

+----------------------------------------------+
|i1 : R = QQ[x,y]                              |
|                                              |
|o1 = R                                        |
|                                              |
|o1 : PolynomialRing                           |
+----------------------------------------------+
|i2 : S = QQ[s,t,u]                            |
|                                              |
|o2 = S                                        |
|                                              |
|o2 : PolynomialRing                           |
+----------------------------------------------+
|i3 : f = map(R,S,{x^2,x*y,y^2})               |
|                                              |
|                  2        2                  |
|o3 = map (R, S, {x , x*y, y })                |
|                                              |
|o3 : RingMap R <-- S                          |
+----------------------------------------------+
|i4 : graphRing f                              |
|                                              |
|                  QQ[p ..p ]                  |
|                      0   4                   |
|o4 = -----------------------------------      |
|         2                       2            |
|     (- p  + p , - p p  + p , - p  + p )      |
|         0    2     0 1    3     1    4       |
|                                              |
|o4 : QuotientRing                             |
+----------------------------------------------+
|i5 : Spec oo                                  |
|                                              |
|         /             QQ[p ..p ]            \|
|         |                 0   4             ||
|o5 = Spec|-----------------------------------||
|         |    2                       2      ||
|         |(- p  + p , - p p  + p , - p  + p )||
|         \    0    2     0 1    3     1    4 /|
|                                              |
|o5 : AffineVariety                            |
+----------------------------------------------+

See also
========

  * graphIdeal -- the ideal of the graph of the
    regular map corresponding to a ring map

Ways to use this method:
========================

  * graphRing(RingMap) -- the coordinate ring of
    the graph of the regular map corresponding to a ring map

modules
*******

For more operations in homological algebra, see chain complexes.
For additional common operations and a comprehensive list of all
routines in Macaulay2 which return or use modules, see Module.

construction of modules

homomorphisms (maps) between modules

graded modules

multilinear algebra

free modules
************

We use Ring ^ ZZ, to make a new free module.

+-----------------------+
|i1 : R = ZZ/101[x,y,z];|
+-----------------------+
|i2 : M = R^4           |
|                       |
|      4                |
|o2 = R                 |
|                       |
|o2 : R-module, free    |
+-----------------------+
Such modules are often made implicitly when constructing matrices.
+--------------------------------+
|i3 : m = matrix{{x,y,z},{y,z,0}}|
|                                |
|o3 = | x y z |                  |
|     | y z 0 |                  |
|                                |
|             2      3           |
|o3 : Matrix R  <-- R            |
+--------------------------------+
|i4 : target m == R^2            |
|                                |
|o4 = true                       |
+--------------------------------+

When a ring is graded, so are its free modules.  By default, the degrees of the
basis elements are taken to be 0.
+-------------------------+
|i5 : degrees M           |
|                         |
|o5 = {{0}, {0}, {0}, {0}}|
|                         |
|o5 : List                |
+-------------------------+
We can use Ring ^ List, to specify other degrees, or more
precisely, their additive inverses.
+-----------------------------------------------------------+
|i6 : F = R^{1,4:2,3,3:4}                                   |
|                                                           |
|      9                                                    |
|o6 = R                                                     |
|                                                           |
|o6 : R-module, free, degrees {-1, 4:-2, -3, 3:-4}          |
+-----------------------------------------------------------+
|i7 : degrees F                                             |
|                                                           |
|o7 = {{-1}, {-2}, {-2}, {-2}, {-2}, {-3}, {-4}, {-4}, {-4}}|
|                                                           |
|o7 : List                                                  |
+-----------------------------------------------------------+
Notice the use of _colon_, above to indicate repetition.

If the variables of the ring have multi-degrees represented by lists (vectors)
of integers, then the degrees of a free module must also be multi-degrees.
+------------------------------------------------------+
|i8 : S = ZZ[a,b,c, Degrees=>{{1,2},{2,0},{3,3}}]      |
|                                                      |
|o8 = S                                                |
|                                                      |
|o8 : PolynomialRing                                   |
+------------------------------------------------------+
|i9 : N = S ^ {{-1,-1},{-4,4},{0,0}}                   |
|                                                      |
|      3                                               |
|o9 = S                                                |
|                                                      |
|o9 : S-module, free, degrees {{1, 1}, {4, -4}, {0, 0}}|
+------------------------------------------------------+
|i10 : degree N_0                                      |
|                                                      |
|o10 = {1, 1}                                          |
|                                                      |
|o10 : List                                            |
+------------------------------------------------------+
|i11 : degree (a*b*N_1)                                |
|                                                      |
|o11 = {7, -2}                                         |
|                                                      |
|o11 : List                                            |
+------------------------------------------------------+

See also
========

  * graded modules

matrices to and from modules -- including kernel, cokernel and image
********************************************************************

matrices to modules (kernel, image, cokernel)
=============================================

Given a matrix, we may compute the kernel, image,
and cokernel.
+------------------------------------+
|i1 : R = QQ[a..f];                  |
+------------------------------------+
|i2 : F = matrix{{a,b,d,e},{b,c,e,f}}|
|                                    |
|o2 = | a b d e |                    |
|     | b c e f |                    |
|                                    |
|             2      4               |
|o2 : Matrix R  <-- R                |
+------------------------------------+
+----------------------------------------------+
|i3 : M = ker F                                |
|                                              |
|o3 = image {1} | cd-be  0      e2-df  ce-bf  ||
|           {1} | -bd+ae e2-df  0      -be+af ||
|           {1} | b2-ac  -ce+bf -be+af 0      ||
|           {1} | 0      cd-be  bd-ae  b2-ac  ||
|                                              |
|                             4                |
|o3 : R-module, submodule of R                 |
+----------------------------------------------+
|i4 : coker F                                  |
|                                              |
|o4 = cokernel | a b d e |                     |
|              | b c e f |                     |
|                                              |
|                            2                 |
|o4 : R-module, quotient of R                  |
+----------------------------------------------+
|i5 : image F                                  |
|                                              |
|o5 = image | a b d e |                        |
|           | b c e f |                        |
|                                              |
|                             2                |
|o5 : R-module, submodule of R                 |
+----------------------------------------------+
Some routines in Macaulay2 have abbreviations, for example ker may be used for
kernel, and coker may be used for cokernel. The image function has no
abbreviated form.

modules to matrices
===================

Each module has, at least implicitly, two matrices associated to it:
generators, (abbreviated form: gens), and relations.
If a module is a submodule of a free module, then the relations
matrix is zero.  If a module is a quotient of a free module, then the generator
matrix is the identity matrix.  If a module is a subquotient,
then both may be more general.
+----------------------------------------+
|i6 : generators M                       |
|                                        |
|o6 = {1} | cd-be  0      e2-df  ce-bf  ||
|     {1} | -bd+ae e2-df  0      -be+af ||
|     {1} | b2-ac  -ce+bf -be+af 0      ||
|     {1} | 0      cd-be  bd-ae  b2-ac  ||
|                                        |
|             4      4                   |
|o6 : Matrix R  <-- R                    |
+----------------------------------------+
|i7 : relations M                        |
|                                        |
|o7 = 0                                  |
|                                        |
|             4                          |
|o7 : Matrix R  <-- 0                    |
+----------------------------------------+

Every finitely generated module has a presentation matrix. In Macaulay2, if the
module is not a quotient of a free module, then a syzygy computation is
performed to find a presentation matrix.
+---------------------+
|i8 : presentation M  |
|                     |
|o8 = {3} | -f -e |   |
|     {3} | b  a  |   |
|     {3} | -c -b |   |
|     {3} | e  d  |   |
|                     |
|             4      2|
|o8 : Matrix R  <-- R |
+---------------------+

See also
========

  * cokernel(Matrix) -- cokernel of a map of modules, graded
    modules, or chaincomplexes
  * image(Matrix) -- image of a map
  * kernel(Matrix) -- kernel of a matrix
  * generators(Module) -- the generator matrix
    of a module
  * relations(Module) -- the defining relations
  * presentation(Module) -- presentation of a
    module

submodules and quotients
************************

submodules
==========

We can create submodules by using standard mathematical notation, keeping in
mind that the generators of a module M are denoted by M_0, M_1, etc.
+---------------------------+
|i1 : R = QQ[x,y,z];        |
+---------------------------+
|i2 : M = R^3               |
|                           |
|      3                    |
|o2 = R                     |
|                           |
|o2 : R-module, free        |
+---------------------------+
|i3 : I = ideal(x^2,y^2-x*z)|
|                           |
|             2   2         |
|o3 = ideal (x , y  - x*z)  |
|                           |
|o3 : Ideal of R            |
+---------------------------+
Here are some examples of submodules of M.
+-----------------------------------------+
|i4 : I*M                                 |
|                                         |
|o4 = image | x2 0  0  y2-xz 0     0     ||
|           | 0  x2 0  0     y2-xz 0     ||
|           | 0  0  x2 0     0     y2-xz ||
|                                         |
|                             3           |
|o4 : R-module, submodule of R            |
+-----------------------------------------+
|i5 : R*M_0                               |
|                                         |
|o5 = image | 1 |                         |
|           | 0 |                         |
|           | 0 |                         |
|                                         |
|                             3           |
|o5 : R-module, submodule of R            |
+-----------------------------------------+
|i6 : I*M_1                               |
|                                         |
|o6 = image | 0  0     |                  |
|           | x2 y2-xz |                  |
|           | 0  0     |                  |
|                                         |
|                             3           |
|o6 : R-module, submodule of R            |
+-----------------------------------------+
|i7 : J = I*M_1 + R*y^5*M_1 + R*M_2       |
|                                         |
|o7 = image | 0  0     0  0 |             |
|           | x2 y2-xz y5 0 |             |
|           | 0  0     0  1 |             |
|                                         |
|                             3           |
|o7 : R-module, submodule of R            |
+-----------------------------------------+
To determine if one submodule is contained in the other, use
isSubset(Module,Module).
+----------------------------+
|i8 : isSubset(I*M,M)        |
|                            |
|o8 = true                   |
+----------------------------+
|i9 : isSubset((x^3-x)*M,x*M)|
|                            |
|o9 = true                   |
+----------------------------+
Another way to construct submodules is to take the kernel or image of a matrix.
+-------------------------------+
|i10 : F = matrix{{x,y,z}}      |
|                               |
|o10 = | x y z |                |
|                               |
|              1      3         |
|o10 : Matrix R  <-- R          |
+-------------------------------+
|i11 : image F                  |
|                               |
|o11 = image | x y z |          |
|                               |
|                              1|
|o11 : R-module, submodule of R |
+-------------------------------+
|i12 : kernel F                 |
|                               |
|o12 = image {1} | -y 0  -z |   |
|            {1} | x  -z 0  |   |
|            {1} | 0  y  x  |   |
|                               |
|                              3|
|o12 : R-module, submodule of R |
+-------------------------------+
The module M does not need to be a free module.  We will see examples below.

quotients
=========

If N is a submodule of M, construct the quotient using Module / Module.
+--------------------------------+
|i13 : F = R^3                   |
|                                |
|       3                        |
|o13 = R                         |
|                                |
|o13 : R-module, free            |
+--------------------------------+
|i14 : F/(x*F+y*F+R*F_2)         |
|                                |
|o14 = cokernel | x 0 0 y 0 0 0 ||
|               | 0 x 0 0 y 0 0 ||
|               | 0 0 x 0 0 y 1 ||
|                                |
|                             3  |
|o14 : R-module, quotient of R   |
+--------------------------------+
When constructing M/N, it is not necessary that M be a free module, or a
quotient of a free module.  In this case, we obtain a subquotient module, which
we describe below.

subquotient modules -- the way Macaulay2 represents modules
***********************************************************

Not all modules arise naturally as submodules or quotients of free modules.  As
an example, consider the module $M = I/I^2$ in the example below.
+------------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                               |
+------------------------------------------------------------------+
|i2 : I = ideal(x*y,x*z,y*z)                                       |
|                                                                  |
|o2 = ideal (x*y, x*z, y*z)                                        |
|                                                                  |
|o2 : Ideal of R                                                   |
+------------------------------------------------------------------+
|i3 : M = I/I^2                                                    |
|                                                                  |
|o3 = subquotient (| xy xz yz |, | x2y2 x2yz xy2z x2z2 xyz2 y2z2 |)|
|                                                                  |
|                               1                                  |
|o3 : R-module, subquotient of R                                   |
+------------------------------------------------------------------+
Macaulay2 represents each module (at least conceptually) as a subquotient
module, that is, a submodule of a quotient of an ambient free module.  A
subquotient module is determined by two matrices $f : R^m \rightarrow{} R^n$
and $g : R^p \rightarrow{} R^n$. The subquotient module with generators $f$ and
relations $g$ is by definition the module $M = ((image f) + (image g))/(image
g)$.

If $f$ is the identity map, $M = coker g$, and if $g = 0$, then $M = image f$.
The class of subquotient modules is the smallest class containing free modules,
which is closed under taking submodules and quotients.

One may create a subquotient module directly from matrices f and g having the
same target free module.
+-------------------------------------------+
|i4 : f = matrix{{x,y}}                     |
|                                           |
|o4 = | x y |                               |
|                                           |
|             1      2                      |
|o4 : Matrix R  <-- R                       |
+-------------------------------------------+
|i5 : g = matrix{{x^2,x*y,y^2,z^4}}         |
|                                           |
|o5 = | x2 xy y2 z4 |                       |
|                                           |
|             1      4                      |
|o5 : Matrix R  <-- R                       |
+-------------------------------------------+
|i6 : M = subquotient(f,g)                  |
|                                           |
|o6 = subquotient (| x y |, | x2 xy y2 z4 |)|
|                                           |
|                               1           |
|o6 : R-module, subquotient of R            |
+-------------------------------------------+
The same module can be constructed in the following manner.
+-------------------------------------------------------+
|i7 : N = (image f)/(image g)                           |
|                                                       |
|o7 = subquotient (| x y |, | x2 xy y2 z4 |)            |
|                                                       |
|                               1                       |
|o7 : R-module, subquotient of R                        |
+-------------------------------------------------------+
|i8 : N1 = (image f + image g)/(image g)                |
|                                                       |
|o8 = subquotient (| x y x2 xy y2 z4 |, | x2 xy y2 z4 |)|
|                                                       |
|                               1                       |
|o8 : R-module, subquotient of R                        |
+-------------------------------------------------------+
|i9 : M === N                                           |
|                                                       |
|o9 = true                                              |
+-------------------------------------------------------+
Notice that Macaulay2 allows one to write (image f)/(image g), even though
mathematically this really means: (image f + image g)/(image g).  There is an
important difference however.  Modules in Macaulay2 always come with an ordered
set of generators, and N1 has 4 more generators (all zero in the module!) than
N.  The modules M and N though are identical.

The two matrices f and g mentioned above are recovered using the routines
generators(Module), and relations(Module).
+----------------------+
|i10 : generators M    |
|                      |
|o10 = | x y |         |
|                      |
|              1      2|
|o10 : Matrix R  <-- R |
+----------------------+
|i11 : relations M     |
|                      |
|o11 = | x2 xy y2 z4 | |
|                      |
|              1      4|
|o11 : Matrix R  <-- R |
+----------------------+

Submodules and quotients of free modules work as one would imagine.
+----------------------------------------------------------------------+
|i12 : N2 = R*M_0 + I*M                                                |
|                                                                      |
|o12 = subquotient (| x x2y xy2 x2z xyz xyz y2z |, | x2 xy y2 z4 |)    |
|                                                                      |
|                                1                                     |
|o12 : R-module, subquotient of R                                      |
+----------------------------------------------------------------------+
|i13 : M/N2                                                            |
|                                                                      |
|o13 = subquotient (| x y |, | x x2y xy2 x2z xyz xyz y2z x2 xy y2 z4 |)|
|                                                                      |
|                                1                                     |
|o13 : R-module, subquotient of R                                      |
+----------------------------------------------------------------------+
|i14 : prune(M/N2)                                                     |
|                                                                      |
|o14 = cokernel {1} | y x z4 |                                         |
|                                                                      |
|                             1                                        |
|o14 : R-module, quotient of R                                         |
+----------------------------------------------------------------------+

Given a subquotient module M, there are several useful modules associated to
M.The free module of which M is a subquotient is obtained using
ambient(Module).
+--------------------+
|i15 : ambient M     |
|                    |
|       1            |
|o15 = R             |
|                    |
|o15 : R-module, free|
+--------------------+
This is the same as the common target of the matrices of generators and
relations.
+---------------------------------------+
|i16 : ambient M === target relations M |
|                                       |
|o16 = true                             |
+---------------------------------------+
|i17 : ambient M === target generators M|
|                                       |
|o17 = true                             |
+---------------------------------------+
M is a submodule of the module R^n/(image g).  The routine super(Module),
returns this quotient module.
+------------------------------+
|i18 : super M                 |
|                              |
|o18 = cokernel | x2 xy y2 z4 ||
|                              |
|                             1|
|o18 : R-module, quotient of R |
+------------------------------+
This may be obtained directly as the cokernel of the matrix of relations.
+--------------------------------------+
|i19 : super M === cokernel relations M|
|                                      |
|o19 = true                            |
+--------------------------------------+
Often the given representation of a module is not very efficient. Use
trim(Module), to keep the module as a subquotient of the same ambient
free module, but change the generators and relations to be minimal, or in the
nonlocal or non-graded case, at least more efficient.
+------------------------------------------------+
|i20 : M + M                                     |
|                                                |
|o20 = subquotient (| x y x y |, | x2 xy y2 z4 |)|
|                                                |
|                                1               |
|o20 : R-module, subquotient of R                |
+------------------------------------------------+
|i21 : trim (M+M)                                |
|                                                |
|o21 = subquotient (| y x |, | y2 xy x2 z4 |)    |
|                                                |
|                                1               |
|o21 : R-module, subquotient of R                |
+------------------------------------------------+
Use minimalPresentation(Module), to also
allow the ambient free module to be improved.  This currently returns a
quotient of a free module, but in the future it might not.
+------------------------------------+
|i22 : minimalPresentation M         |
|                                    |
|o22 = cokernel {1} | y x 0 0 z4 0  ||
|               {1} | 0 0 y x 0  z4 ||
|                                    |
|                             2      |
|o22 : R-module, quotient of R       |
+------------------------------------+
prune is a synonym for minimalPresentation.
+------------------------------------+
|i23 : prune M                       |
|                                    |
|o23 = cokernel {1} | y x 0 0 z4 0  ||
|               {1} | 0 0 y x 0  z4 ||
|                                    |
|                             2      |
|o23 : R-module, quotient of R       |
+------------------------------------+
For maps between modules, including between subquotient modules, see
homomorphisms (maps) between modules.

See also
========

  * ambient(Module) -- ambient free module
  * super(Module) -- get the ambient module
  * generators(Module) -- the generator matrix
    of a module
  * relations(Module) -- the defining relations
  * subquotient -- make a subquotient module
  * trim(Module) -- minimize generators and relations
  * minimalPresentation(Module), --
    minimal presentation of a module

module homomorphisms
********************

A homomorphism f : M --> N is represented as a matrix from the generators of M
to the generators of N.
+------------------------------+
|i1 : R = QQ[x,y]/(y^2-x^3);   |
+------------------------------+
|i2 : M = module ideal(x,y)    |
|                              |
|o2 = image | x y |            |
|                              |
|                             1|
|o2 : R-module, submodule of R |
+------------------------------+
One homomorphism F : M --> R is x |--> y, y |--> x^2 (this is multiplication by
the fraction y/x). We write this in the following way.
+-----------------------------------+
|i3 : F = map(R^1,M,matrix{{y,x^2}})|
|                                   |
|o3 = | y x2 |                      |
|                                   |
|             1                     |
|o3 : Matrix R  <-- M               |
+-----------------------------------+
Notice that as is usual in Macaulay2, the target comes before the source.

Macaulay2 doesn't display the source and target, unless they are both free
modules or have been assigned to global variables.  Use target,
and source, to get them.  The matrix, routine
recovers the matrix of free modules between the generators of the source and
target.
+------------------------------+
|i4 : source F                 |
|                              |
|o4 = image | x y |            |
|                              |
|                             1|
|o4 : R-module, submodule of R |
+------------------------------+
|i5 : target F == R^1          |
|                              |
|o5 = true                     |
+------------------------------+
|i6 : matrix F                 |
|                              |
|o6 = | y x2 |                 |
|                              |
|             1      2         |
|o6 : Matrix R  <-- R          |
+------------------------------+
Macaulay2 also does not check that the homomorphism is well defined (i.e. the
relations of the source map into the relations of the target). Use
isWellDefined, to check.  This generally requires a Gröbner
basis computation (which is performed automatically, if it is required and has
not already been done).
+--------------------+
|i7 : isWellDefined F|
|                    |
|o7 = true           |
+--------------------+
|i8 : isIsomorphism F|
|                    |
|o8 = false          |
+--------------------+
The image of F lies in the submodule M of R^1.  Suppose we wish to define this
new map G : M --> M.  How does one do this?

To obtain the map M --> M, we use Matrix // Matrix. In
order to do this, we need the inclusion map of M into R^1.
+-----------------------------+
|i9 : inc = inducedMap(R^1, M)|
|                             |
|o9 = | x y |                 |
|                             |
|             1               |
|o9 : Matrix R  <-- M         |
+-----------------------------+
Now we use // to lift F : M --> R^1 along inc : M --> R^1, to obtain a map G :
M --> M, such that inc * G == F.
+-------------------------------------+
|i10 : G = F // inc                   |
|                                     |
|o10 = {1} | 0 x |                    |
|      {1} | 1 0 |                    |
|                                     |
|o10 : Matrix M <-- M                 |
+-------------------------------------+
|i11 : target G == M and source G == M|
|                                     |
|o11 = true                           |
+-------------------------------------+
|i12 : inc * G == F                   |
|                                     |
|o12 = true                           |
+-------------------------------------+
Let's make sure that this map G is well defined.
+------------------------------+
|i13 : isWellDefined G         |
|                              |
|o13 = true                    |
+------------------------------+
|i14 : isIsomorphism G         |
|                              |
|o14 = false                   |
+------------------------------+
|i15 : prune coker G           |
|                              |
|o15 = cokernel | y x |        |
|                              |
|                             1|
|o15 : R-module, quotient of R |
+------------------------------+
|i16 : kernel G == 0           |
|                              |
|o16 = true                    |
+------------------------------+

See also
========

  * isWellDefined(Matrix) -- whether a map is well
    defined
  * isIsomorphism(Matrix) -- whether a map is an
    isomorphism
  * isInjective(Matrix) -- whether a map is injective
  * isSurjective(Matrix) -- whether a map is surjective
  * kernel(Matrix) -- kernel of a matrix
  * cokernel(Matrix) -- cokernel of a map of modules, graded
    modules, or chaincomplexes
  * Matrix // Matrix -- factor a map through another

right modules or left modules?
******************************

Macaulay2 can handle non-commutative rings, and for such rings there is a
difference between left modules and right modules. In Macaulay2, all the
modules are left modules, but matrices act on the left, too.  The usual
convention would be to have the matrices act on the right, so the homomorphism
rule (f(av)=af(v)) becomes a consequence of associativity of
matrix-vector-scalar multiplication ((av)f=a(vf)).  Macaulay2 makes things come
out okay in the end -- a left R-module can be regarded naturally as a right
R'-module, where R' is the opposite ring of R, obtained from the ring R by
reversing the multiplication.  Thus matrices over R' can act on R-modules from
the left.  Matrices over R in Macaulay2 are really matrices over R'.

We illustrate this state of affairs with an example over a (noncommutative)
Weyl algebra.  First observe the noncommutativity.
+-----------------------------------------------+
|i1 : R = QQ[x,dx,WeylAlgebra=>{x=>dx}]         |
|                                               |
|o1 = R                                         |
|                                               |
|o1 : PolynomialRing, 1 differential variable(s)|
+-----------------------------------------------+
|i2 : x*dx                                      |
|                                               |
|o2 = x*dx                                      |
|                                               |
|o2 : R                                         |
+-----------------------------------------------+
|i3 : dx*x                                      |
|                                               |
|o3 = x*dx + 1                                  |
|                                               |
|o3 : R                                         |
+-----------------------------------------------+
Now verify the module is a left module by checking associativity.
+-------------------------+
|i4 : M = R^2             |
|                         |
|      2                  |
|o4 = R                   |
|                         |
|o4 : R-module, free      |
+-------------------------+
|i5 : v = M_0             |
|                         |
|o5 = | 1 |               |
|     | 0 |               |
|                         |
|      2                  |
|o5 : R                   |
+-------------------------+
|i6 : dx*v                |
|                         |
|o6 = | dx |              |
|     |  0 |              |
|                         |
|      2                  |
|o6 : R                   |
+-------------------------+
|i7 : x*(dx*v)            |
|                         |
|o7 = | xdx |             |
|     |  0  |             |
|                         |
|      2                  |
|o7 : R                   |
+-------------------------+
|i8 : (x*dx)*v            |
|                         |
|o8 = | xdx |             |
|     |  0  |             |
|                         |
|      2                  |
|o8 : R                   |
+-------------------------+
|i9 : x*(dx*v) == (x*dx)*v|
|                         |
|o9 = true                |
+-------------------------+
Now make a matrix and check that left multiplication by it is a homomorphism
from M to M.
+------------------------+
|i10 : f = dx * id_M     |
|                        |
|o10 = | dx 0  |         |
|      | 0  dx |         |
|                        |
|              2      2  |
|o10 : Matrix R  <-- R   |
+------------------------+
|i11 : f*(x*v)           |
|                        |
|o11 = | xdx |           |
|      |  0  |           |
|                        |
|       2                |
|o11 : R                 |
+------------------------+
|i12 : x*(f*v)           |
|                        |
|o12 = | xdx |           |
|      |  0  |           |
|                        |
|       2                |
|o12 : R                 |
+------------------------+
|i13 : f*(x*v) == x*(f*v)|
|                        |
|o13 = true              |
+------------------------+
Now we make another matrix and check that matrix multiplication treats the
entries of the matrices as residing in the opposite ring, R'.
+---------------------------------------------+
|i14 : g = x * id_M                           |
|                                             |
|o14 = | x 0 |                                |
|      | 0 x |                                |
|                                             |
|              2      2                       |
|o14 : Matrix R  <-- R                        |
+---------------------------------------------+
|i15 : f*g                                    |
|                                             |
|o15 = | xdx 0   |                            |
|      | 0   xdx |                            |
|                                             |
|              2      2                       |
|o15 : Matrix R  <-- R                        |
+---------------------------------------------+
|i16 : f*g == (x*dx) * id_M                   |
|                                             |
|o16 = true                                   |
+---------------------------------------------+
|i17 : (dx * id_M)*(x * id_M) == (x*dx) * id_M|
|                                             |
|o17 = true                                   |
+---------------------------------------------+
Here we check that multiplication of a scalar times a matrix is compatible with
multiplication of a scalar times a vector.
+------------------------------------------------------------------+
|i18 : x * ( (dx * id_M) * v )                                     |
|                                                                  |
|o18 = | xdx |                                                     |
|      |  0  |                                                     |
|                                                                  |
|       2                                                          |
|o18 : R                                                           |
+------------------------------------------------------------------+
|i19 : (x *  (dx * id_M) ) * v                                     |
|                                                                  |
|o19 = | xdx |                                                     |
|      |  0  |                                                     |
|                                                                  |
|       2                                                          |
|o19 : R                                                           |
+------------------------------------------------------------------+
|i20 : (x *  (dx * id_M) ) * v == x * ( (dx * id_M) * v )          |
|                                                                  |
|o20 = true                                                        |
+------------------------------------------------------------------+
One desirable associativity rule does not hold, the one for RingElement *
Matrix * Matrix, as we see in this example.
+----------------------------------------------------------------+
|i21 : x * ( id_M * ( dx * id_M ) )                              |
|                                                                |
|o21 = | xdx 0   |                                               |
|      | 0   xdx |                                               |
|                                                                |
|              2      2                                          |
|o21 : Matrix R  <-- R                                           |
+----------------------------------------------------------------+
|i22 : (x * id_M) * ( dx * id_M )                                |
|                                                                |
|o22 = | xdx+1 0     |                                           |
|      | 0     xdx+1 |                                           |
|                                                                |
|              2      2                                          |
|o22 : Matrix R  <-- R                                           |
+----------------------------------------------------------------+
|i23 : x * ( id_M * ( dx * id_M ) ) == (x * id_M) * ( dx * id_M )|
|                                                                |
|o23 = false                                                     |
+----------------------------------------------------------------+
The reason for this discrepancy is that, as explained above, matrix
multiplication is done over R', not over R.

Currently, tensor product of a module M by a ring R works on either side and
does the same thing.  In other words, you can write R**M or M**R.  That may
change in the future.

Hilbert functions and free resolutions -- including degree and betti numbers
****************************************************************************

In this section, we give examples of common operations involving modules.
Throughout this section, we suppose that the base ring R is graded, with each
variable having degree one, and that  M is a graded R-module.  If the ring is
not graded, or is multi-graded, or if M is not graded, some of these functions
still work, but care must be taken in interpreting the output.  Here, we just
consider the standard grading case.

checking homogeneity
====================

Let's start by making a module over a ring with 18 variables
+-------------------------------------+
|i1 : R = ZZ/32003[vars(0..17)];      |
+-------------------------------------+
|i2 : M = coker genericMatrix(R,a,3,6)|
|                                     |
|o2 = cokernel | a d g j m p |        |
|              | b e h k n q |        |
|              | c f i l o r |        |
|                                     |
|                            3        |
|o2 : R-module, quotient of R         |
+-------------------------------------+
Use isHomogeneous, to check whether a given module is
graded.
+--------------------+
|i3 : isHomogeneous M|
|                    |
|o3 = true           |
+--------------------+

codimension, degree, and sectional arithmetic genera
====================================================

Use codim(Module), degree(Module),
and genera(Module) (Varieties),
for some basic numeric information about
a module.
+------------------------------------------------------+
|i4 : codim M                                          |
|                                                      |
|o4 = 4                                                |
+------------------------------------------------------+
|i5 : degree M                                         |
|                                                      |
|o5 = 15                                               |
+------------------------------------------------------+
|i6 : genera M                                         |
|                                                      |
|o6 = {-2, 2, -2, 2, -2, 2, -2, 2, -2, 2, -2, 2, 4, 14}|
|                                                      |
|o6 : List                                             |
+------------------------------------------------------+
The last number in the list of genera is the degree minus one.  The second to
last number is the genus of the generic linear section curve, ..., and the
first number is the arithmetic genus.

the Hilbert series
==================

The Hilbert series (see hilbertSeries(Module)) of
M is by definition the formal power series H(t) = sum(d in ZZ) dim(M_d) t^d.
This is a rational function with denominator (1-t)^n, where n is the number of
variables in the polynomial ring.  The numerator of this rational function is
called the poincare polynomial, and is obtained by the poincare(Module),
function.
+-------------------------------+
|i7 : poincare M                |
|                               |
|                 4      5     6|
|o7 = 3 - 6T + 15T  - 18T  + 6T |
|                               |
|o7 : ZZ[T]                     |
+-------------------------------+
|i8 : hf = hilbertSeries M      |
|                               |
|                 4      5     6|
|     3 - 6T + 15T  - 18T  + 6T |
|o8 = --------------------------|
|                     18        |
|              (1 - T)          |
|                               |
|o8 : Expression of class Divide|
+-------------------------------+

It is often useful to divide the poincare polynomial by (1-t) as many times as
possible.  This can be done by using reduceHilbert,:
+-------------------------------+
|i9 : reduceHilbert hf          |
|                               |
|                2              |
|     3 + 6T + 6T               |
|o9 = ------------              |
|              14               |
|       (1 - T)                 |
|                               |
|o9 : Expression of class Divide|
+-------------------------------+
+-------------------------------------------------+
|i10 : poincare' = (M) -> (                       |
|        H := poincare M;                         |
|        t := (ring H)_0;  -- The variable t above|
|        while H % (1-t) == 0 do H = H // (1-t);  |
|        H);                                      |
+-------------------------------------------------+
|i11 : poincare' M                                |
|                                                 |
|                 2                               |
|o11 = 3 + 6T + 6T                                |
|                                                 |
|o11 : ZZ[T]                                      |
+-------------------------------------------------+

free resolutions
================

The minimal free resolution C is computed using resolution(Module).
The specific matrices are obtained by indexing C.dd.
+-------------------------------------------------------------------+
|i12 : C = resolution M                                             |
|                                                                   |
|       3      6      15      18      6                             |
|o12 = R  <-- R  <-- R   <-- R   <-- R  <-- 0                       |
|                                                                   |
|      0      1      2       3       4      5                       |
|                                                                   |
|o12 : ChainComplex                                                 |
+-------------------------------------------------------------------+
|i13 : C.dd_3                                                       |
|                                                                   |
|o13 = {4} | m  -n o  p  -q r  0  0  0  0  0  0  0  0  0  0  0  0  ||
|      {4} | -j k  -l 0  0  0  p  0  0  0  -q r  0  0  0  0  0  0  ||
|      {4} | g  -h i  0  0  0  0  p  0  0  0  0  -q 0  0  r  0  0  ||
|      {4} | -d e  -f 0  0  0  0  0  p  0  0  0  0  -q 0  0  r  0  ||
|      {4} | a  -b c  0  0  0  0  0  0  p  0  0  0  0  -q 0  0  r  ||
|      {4} | 0  0  0  -j k  -l -m 0  0  0  n  -o 0  0  0  0  0  0  ||
|      {4} | 0  0  0  g  -h i  0  -m 0  0  0  0  n  0  0  -o 0  0  ||
|      {4} | 0  0  0  -d e  -f 0  0  -m 0  0  0  0  n  0  0  -o 0  ||
|      {4} | 0  0  0  a  -b c  0  0  0  -m 0  0  0  0  n  0  0  -o ||
|      {4} | 0  0  0  0  0  0  g  j  0  0  -h i  -k 0  0  l  0  0  ||
|      {4} | 0  0  0  0  0  0  -d 0  j  0  e  -f 0  -k 0  0  l  0  ||
|      {4} | 0  0  0  0  0  0  a  0  0  j  -b c  0  0  -k 0  0  l  ||
|      {4} | 0  0  0  0  0  0  0  -d -g 0  0  0  e  h  0  -f -i 0  ||
|      {4} | 0  0  0  0  0  0  0  a  0  -g 0  0  -b 0  h  c  0  -i ||
|      {4} | 0  0  0  0  0  0  0  0  a  d  0  0  0  -b -e 0  c  f  ||
|                                                                   |
|              15      18                                           |
|o13 : Matrix R   <-- R                                             |
+-------------------------------------------------------------------+
For more information about chain complexes and resolutions, see chain complexes,
and computing resolutions.

betti numbers
=============

Use betti, to display the graded betti numbers of M.
+------------------------+
|i14 : betti C           |
|                        |
|             0 1  2  3 4|
|o14 = total: 3 6 15 18 6|
|          0: 3 6  .  . .|
|          1: . .  .  . .|
|          2: . . 15 18 6|
|                        |
|o14 : BettiTally        |
+------------------------+
This table should be interpreted as follows: the number in the i-th row and
j-th column (indices starting at 0), is the number of j-th syzygies in degree
i+j. In the above example, there are 15 second syzygies of degree 4, and the
entries of the maps CC.d_1, CC.d_3, CC.d_4 are all linear.

isHomogeneous -- whether something is homogeneous (graded)
**********************************************************

Synopsis
========

  * Usage:
        isHomogeneous x
  * Inputs:
      * x, a Ring, RingElement, Vector,
        see Matrix, Ideal, Module,
        see RingMap, ChainComplex, or
        ChainComplexMap,
  * Outputs:
      * a Boolean value, whether x is homogeneous.

Description
===========

+---------------------------------------------+
|i1 : isHomogeneous(ZZ)                       |
|                                             |
|o1 = true                                    |
+---------------------------------------------+
|i2 : isHomogeneous(ZZ[x,y])                  |
|                                             |
|o2 = true                                    |
+---------------------------------------------+
|i3 : isHomogeneous(ZZ[x,y]/(x^3-x^2*y+3*y^3))|
|                                             |
|o3 = true                                    |
+---------------------------------------------+
|i4 : isHomogeneous(ZZ[x,y]/(x^3-y-3))        |
|                                             |
|o4 = false                                   |
+---------------------------------------------+

Quotients of multigraded rings are homogeneous, if the ideal is homogeneous.
+------------------------------------------------+
|i5 : R = QQ[a,b,c,Degrees=>{{1,1},{1,0},{0,1}}];|
+------------------------------------------------+
|i6 : I = ideal(a-b*c);                          |
|                                                |
|o6 : Ideal of R                                 |
+------------------------------------------------+
|i7 : isHomogeneous I                            |
|                                                |
|o7 = true                                       |
+------------------------------------------------+
|i8 : isHomogeneous(R/I)                         |
|                                                |
|o8 = true                                       |
+------------------------------------------------+
|i9 : isHomogeneous(R/(a-b))                     |
|                                                |
|o9 = false                                      |
+------------------------------------------------+

Polynomial rings over polynomial rings are multigraded.
+---------------------+
|i10 : A = QQ[a]      |
|                     |
|o10 = A              |
|                     |
|o10 : PolynomialRing |
+---------------------+
|i11 : B = A[x]       |
|                     |
|o11 = B              |
|                     |
|o11 : PolynomialRing |
+---------------------+
|i12 : degree x       |
|                     |
|o12 = {1, 0}         |
|                     |
|o12 : List           |
+---------------------+
|i13 : degree a_B     |
|                     |
|o13 = {0, 1}         |
|                     |
|o13 : List           |
+---------------------+
|i14 : isHomogeneous B|
|                     |
|o14 = true           |
+---------------------+

A matrix is homogeneous if each entry is homogeneous of such a degree that the
matrix has a well-defined degree.
+--------------------------------------+
|i15 : S = QQ[a,b];                    |
+--------------------------------------+
|i16 : F = S^{-1,2}                    |
|                                      |
|       2                              |
|o16 = S                               |
|                                      |
|o16 : S-module, free, degrees {1, -2} |
+--------------------------------------+
|i17 : isHomogeneous F                 |
|                                      |
|o17 = true                            |
+--------------------------------------+
|i18 : G = S^{1,2}                     |
|                                      |
|       2                              |
|o18 = S                               |
|                                      |
|o18 : S-module, free, degrees {-1, -2}|
+--------------------------------------+
|i19 : phi = random(G,F)               |
|                                      |
|o19 = {-1} | 8a2+ab+3b2        0 |    |
|      {-2} | 7a3+8a2b+3ab2+3b3 7 |    |
|                                      |
|              2      2                |
|o19 : Matrix S  <-- S                 |
+--------------------------------------+
|i20 : isHomogeneous phi               |
|                                      |
|o20 = true                            |
+--------------------------------------+
|i21 : degree phi                      |
|                                      |
|o21 = {0}                             |
|                                      |
|o21 : List                            |
+--------------------------------------+

Modules are homogeneous if their generator and relation matrices are
homogeneous.
+-------------------------------------------+
|i22 : M = coker phi                        |
|                                           |
|o22 = cokernel {-1} | 8a2+ab+3b2        0 ||
|               {-2} | 7a3+8a2b+3ab2+3b3 7 ||
|                                           |
|                             2             |
|o22 : S-module, quotient of S              |
+-------------------------------------------+
|i23 : isHomogeneous(a*M)                   |
|                                           |
|o23 = true                                 |
+-------------------------------------------+
|i24 : isHomogeneous((a+1)*M)               |
|                                           |
|o24 = false                                |
+-------------------------------------------+

Note that no implicit simplification is done. Consider the following cautionary
example.
+-------------------------------------+
|i25 : R = QQ[x]                      |
|                                     |
|o25 = R                              |
|                                     |
|o25 : PolynomialRing                 |
+-------------------------------------+
|i26 : isHomogeneous ideal(x+x^2, x^2)|
|                                     |
|o26 = false                          |
+-------------------------------------+

Caveat
======

No computation on the generators and relations is performed. For example, if
inhomogeneous generators of a homogeneous ideal are given, then the return
value is false.

See also
========

  * degree
  * degrees -- degrees of generators
  * homogenize -- homogenize with respect to a variable
  * graded and multigraded polynomial rings
  * graded modules
  * prune -- prune, e.g., compute a minimal presentation

Ways to use isHomogeneous:
==========================

  * "isHomogeneous(ChainComplex)"
  * "isHomogeneous(ChainComplexMap)"
  * "isHomogeneous(Ideal)"
  * "isHomogeneous(Matrix)"
  * "isHomogeneous(Module)"
  * "isHomogeneous(Ring)"
  * "isHomogeneous(RingElement)"
  * "isHomogeneous(RingMap)"
  * "isHomogeneous(Vector)"
  * isHomogeneous(Number) (missing documentation)
  * isHomogeneous(PolynomialRing) (missing documentation)
  * isHomogeneous(QuotientRing) (missing documentation)

For the programmer
==================

The object isHomogeneous, is a method function.

codim(Module) -- codimension of the support of a module
*******************************************************

Synopsis
========

  * Function: codim,
  * Usage:
        codim M
  * Inputs:
      * M, a module over a ring R
  * Optional inputs,:
      * Generic, => ..., default
        value false,
  * Outputs:
      * an integer,

Description
===========

Computes the codimension of the support of the module as given by dim(R) -
dim(M).
+----------------------------------+
|i1 : R = ZZ/101[a..d];            |
+----------------------------------+
|i2 : M = coker matrix{{a,b},{c,d}}|
|                                  |
|o2 = cokernel | a b |             |
|              | c d |             |
|                                  |
|                            2     |
|o2 : R-module, quotient of R      |
+----------------------------------+
|i3 : codim M                      |
|                                  |
|o3 = 1                            |
+----------------------------------+

The returned value is the usual codimension if R is an integral domain or, more
generally, equidimensional.

See also
========

  * dim(Module) -- compute the Krull dimension

Ways to use this method:
========================

  * codim(Module) -- codimension of the support of a
    module

degree(Module)
**************

Synopsis
========

  * Function: degree,
  * Usage:
        degree M
  * Inputs:
      * M, over a polynomial ring or quotient of a polynomial ring, over a
        field k
  * Outputs:
      * an integer, the degree of M

Description
===========

We assume that M is a graded (homogeneous) module over a polynomial ring or a
quotient of a polynomial ring with all degrees of variables and heft vector
equal to {1}, over a field k.

If M is finite dimensional over k, the degree of M is its dimension over k.
Otherwise, the degree of M is the multiplicity of M, i.e., the integer d such
that the Hilbert polynomial of M has the form z |--> d z^e/e! + lower terms in
z.

+---------------------------------------------+
|i1 : R = ZZ/101[t,x,y,z];                    |
+---------------------------------------------+
|i2 : degree (R^1 / (ideal vars R)^6)         |
|                                             |
|o2 = 126                                     |
+---------------------------------------------+
|i3 : degree minors_2 matrix {{t,x,y},{x,y,z}}|
|                                             |
|o3 = 3                                       |
+---------------------------------------------+

The algorithm computes the poincare, polynomial of M, divides
it by 1-T as often as possible, then evaluates it at T=1. When the module has
finite length, the result is the Hilbert series evaluated at 1, that is the
dimension over the ground field, which for a graded (homogeneous) is the same
as the length.

Caveat
======

If the base ring is ZZ, or the module is not homogeneous, it is
likely that the answer is not what you would expect.  Similarly, if the degrees
of the variables are not all {1}, or the heft vector isn't {1}, then the answer
is harder to interpret.  See heft vectors, and
multidegree.

See also
========

  * hilbertPolynomial -- compute the Hilbert
    polynomial
  * isHomogeneous -- whether something is homogeneous
    (graded)

Ways to use this method:
========================

  * degree(Module)

hilbertSeries(Module) -- compute the Hilbert series of the module
*****************************************************************

Synopsis
========

  * Function: hilbertSeries,
  * Usage:
        hilbertSeries M
  * Inputs:
      * M
  * Optional inputs,:
      * Order, => ...,
        default value infinity, display the truncated power series expansion
      * Reduce, => ...,
        default value false, reduce the Hilbert series
  * Outputs:
      * a divide expression, the Hilbert series

Description
===========

We compute the Hilbert series, of a module.
+-----------------------------------+
|i1 : R = ZZ/101[x, Degrees => {2}];|
+-----------------------------------+
|i2 : M = module ideal x^2          |
|                                   |
|o2 = image | x2 |                  |
|                                   |
|                             1     |
|o2 : R-module, submodule of R      |
+-----------------------------------+
|i3 : s = hilbertSeries M           |
|                                   |
|         4                         |
|        T                          |
|o3 = --------                      |
|           2                       |
|     (1 - T )                      |
|                                   |
|o3 : Expression of class Divide    |
+-----------------------------------+
|i4 : numerator s                   |
|                                   |
|      4                            |
|o4 = T                             |
|                                   |
|o4 : ZZ[T]                         |
+-----------------------------------+
|i5 : poincare M                    |
|                                   |
|      4                            |
|o5 = T                             |
|                                   |
|o5 : ZZ[T]                         |
+-----------------------------------+
Recall that the variables of the power series are the variables of the
degrees ring.
+-------------------------------------+
|i6 : R=ZZ/101[x, Degrees => {{1,1}}];|
+-------------------------------------+
|i7 : M = module ideal x^2;           |
+-------------------------------------+
|i8 : s = hilbertSeries M             |
|                                     |
|         2 2                         |
|        T T                          |
|         0 1                         |
|o8 = ----------                      |
|     (1 - T T )                      |
|           0 1                       |
|                                     |
|o8 : Expression of class Divide      |
+-------------------------------------+
|i9 : numerator s                     |
|                                     |
|      2 2                            |
|o9 = T T                             |
|      0 1                            |
|                                     |
|o9 : ZZ[T ..T ]                      |
|         0   1                       |
+-------------------------------------+
|i10 : poincare M                     |
|                                     |
|       2 2                           |
|o10 = T T                            |
|       0 1                           |
|                                     |
|o10 : ZZ[T ..T ]                     |
|          0   1                      |
+-------------------------------------+

Ways to use this method:
========================

  * hilbertSeries(Module) -- compute the
    Hilbert series of the module

poincare -- assemble degrees of a ring, module, or ideal into a polynomial
**************************************************************************

Synopsis
========

  * Usage:
        poincare M
  * Inputs:
      * M, a ring, a module, or an ideal,
  * Outputs:
      * a ring element, in the degrees ring,
        of the ambient ring, which is a Laurent polynomial ring
        whose monomial T_0^(d_0) ... T_(r-1)^(d_(r-1)) correspond to the degree
        {d_0,...,d_(n-1)}

Description
===========

This function computes the numerator of the reduced Hilbert series,
of a graded ring, or a graded module or ideal over a graded
ring, which encodes information about the twists in the minimal free resolution
of the object.

+-----------------------------------------------+
|i1 : S = ZZ/101[w..z];                         |
+-----------------------------------------------+
|i2 : M = module monomialCurveIdeal(S, {1,3,4});|
+-----------------------------------------------+
|i3 : betti res M                               |
|                                               |
|            0 1 2                              |
|o3 = total: 4 4 1                              |
|         2: 1 . .                              |
|         3: 3 4 1                              |
|                                               |
|o3 : BettiTally                                |
+-----------------------------------------------+
|i4 : poincare M                                |
|                                               |
|      2     3     4    5                       |
|o4 = T  + 3T  - 4T  + T                        |
|                                               |
|o4 : ZZ[T]                                     |
+-----------------------------------------------+
|i5 : hilbertSeries M                           |
|                                               |
|      2     3     4    5                       |
|     T  + 3T  - 4T  + T                        |
|o5 = -------------------                       |
|                  4                            |
|           (1 - T)                             |
|                                               |
|o5 : Expression of class Divide                |
+-----------------------------------------------+

When $S$ is a $\ZZ^r$-graded ring in $n$ variables and $M$ a graded $S$-module,
the Hilbert series of $M$ is by definition the formal power series $$
HS(T_0,\dots,T_{n-1}) = \sum_{d\in\ZZ^r} \mathrm{dim}(M_d) T_0^{d_0} \cdots
T_{n-1}^{d_{n-1}}. $$ The coefficient of the term $T_0^{d_0} \cdots
T_{n-1}^{d_{n-1}}$ in the series is the number of basis elements of
$M_{d_0,...,d_{n-1}}$. When the multi-degree has a single component, the
coefficient of $T^d$ is dimension of $M_d$.

Since the Hilbert series is additive in exact sequences, the function poincare
can be used to get information about the minimal free resolution and hence the
syzygies of $M$. For more details, see Hilbert functions and free resolutions.

This polynomial is an element of the degrees ring, of $S$.
Notice that the monomial ordering used in the degrees ring is RevLex,
so the polynomials in it will be displayed with the smallest exponents
first.

compute the polynomial for a ring
=================================

  * Usage:
        poincare R
+------------------------------+
|i6 : R = ZZ/101[x]/ideal(x^2);|
+------------------------------+
|i7 : poincare R               |
|                              |
|          2                   |
|o7 = 1 - T                    |
|                              |
|o7 : ZZ[T]                    |
+------------------------------+
|i8 : numerator hilbertSeries R|
|                              |
|          2                   |
|o8 = 1 - T                    |
|                              |
|o8 : ZZ[T]                    |
+------------------------------+

Recall that the variables of the polynomial are the variables of the degrees
ring.

+---------------------------------------------------+
|i9 : R = ZZ/101[x,y, DegreeRank => 2]/ideal(x^2*y);|
+---------------------------------------------------+
|i10 : poincare R                                   |
|                                                   |
|           2                                       |
|o10 = 1 - T T                                      |
|           0 1                                     |
|                                                   |
|o10 : ZZ[T ..T ]                                   |
|          0   1                                    |
+---------------------------------------------------+
|i11 : numerator hilbertSeries R                    |
|                                                   |
|           2                                       |
|o11 = 1 - T T                                      |
|           0 1                                     |
|                                                   |
|o11 : ZZ[T ..T ]                                   |
|          0   1                                    |
+---------------------------------------------------+

compute the polynomial for a module
===================================

  * Usage:
        poincare M
+------------------------------------------------+
|i12 : R = ZZ/101[w..z];                         |
+------------------------------------------------+
|i13 : M = module monomialCurveIdeal(R, {1,3,4});|
+------------------------------------------------+
|i14 : poincare M                                |
|                                                |
|       2     3     4    5                       |
|o14 = T  + 3T  - 4T  + T                        |
|                                                |
|o14 : ZZ[T]                                     |
+------------------------------------------------+
|i15 : numerator reduceHilbert hilbertSeries M   |
|                                                |
|       2     3     4    5                       |
|o15 = T  + 3T  - 4T  + T                        |
|                                                |
|o15 : ZZ[T]                                     |
+------------------------------------------------+

compute the polynomial for the quotient of a ring by an ideal
=============================================================

  * Usage:
        poincare I

The this command computes the numerator of the Hilbert series of the
comodule, R^1/I, where R is the ring of I.

+---------------------------------------------+
|i16 : R = ZZ/101[w..z];                      |
+---------------------------------------------+
|i17 : I = monomialCurveIdeal(R, {1,3,4});    |
|                                             |
|o17 : Ideal of R                             |
+---------------------------------------------+
|i18 : poincare I                             |
|                                             |
|           2     3     4    5                |
|o18 = 1 - T  - 3T  + 4T  - T                 |
|                                             |
|o18 : ZZ[T]                                  |
+---------------------------------------------+
|i19 : poincare comodule I                    |
|                                             |
|           2     3     4    5                |
|o19 = 1 - T  - 3T  + 4T  - T                 |
|                                             |
|o19 : ZZ[T]                                  |
+---------------------------------------------+
|i20 : numerator hilbertSeries I              |
|                                             |
|           2     3     4    5                |
|o20 = 1 - T  - 3T  + 4T  - T                 |
|                                             |
|o20 : ZZ[T]                                  |
+---------------------------------------------+
|i21 : numerator reduceHilbert hilbertSeries I|
|                                             |
|                 2    3                      |
|o21 = 1 + 2T + 2T  - T                       |
|                                             |
|o21 : ZZ[T]                                  |
+---------------------------------------------+
|i22 : poincare module I                      |
|                                             |
|       2     3     4    5                    |
|o22 = T  + 3T  - 4T  + T                     |
|                                             |
|o22 : ZZ[T]                                  |
+---------------------------------------------+

Caching of the result of poincare
=================================

When poincare M is called on a module $M$, the result is cached in
M.cache.poincare for future reference. For ideals, the polynomial is cached in
the comodule, of the ideal and for matrices, it is cached in
the cokernel, of the matrix. This can speed the computation of
Gröbner bases. For details, see computing Groebner bases.

If the numerator $p$ of the Hilbert series for a module $M$ is known by other
means, it can be manually stored by running:

+----------------------------------+
|                                  |
| poincare M = p -- cache poincare |
+----------------------------------+

This functionality used to be available by running installHilbertFunction(M,
p).

For example, in the following example, the Hilbert function of 3 random
polynomials should be the same as the Hilbert function for a complete
intersection.

+-----------------------------------------------------------------------------+
|i23 : R = ZZ/101[a..g];                                                      |
+-----------------------------------------------------------------------------+
|i24 : I = ideal random(R^1, R^{3:-3});                                       |
|                                                                             |
|o24 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i25 : p = poincare ideal(a^3, b^3, c^3)                                      |
|                                                                             |
|            3     6    9                                                     |
|o25 = 1 - 3T  + 3T  - T                                                      |
|                                                                             |
|o25 : ZZ[T]                                                                  |
+-----------------------------------------------------------------------------+
|i26 : poincare I = p                                                         |
|                                                                             |
|            3     6    9                                                     |
|o26 = 1 - 3T  + 3T  - T                                                      |
|                                                                             |
|o26 : ZZ[T]                                                                  |
+-----------------------------------------------------------------------------+
|i27 : gbTrace = 3                                                            |
|                                                                             |
|o27 = 3                                                                      |
+-----------------------------------------------------------------------------+
|i28 : time poincare I                                                        |
| -- used 0.000864725s (cpu); 7.815e-06s (thread); 0s (gc)                    |
|                                                                             |
|            3     6    9                                                     |
|o28 = 1 - 3T  + 3T  - T                                                      |
|                                                                             |
|o28 : ZZ[T]                                                                  |
+-----------------------------------------------------------------------------+
|i29 : time gens gb I;                                                        |
|                                                                             |
|   -- registering gb 19 at 0x7fdc5c199e00                                    |
|                                                                             |
|   -- [gb]{3}(3,3)mmm{4}(2,2)mm{5}(3,3)mmm{6}(2,6)mm{7}(1,4)m{8}(0,2)number  |
|   -- number of monomials                = 4186                              |
|   -- #reduction steps = 38                                                  |
|   -- #spairs done = 11                                                      |
|   -- ncalls = 10                                                            |
|   -- nloop = 29                                                             |
|   -- nsaved = 0                                                             |
|   --  -- used 0.00899963s (cpu); 0.00904741s (thread); 0s (gc)              |
|                                                                             |
|              1      11                                                      |
|o29 : Matrix R  <-- R                                                        |
|-----------------------------------------------------------------------------|
|of (nonminimal) gb elements = 11                                             |
+-----------------------------------------------------------------------------+

In this case, the savings is minimal, but often it can be dramatic. Another
important situation is to compute a Gröbner basis using a different monomial
order.

+-----------------------------------------------------------------------------+
|i30 : R = QQ[a..d];                                                          |
+-----------------------------------------------------------------------------+
|i31 : I = ideal random(R^1, R^{3:-3});                                       |
|                                                                             |
|   -- registering gb 20 at 0x7fdc5c199c40                                    |
|                                                                             |
|   -- [gb]number of (nonminimal) gb elements = 0                             |
|   -- number of monomials                = 0                                 |
|   -- #reduction steps = 0                                                   |
|   -- #spairs done = 0                                                       |
|   -- ncalls = 0                                                             |
|   -- nloop = 0                                                              |
|   -- nsaved = 0                                                             |
|   --                                                                        |
|o31 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i32 : time p = poincare I                                                    |
|                                                                             |
|   -- registering gb 21 at 0x7fdc5c1998c0                                    |
|                                                                             |
|   -- [gb]{3}(3)mmm{4}(2)mm{5}(3)mmm{6}(6)mmoooo{7}(4)mooo{8}(2)oonumber of  |
|   -- number of monomials                = 267                               |
|   -- #reduction steps = 236                                                 |
|   -- #spairs done = 30                                                      |
|   -- ncalls = 10                                                            |
|   -- nloop = 20                                                             |
|   -- nsaved = 0                                                             |
|   --  -- used 0.00399942s (cpu); 0.00381295s (thread); 0s (gc)              |
|                                                                             |
|            3     6    9                                                     |
|o32 = 1 - 3T  + 3T  - T                                                      |
|                                                                             |
|o32 : ZZ[T]                                                                  |
|-----------------------------------------------------------------------------|
|(nonminimal) gb elements = 11                                                |
+-----------------------------------------------------------------------------+
|i33 : S = QQ[a..d, MonomialOrder => Eliminate 2]                             |
|                                                                             |
|o33 = S                                                                      |
|                                                                             |
|o33 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i34 : J = substitute(I, S)                                                   |
|                                                                             |
|             2 3   4 2        2   5 3   5 2    3         2    5 2    1       |
|o34 = ideal (-a  + -a b + 2a*b  + -b  + -a c + -a*b*c + b c + -a d + -a*b*d +|
|             5     9              2     3      2              6      7       |
|      -----------------------------------------------------------------------|
|        2       2   5   2   1        1        9   2       2   8 3   4 2      |
|      2b d + a*c  + -b*c  + -a*c*d + -b*c*d + -a*d  + 3b*d  + -c  + -c d +   |
|                    3       9        2        7               7     3        |
|      -----------------------------------------------------------------------|
|      3   2   3 3   3   6 2    5   2   1 3   6 2             1 2    6 2      |
|      -c*d  + -d , a  + -a b + -a*b  + -b  + -a c + 6a*b*c + -b c + -a d +   |
|      5       2         5      2       4     5               3      7        |
|      -----------------------------------------------------------------------|
|               3 2       2      2    3        3        9   2   1   2   1 3   |
|      a*b*d + --b d + a*c  + b*c  + --a*c*d + -b*c*d + -a*d  + -b*d  + -c  + |
|              10                    10        8        4       2       3     |
|      -----------------------------------------------------------------------|
|      1 2        2   8 3  5 3   3 2    1   2   3 3     2            1 2      |
|      -c d + 2c*d  + -d , -a  + -a b + -a*b  + -b  + 7a c + a*b*c + -b c +   |
|      2              7    7     2      3       2                    5        |
|      -----------------------------------------------------------------------|
|      5 2    6        5 2    1   2   1   2            3           2    1   2 |
|      -a d + -a*b*d + -b d + -a*c  + -b*c  + 2a*c*d + -b*c*d + a*d  + --b*d  |
|      3      5        4      2       8                2               10     |
|      -----------------------------------------------------------------------|
|        7 3   8 2    7   2    3                                              |
|      + -c  + -c d + -c*d  + d )                                             |
|        5     5      8                                                       |
|                                                                             |
|o34 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i35 : poincare J = p                                                         |
|                                                                             |
|            3     6    9                                                     |
|o35 = 1 - 3T  + 3T  - T                                                      |
|                                                                             |
|o35 : ZZ[T]                                                                  |
+-----------------------------------------------------------------------------+
|i36 : gbTrace = 3                                                            |
|                                                                             |
|o36 = 3                                                                      |
+-----------------------------------------------------------------------------+
|i37 : time gens gb J;                                                        |
|                                                                             |
|   -- registering gb 22 at 0x7fdc5c199700                                    |
|                                                                             |
|   -- [gb]{3}(3,3)mmm{4}(2,2)mm{5}(3,3)mmm{6}(3,7)mmm{7}(3,8)mmm{8           |
|   -- mm{10}(2,8)mm{11}(1,5)m{12}(1,3)m{13}(1,3)m{14}(1,3)m{15}(1,           |
|   -- {17}(1,3)m{18}(1,3)m{19}(1,3)m{20}(1,3)m{21}(1,3)m{22}(1,3)m           |
|   -- {25}(1,3)m{26}(1,3)m{27}(1,3)m{28}(0,2)number of (nonminimal           |
|   -- number of monomials                = 1051                              |
|   -- #reduction steps = 284                                                 |
|   -- #spairs done = 53                                                      |
|   -- ncalls = 46                                                            |
|   -- nloop = 54                                                             |
|   -- nsaved = 0                                                             |
|   --  -- used 0.0369202s (cpu); 0.0365509s (thread); 0s (gc)                |
|                                                                             |
|              1      39                                                      |
|o37 : Matrix S  <-- S                                                        |
|-----------------------------------------------------------------------------|
|}(3,9)mmm{9}(3,9)m                                                           |
|3)m{16}(1,3)m                                                                |
|{23}(1,3)m{24}(1,3)m                                                         |
|) gb elements = 39                                                           |
+-----------------------------------------------------------------------------+
|i38 : selectInSubring(1, gens gb J)                                          |
|                                                                             |
|o38 = | 243873059890414515367459726418219472801881021280016638460434780718278|
|      -----------------------------------------------------------------------|
|      1440000c27+680473430096987971146702628170541552971659410296860500064419|
|      -----------------------------------------------------------------------|
|      8659321541120000c26d+11597364228740720976813725657514406124738091415081|
|      -----------------------------------------------------------------------|
|      708788717896930979185664000c25d2+                                      |
|      -----------------------------------------------------------------------|
|      23593854948820747270541718485240316584065850799950623007351199460826287|
|      -----------------------------------------------------------------------|
|      616000c24d3+32743644647016475216170069528641722426835477775253543592889|
|      -----------------------------------------------------------------------|
|      918133322668441600c23d4+                                               |
|      -----------------------------------------------------------------------|
|      33158095190154155829221377356630179888238312515669425233096064578894340|
|      -----------------------------------------------------------------------|
|      119040c22d5+15028595287222793638671643791164484488028666170821129484464|
|      -----------------------------------------------------------------------|
|      0913474618113410688c21d6-                                              |
|      -----------------------------------------------------------------------|
|      21512804869970961505730654467974378533992989635620845013046053149115691|
|      -----------------------------------------------------------------------|
|      376640c20d7+28431980514156020200015862091261060783608362711779183901930|
|      -----------------------------------------------------------------------|
|      9806045574261823520c19d8+                                              |
|      -----------------------------------------------------------------------|
|      16650730381353978595863327607516214447500495532056234936672555655369716|
|      -----------------------------------------------------------------------|
|      831120c18d9+87968827795245198558720802391460287994055816649663973831801|
|      -----------------------------------------------------------------------|
|      513286446550410048c17d10+                                              |
|      -----------------------------------------------------------------------|
|      22959959692503790373650797595979928852024328895071866607353571279986753|
|      -----------------------------------------------------------------------|
|      6198896c16d11-186238464624475812059215969192404399881338554287087040105|
|      -----------------------------------------------------------------------|
|      246208136582238056824c15d12+                                           |
|      -----------------------------------------------------------------------|
|      24548920676014640650981729325587232424855337187862713658240676351249839|
|      -----------------------------------------------------------------------|
|      5829972c14d13-141132193544414336210863578442532364572117789942199579134|
|      -----------------------------------------------------------------------|
|      726132062555878780658c13d14+                                           |
|      -----------------------------------------------------------------------|
|      80520443561444628031196207946045746850357450872252370351009550385550378|
|      -----------------------------------------------------------------------|
|      086681c12d15-2278233247601720373545720827573468959013067281967477143592|
|      -----------------------------------------------------------------------|
|      7358914316617821352c11d16+                                             |
|      -----------------------------------------------------------------------|
|      12315466375513693509230290342016673656670249832613715660807956483127262|
|      -----------------------------------------------------------------------|
|      733880c10d17+4719437472003410614922275085496115471668279624745540404962|
|      -----------------------------------------------------------------------|
|      433899525703062436c9d18+                                               |
|      -----------------------------------------------------------------------|
|      74497958923598706042158991668350708405967894269886723021144934645580613|
|      -----------------------------------------------------------------------|
|      74608c8d19+334728676747320315154276056749403769663819349640069418486913|
|      -----------------------------------------------------------------------|
|      9937175077192912c7d20+2106534096122290217776886174919161239203477897917|
|      -----------------------------------------------------------------------|
|      158167686354319461999466336c6d21+                                      |
|      -----------------------------------------------------------------------|
|      46016969029446996772206730674250118343258593659063037978247047403425711|
|      -----------------------------------------------------------------------|
|      5680c5d22+1542848777781200461682672598621194432349177258865304071672664|
|      -----------------------------------------------------------------------|
|      34720712424352c4d23+209766195470884862406436228545283251810588018452908|
|      -----------------------------------------------------------------------|
|      50471734381682038429280c3d24+                                          |
|      -----------------------------------------------------------------------|
|      70221637578010351138072776173836055657918796706303534104710104349853120|
|      -----------------------------------------------------------------------|
|      0c2d25+9531871659255442565995582182062188830769684462513069209840585989|
|      -----------------------------------------------------------------------|
|      184000cd26+127037175535596202927970476797708894400916603090057099058781|
|      -----------------------------------------------------------------------|
|      42251744000d27 |                                                       |
|                                                                             |
|              1      1                                                       |
|o38 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+

Caveat
======

This function may behave unpredictably in presence of variables of degree zero.

See also
========

  * poincareN -- assemble degrees into polynomial
  * poincare(ChainComplex) -- assemble
    degrees of a chain complex into a polynomial
  * degreesRing -- the ring or monoid of degrees
  * hilbertFunction -- the Hilbert function
  * hilbertSeries -- compute the Hilbert series
  * hilbertPolynomial -- compute the Hilbert
    polynomial
  * reduceHilbert -- reduce a Hilbert series expression
  * selectInSubring -- select columns in a subring
  * Elimination -- eliminating specified variables,
    and Sylvester resultant

Ways to use poincare:
=====================

  * "poincare(BettiTally)" -- see BettiTally, -- the class of
    all Betti tallies
  * "poincare(Ideal)"
  * "poincare(Module)"
  * "poincare(MonomialIdeal)"
  * "poincare(Ring)"
  * poincare(ChainComplex) -- assemble
    degrees of a chain complex into a polynomial

For the programmer
==================

The object poincare, is a method function.

poincareN -- assemble degrees into polynomial
*********************************************

Synopsis
========

  * Usage:
        poincareN C
  * Inputs:
      * C, a chain complex,
  * Outputs:
      * a ring element, in the Laurent polynomial ring
        degrees ring, whose variables correspond to the
        degrees of the ambient ring

Description
===========

This function encodes information about the degrees of basis elements of a free
chain complex in a polynomial. The polynomial has terms $S^i T_0^{d_0} \cdots
T_{n-1}^{d_{n-1}}$ in it for each basis element of C_i with multi-degree
{d_0,...,d_(n-1)}.

+-------------------------------------------+
|i1 : R = ZZ/101[a,b,c, Degrees=>{1,1,2}];  |
+-------------------------------------------+
|i2 : C = res cokernel vars R               |
|                                           |
|      1      3      3      1               |
|o2 = R  <-- R  <-- R  <-- R  <-- 0         |
|                                           |
|     0      1      2      3      4         |
|                                           |
|o2 : ChainComplex                          |
+-------------------------------------------+
|i3 : betti C                               |
|                                           |
|            0 1 2 3                        |
|o3 = total: 1 3 3 1                        |
|         0: 1 2 1 .                        |
|         1: . 1 2 1                        |
|                                           |
|o3 : BettiTally                            |
+-------------------------------------------+
|i4 : p = poincareN C                       |
|                                           |
|                    2    2 2     2 3    3 4|
|o4 = 1 + 2S*T  + S*T  + S T  + 2S T  + S T |
|             0      0      0       0      0|
|                                           |
|o4 : ZZ[S, T ]                             |
|            0                              |
+-------------------------------------------+

Setting the S variable to -1 gives the polynomial calculated by
poincare(ChainComplex).

+-----------------------+
|i5 : sub(p, {S => -1}) |
|                       |
|                 3    4|
|o5 = 1 - 2T  + 2T  - T |
|           0     0    0|
|                       |
|o5 : ZZ[S, T ]         |
|            0          |
+-----------------------+
|i6 : poincare C        |
|                       |
|                3    4 |
|o6 = 1 - 2T + 2T  - T  |
|                       |
|o6 : ZZ[T]             |
+-----------------------+

Conversely, setting it to 1 gives the same polynomial for the direct sum of
components of the complex.

+-----------------------------+
|i7 : sub(p, {S => 1})        |
|                             |
|                 2     3    4|
|o7 = 1 + 2T  + 2T  + 2T  + T |
|           0     0     0    0|
|                             |
|o7 : ZZ[S, T ]               |
|            0                |
+-----------------------------+
|i8 : poincare sum C          |
|                             |
|                2     3    4 |
|o8 = 1 + 2T + 2T  + 2T  + T  |
|                             |
|o8 : ZZ[T]                   |
+-----------------------------+

See also
========

  * poincare -- assemble degrees of a ring, module, or ideal
    into a polynomial
  * degreesRing -- the ring or monoid of degrees
  * hilbertFunction -- the Hilbert function
  * hilbertSeries -- compute the Hilbert series
  * hilbertPolynomial -- compute the Hilbert
    polynomial
  * reduceHilbert -- reduce a Hilbert series expression
  * poincare(BettiTally) -- the class of all Betti tallies
  * sum(ChainComplex) -- direct sum of the
    components of a chain complex

Ways to use poincareN:
======================

  * "poincareN(ChainComplex)"

For the programmer
==================

The object poincareN, is a method function.

reduceHilbert -- reduce a Hilbert series expression
***************************************************

Synopsis
========

  * Usage:
        reduceHilbert H
  * Inputs:
      * H, a divide expression,
  * Outputs:
      * a divide expression, the Hilbert series reduced by
        removing common factors

Description
===========

This function is used to reduce the rational expression given by the command
hilbertSeries. It is not automatically reduced, but
sometimes it is useful to write it in reduced form. For instance, one might not
notice that the series is a polynomial until it is reduced.

+-----------------------------------+
|i1 : R = ZZ/101[x, Degrees => {2}];|
+-----------------------------------+
|i2 : I = ideal x^2;                |
|                                   |
|o2 : Ideal of R                    |
+-----------------------------------+
|i3 : s = hilbertSeries I           |
|                                   |
|           4                       |
|      1 - T                        |
|o3 = --------                      |
|           2                       |
|     (1 - T )                      |
|                                   |
|o3 : Expression of class Divide    |
+-----------------------------------+
|i4 : reduceHilbert s               |
|                                   |
|          2                        |
|     1 + T                         |
|o4 = ------                        |
|        1                          |
|                                   |
|o4 : Expression of class Divide    |
+-----------------------------------+

The reduction is partial, in the sense that the explicit factors of the
denominator are cancelled entirely or not at all.

+--------------------------------------------------+
|i5 : M = R^{0,-1}                                 |
|                                                  |
|      2                                           |
|o5 = R                                            |
|                                                  |
|o5 : R-module, free, degrees {0..1}               |
+--------------------------------------------------+
|i6 : hilbertSeries M                              |
|                                                  |
|       1 + T                                      |
|o6 = --------                                     |
|           2                                      |
|     (1 - T )                                     |
|                                                  |
|o6 : Expression of class Divide                   |
+--------------------------------------------------+
|i7 : f = reduceHilbert oo                         |
|                                                  |
|       1 + T                                      |
|o7 = --------                                     |
|           2                                      |
|     (1 - T )                                     |
|                                                  |
|o7 : Expression of class Divide                   |
+--------------------------------------------------+
|i8 : gcd( value numerator f, value denominator f )|
|                                                  |
|o8 = 1 + T                                        |
|                                                  |
|o8 : ZZ[T]                                        |
+--------------------------------------------------+

Ways to use reduceHilbert:
==========================

  * "reduceHilbert(Divide)"

For the programmer
==================

The object reduceHilbert, is a method function.

betti -- display or modify a Betti diagram
******************************************

Synopsis
========

  * Usage:
        betti M
  * Optional inputs,:
      * Minimize, => ...,
        default value false, minimal betti numbers of a non-minimal free
        resolution
      * Weights, => ..., default value null, view
        and set the weight vector of a Betti diagram

Description
===========

The function betti creates and displays the Betti diagram of mathematical
objects that can be presented using graded free modules and graded maps between
them, such as ideals, modules, and chain complexes. The returned
BettiTally, encapsulates the data from the entries of the displayed
Betti diagram, in case they are needed in a program.

+------------------------------------------+
|i1 : S = QQ[x,y,z,w];                     |
+------------------------------------------+
|i2 : I = monomialCurveIdeal(S, {1,2,3})   |
|                                          |
|             2                    2       |
|o2 = ideal (z  - y*w, y*z - x*w, y  - x*z)|
|                                          |
|o2 : Ideal of S                           |
+------------------------------------------+
|i3 : t = betti res I                      |
|                                          |
|            0 1 2                         |
|o3 = total: 1 3 2                         |
|         0: 1 . .                         |
|         1: . 3 2                         |
|                                          |
|o3 : BettiTally                           |
+------------------------------------------+
|i4 : peek oo                              |
|                                          |
|o4 = BettiTally{(0, {0}, 0) => 1}         |
|                (1, {2}, 2) => 3          |
|                (2, {3}, 3) => 2          |
+------------------------------------------+
|i5 : t#(1, {2}, 2)                        |
|                                          |
|o5 = 3                                    |
+------------------------------------------+

The keys are triples (i,d,h) encoding:

 i, the column labels, representing the homological degree;
-----------------------------------------------------------

 d, a list of integers giving a multidegree; and
------------------------------------------------

 h, the row labels, representing the dot product of a weight covector and d.
----------------------------------------------------------------------------

Only i and h are used in printing, and the weight covector can be modified by
specifying the betti(...,Weights=>...), option.
The heft vector, of the ring of the input object is the
default choice for the weight covector.

+------------------------------------------+
|i6 : R = QQ[a,b,c, Degrees => {-1,-2,-3}];|
+------------------------------------------+
|i7 : heft R                               |
|                                          |
|o7 = {-1}                                 |
|                                          |
|o7 : List                                 |
+------------------------------------------+
|i8 : betti koszul vars R                  |
|                                          |
|            0 1 2 3                       |
|o8 = total: 1 3 3 1                       |
|         0: 1 1 . .                       |
|         1: . 1 1 .                       |
|         2: . 1 1 .                       |
|         3: . . 1 1                       |
|                                          |
|o8 : BettiTally                           |
+------------------------------------------+

If the ring has no heft vector, then the weights vector is taken to be all
zero. If the option betti(...,Weights=>...), is
provided, the length of the given weight vector should be the same as the
degree length, of the ring of the input object.

+------------------------------+
|i9 : betti(oo, Weights => {1})|
|                              |
|            0 1 2 3           |
|o9 = total: 1 3 3 1           |
|        -9: . . . 1           |
|        -8: . . . .           |
|        -7: . . 1 .           |
|        -6: . . 1 .           |
|        -5: . . 1 .           |
|        -4: . 1 . .           |
|        -3: . 1 . .           |
|        -2: . 1 . .           |
|        -1: . . . .           |
|         0: 1 . . .           |
|                              |
|o9 : BettiTally               |
+------------------------------+

If the ring is multigraded, the function multigraded(BettiTally),
may be used to extract information from all degree components of
the Betti diagram at once.

+-------------------------------------------------------------+
|i10 : R = QQ[a,b,c,d, Degrees => {{1,0},{2,1},{0,1},{-2,1}}];|
+-------------------------------------------------------------+
|i11 : heft R                                                 |
|                                                             |
|o11 = {1, 3}                                                 |
|                                                             |
|o11 : List                                                   |
+-------------------------------------------------------------+
|i12 : B = betti res coker vars R                             |
|                                                             |
|             0 1 2 3 4                                       |
|o12 = total: 1 4 6 4 1                                       |
|          0: 1 2 1 . .                                       |
|          1: . . . . .                                       |
|          2: . 1 2 1 .                                       |
|          3: . . . . .                                       |
|          4: . 1 2 1 .                                       |
|          5: . . . . .                                       |
|          6: . . 1 2 1                                       |
|                                                             |
|o12 : BettiTally                                             |
+-------------------------------------------------------------+
|i13 : betti(B, Weights => {1,0})                             |
|                                                             |
|             0 1 2 3 4                                       |
|o13 = total: 1 4 6 4 1                                       |
|         -4: . . 1 1 .                                       |
|         -3: . 1 1 1 1                                       |
|         -2: . . 1 1 .                                       |
|         -1: . 1 1 . .                                       |
|          0: 1 1 1 1 .                                       |
|          1: . 1 1 . .                                       |
|                                                             |
|o13 : BettiTally                                             |
+-------------------------------------------------------------+
|i14 : betti(B, Weights => {0,1})                             |
|                                                             |
|             0 1 2 3 4                                       |
|o14 = total: 1 4 6 4 1                                       |
|         -1: . 1 3 3 1                                       |
|          0: 1 3 3 1 .                                       |
|                                                             |
|o14 : BettiTally                                             |
+-------------------------------------------------------------+
|i15 : multigraded B                                          |
|                                                             |
|          0          1              2           3     4      |
|o15 =  0: 1          .              .           .     .      |
|       1: . a+a^(-2)*b              .           .     .      |
|       2: .          .       a^(-1)*b           .     .      |
|       3: .          b              .           .     .      |
|       4: .          . a*b+a^(-2)*b^2           .     .      |
|       5: .      a^2*b              .  a^(-1)*b^2     .      |
|       6: .          .      a^3*b+b^2           .     .      |
|       7: .          .              .       a*b^2     .      |
|       8: .          .        a^2*b^2           .     .      |
|       9: .          .              . a^3*b^2+b^3     .      |
|      10: .          .              .           . a*b^3      |
|                                                             |
|o15 : MultigradedBettiTally                                  |
+-------------------------------------------------------------+

Betti table of a Groebner basis
===============================

  * Usage:
        betti G
  * Inputs:
      * G, a Gröbner basis,
      * Weights => ...
  * Outputs:
      * a Betti tally, a diagram showing the degrees of the
        generators of the source and target modules of the matrix of generators
        of G
+-----------------------------------+
|i16 : S = ZZ/10007[x,y];           |
+-----------------------------------+
|i17 : G = gb ideal(x^3+y^3, x*y^4);|
+-----------------------------------+
|i18 : gens G                       |
|                                   |
|o18 = | x3+y3 xy4 y7 |             |
|                                   |
|              1      3             |
|o18 : Matrix S  <-- S              |
+-----------------------------------+
|i19 : betti G                      |
|                                   |
|             0 1                   |
|o19 = total: 1 3                   |
|          0: 1 .                   |
|          1: . .                   |
|          2: . 1                   |
|          3: . .                   |
|          4: . 1                   |
|          5: . .                   |
|          6: . 1                   |
|                                   |
|o19 : BettiTally                   |
+-----------------------------------+

Betti diagram showing the degrees of the target and source of a map
===================================================================

  * Usage:
        betti f
  * Inputs:
      * f, a matrix,
      * Weights => ...
  * Outputs:
      * a Betti tally, a diagram showing the degrees of the
        generators of the source and target modules of f

The diagram ignores the degree of the map itself.

+---------------------------------------------+
|i20 : S = ZZ/10007[x,y];                     |
+---------------------------------------------+
|i21 : betti matrix {{x^3, x*y^2}, {y*x, y^2}}|
|                                             |
|             0 1                             |
|o21 = total: 2 2                             |
|          0: 2 .                             |
|          1: . .                             |
|          2: . 2                             |
|                                             |
|o21 : BettiTally                             |
+---------------------------------------------+

Betti diagram showing the degrees of generators and relations of a homogeneous module
=====================================================================================

  * Usage:
        betti M
  * Inputs:
      * M, a module,
      * Weights => ...
  * Outputs:
      * a Betti tally, showing the zero-th, first graded,
        and total Betti numbers of $M$.

Note that the Betti numbers are not minimized.

+---------------------------------------------------------------+
|i22 : S = ZZ/10007[x,y];                                       |
+---------------------------------------------------------------+
|i23 : betti coker matrix{{x^3, x*y^2}, {y*x^2, y^3}}           |
|                                                               |
|             0 1                                               |
|o23 = total: 2 2                                               |
|          0: 2 .                                               |
|          1: . .                                               |
|          2: . 2                                               |
|                                                               |
|o23 : BettiTally                                               |
+---------------------------------------------------------------+
|i24 : betti coker map(S^{0,-1}, , matrix{{x^2, y}, {y^3, x^2}})|
|                                                               |
|             0 1                                               |
|o24 = total: 2 2                                               |
|          0: 1 .                                               |
|          1: 1 .                                               |
|          2: . 1                                               |
|          3: . 1                                               |
|                                                               |
|o24 : BettiTally                                               |
+---------------------------------------------------------------+

Also see betti(CoherentSheaf) (missing documentation).

Betti diagram showing the degrees of generators of a homogeneous ideal
======================================================================

  * Usage:
        betti I
  * Inputs:
      * I, an ideal,
      * Weights => ...
  * Outputs:
      * a Betti tally, showing the degrees of the generators
        and relations of the quotient of the ambient ring by $I$

Note that the Betti numbers are not minimized.

+---------------------------+
|i25 : S = ZZ/10007[x,y];   |
+---------------------------+
|i26 : I = ideal(x,x^2,y^3);|
|                           |
|o26 : Ideal of S           |
+---------------------------+
|i27 : betti I              |
|                           |
|             0 1           |
|o27 = total: 1 3           |
|          0: 1 1           |
|          1: . 1           |
|          2: . 1           |
|                           |
|o27 : BettiTally           |
+---------------------------+
|i28 : betti comodule I     |
|                           |
|             0 1           |
|o28 = total: 1 3           |
|          0: 1 1           |
|          1: . 1           |
|          2: . 1           |
|                           |
|o28 : BettiTally           |
+---------------------------+

Betti diagram showing the of degrees in a graded module or chain complex
========================================================================

  * Usage:
        betti C
  * Inputs:
      * C, a graded module, or a chain complex,
      * Weights => ...
      * Minimize => ...
  * Outputs:
      * a Betti tally, showing the degrees of the generators
        of the modules in C

The diagram can be used to determine the degrees of the entries in the matrices
of the differentials in a chain complex (which is a type of graded module)
provided they are homogeneous maps of degree 0.

+-----------------------------------------------------+
|i29 : R = ZZ/101[a..h]                               |
|                                                     |
|o29 = R                                              |
|                                                     |
|o29 : PolynomialRing                                 |
+-----------------------------------------------------+
|i30 : p = genericMatrix(R,a,2,4)                     |
|                                                     |
|o30 = | a c e g |                                    |
|      | b d f h |                                    |
|                                                     |
|              2      4                               |
|o30 : Matrix R  <-- R                                |
+-----------------------------------------------------+
|i31 : q = generators gb p                            |
|                                                     |
|o31 = | g e c a 0     0     0     0     0     0     ||
|      | h f d b fg-eh dg-ch bg-ah de-cf be-af bc-ad ||
|                                                     |
|              2      10                              |
|o31 : Matrix R  <-- R                                |
+-----------------------------------------------------+
|i32 : C = resolution cokernel leadTerm q             |
|                                                     |
|       2      10      14      7      1               |
|o32 = R  <-- R   <-- R   <-- R  <-- R  <-- 0         |
|                                                     |
|      0      1       2       3      4      5         |
|                                                     |
|o32 : ChainComplex                                   |
+-----------------------------------------------------+
|i33 : betti C                                        |
|                                                     |
|             0  1  2 3 4                             |
|o33 = total: 2 10 14 7 1                             |
|          0: 2  4  6 4 1                             |
|          1: .  6  8 3 .                             |
|                                                     |
|o33 : BettiTally                                     |
+-----------------------------------------------------+

Column j of the top row of the diagram gives the rank of the free module C_j.
The entry in column j in the row labelled i is the number of basis elements of
(weighted) degree i+j in the free module  C_j. When the chain complex is the
resolution of a module the entries are the total and the graded Betti numbers
of the module.

See also
========

  * minimalBetti -- minimal betti numbers of (the minimal
    free resolution of) a homogeneous ideal or module
  * multigraded -- convert a Betti tally into a multigraded
    Betti tally
  * regularity -- compute the Castelnuovo-Mumford regularity
  * pdim -- calculate the projective dimension

Ways to use betti:
==================

  * "betti(ChainComplex)"
  * "betti(GradedModule)"
  * "betti(GroebnerBasis)"
  * "betti(Ideal)"
  * "betti(Matrix)"
  * "betti(Module)"
  * betti(BettiTally) -- view and set the weight
    vector of a Betti diagram
  * betti(CoherentSheaf) (missing documentation)

For the programmer
==================

The object betti, is a method function with options.

BettiTally -- the class of all Betti tallies
********************************************

Description
===========

A Betti tally is a special type of Tally, that is printed as a
display of graded Betti numbers. The class was created so the function
betti, could return something that both prints nicely and from which
information can be extracted.  The keys are triples (i,d,h) encoding:

 i, the column labels, representing the homological degree;
-----------------------------------------------------------

 d, a list of integers giving a multidegree; and
------------------------------------------------

 h, the row labels, representing the dot product of a weight covector and d.
----------------------------------------------------------------------------

Only i and h are used in printing, and the weight covector can be modified by
specifying the betti(...,Weights=>...), option to
betti(BettiTally).

+-----------------------------------------------------------------------------+
|i1 : t = new BettiTally from { (0,{0},0) => 1, (1,{1},1) => 2, (2,{3},3) =>  |
|                                                                             |
|            0 1 2                                                            |
|o1 = total: 1 2 7                                                            |
|         0: 1 2 .                                                            |
|         1: . . 3                                                            |
|         2: . . 4                                                            |
|                                                                             |
|o1 : BettiTally                                                              |
|-----------------------------------------------------------------------------|
|3, (2,{4},4) => 4 }                                                          |
+-----------------------------------------------------------------------------+
|i2 : betti(t, Weights => {2})                                                |
|                                                                             |
|            0 1 2                                                            |
|o2 = total: 1 2 7                                                            |
|         0: 1 . .                                                            |
|         1: . 2 .                                                            |
|         2: . . .                                                            |
|         3: . . .                                                            |
|         4: . . 3                                                            |
|         5: . . .                                                            |
|         6: . . 4                                                            |
|                                                                             |
|o2 : BettiTally                                                              |
+-----------------------------------------------------------------------------+
|i3 : peek oo                                                                 |
|                                                                             |
|o3 = BettiTally{(0, {0}, 0) => 1}                                            |
|                (1, {1}, 2) => 2                                             |
|                (2, {3}, 6) => 3                                             |
|                (2, {4}, 8) => 4                                             |
+-----------------------------------------------------------------------------+

For convenience, the operations of direct sum (see ++), tensor product
(see **), see codim, degree, dual,
see pdim, poincare, regularity,
and degree shifting (numbers in brackets or parentheses), have
been implemented for Betti tallies.  These operations mimic the corresponding
operations on chain complexes.

+--------------------------------------+
|i4 : t(5)                             |
|                                      |
|            0 1 2                     |
|o4 = total: 1 2 7                     |
|        -5: 1 2 .                     |
|        -4: . . 3                     |
|        -3: . . 4                     |
|                                      |
|o4 : BettiTally                       |
+--------------------------------------+
|i5 : t[-5]                            |
|                                      |
|            5 6 7                     |
|o5 = total: 1 2 7                     |
|        -5: 1 2 .                     |
|        -4: . . 3                     |
|        -3: . . 4                     |
|                                      |
|o5 : BettiTally                       |
+--------------------------------------+
|i6 : dual oo                          |
|                                      |
|            -7 -6 -5                  |
|o6 = total:  7  2  1                  |
|         3:  4  .  .                  |
|         4:  3  .  .                  |
|         5:  .  2  1                  |
|                                      |
|o6 : BettiTally                       |
+--------------------------------------+
|i7 : t ++ oo                          |
|                                      |
|            -7 -6 -5 -4 -3 -2 -1 0 1 2|
|o7 = total:  7  2  1  .  .  .  . 1 2 7|
|         0:  .  .  .  .  .  .  . 1 2 .|
|         1:  .  .  .  .  .  .  . . . 3|
|         2:  .  .  .  .  .  .  . . . 4|
|         3:  4  .  .  .  .  .  . . . .|
|         4:  3  .  .  .  .  .  . . . .|
|         5:  .  2  1  .  .  .  . . . .|
|                                      |
|o7 : BettiTally                       |
+--------------------------------------+
|i8 : t ** t                           |
|                                      |
|            0 1  2  3  4              |
|o8 = total: 1 4 18 28 49              |
|         0: 1 4  4  .  .              |
|         1: . .  6 12  .              |
|         2: . .  8 16  9              |
|         3: . .  .  . 24              |
|         4: . .  .  . 16              |
|                                      |
|o8 : BettiTally                       |
+--------------------------------------+
|i9 : pdim t                           |
|                                      |
|o9 = 2                                |
+--------------------------------------+
|i10 : codim t                         |
|                                      |
|o10 = 0                               |
+--------------------------------------+
|i11 : degree t                        |
|                                      |
|o11 = 6                               |
+--------------------------------------+
|i12 : poincare t                      |
|                                      |
|                 3     4              |
|o12 = 1 - 2T + 3T  + 4T               |
|                                      |
|o12 : ZZ[T]                           |
+--------------------------------------+
|i13 : regularity t                    |
|                                      |
|o13 = 2                               |
+--------------------------------------+

If the Betti tally represents the Betti numbers of a resolution of a module $M$
on a polynomial ring $R = K[x_0,...,x_n]$, then while the data does not
uniquely determine $M$, it suffices to compute the Hilbert polynomial,
and Hilbert series, of $M$.

+---------------------------------+
|i14 : n = 3                      |
|                                 |
|o14 = 3                          |
+---------------------------------+
|i15 : hilbertSeries(n, t)        |
|                                 |
|                 3     4         |
|      1 - 2T + 3T  + 4T          |
|o15 = ------------------         |
|                  3              |
|           (1 - T)               |
|                                 |
|o15 : Expression of class Divide |
+---------------------------------+
|i16 : hilbertPolynomial(n, t)    |
|                                 |
|o16 = 33*P  - 23*P  + 6*P        |
|          0       1      2       |
|                                 |
|o16 : ProjectiveHilbertPolynomial|
+---------------------------------+

A Betti tally can be multiplied by an integer or by a rational number, and the
values can be lifted to integers, when possible.

+------------------+
|i17 : (1/2) * t   |
|                  |
|             0 1 2|
|             1   7|
|o17 = total: - 1 -|
|             2   2|
|             1    |
|          0: - 1 .|
|             2    |
|                 3|
|          1: . . -|
|                 2|
|          2: . . 2|
|                  |
|o17 : BettiTally  |
+------------------+
|i18 : 2 * oo      |
|                  |
|             0 1 2|
|o18 = total: 1 2 7|
|          0: 1 2 .|
|          1: . . 3|
|          2: . . 4|
|                  |
|o18 : BettiTally  |
+------------------+
|i19 : lift(oo,ZZ) |
|                  |
|             0 1 2|
|o19 = total: 1 2 7|
|          0: 1 2 .|
|          1: . . 3|
|          2: . . 4|
|                  |
|o19 : BettiTally  |
+------------------+

Given a ring $R$, a chain complex with zero maps over $R$ that has a prescribed
Betti table can be constructed. Negative entries are ignored and rational
entries produce an error. Multigraded rings work only if the Betti tally
contains degrees of the correct degree length.

+--------------------------+
|i20 : R = QQ[x,y]         |
|                          |
|o20 = R                   |
|                          |
|o20 : PolynomialRing      |
+--------------------------+
|i21 : C = R^t             |
|                          |
|       1      2      7    |
|o21 = R  <-- R  <-- R     |
|                          |
|      0      1      2     |
|                          |
|o21 : ChainComplex        |
+--------------------------+
|i22 : betti C             |
|                          |
|             0 1 2        |
|o22 = total: 1 2 7        |
|          0: 1 2 .        |
|          1: . . 3        |
|          2: . . 4        |
|                          |
|o22 : BettiTally          |
+--------------------------+
|i23 : C.dd                |
|                          |
|           1         2    |
|o23 = 0 : R  <----- R  : 1|
|                0         |
|                          |
|           2         7    |
|      1 : R  <----- R  : 2|
|                0         |
|                          |
|o23 : ChainComplexMap     |
+--------------------------+

Contributors
============

Hans-Christian von Bothmer donated the last feature.

Types of Betti tally:
=====================

  * MultigradedBettiTally -- the class of all
    multigraded Betti tallies

Functions and methods returning a Betti tally:
==============================================

  * betti -- display or modify a Betti diagram
  * "BettiTally ** BettiTally"
  * "BettiTally ++ BettiTally"
  * "BettiTally Array"
  * "BettiTally ZZ"
  * "dual(BettiTally)"
  * "lift(BettiTally,type of ZZ)"
  * "QQ * BettiTally"
  * "ZZ * BettiTally"
  * minimalBetti -- minimal betti numbers of (the minimal
    free resolution of) a homogeneous ideal or module
  * "minimalBetti(Ideal)" -- see minimalBetti, -- minimal
    betti numbers of (the minimal free resolution of) a homogeneous ideal or
    module
  * "minimalBetti(Module)" -- see minimalBetti, -- minimal
    betti numbers of (the minimal free resolution of) a homogeneous ideal or
    module
  * truncate(BettiTally,InfiniteNumber,InfiniteNumber) (missing documentation)
  * truncate(BettiTally,InfiniteNumber,ZZ) (missing documentation)
  * truncate(BettiTally,ZZ,InfiniteNumber) (missing documentation)
  * truncate(BettiTally,ZZ,ZZ) (missing documentation)

Methods that use a Betti tally:
===============================

  * betti(BettiTally) -- view and set the weight
    vector of a Betti diagram
  * "codim(BettiTally)"
  * "degree(BettiTally)"
  * "hilbertPolynomial(ZZ,BettiTally)"
  * "hilbertSeries(ZZ,BettiTally)"
  * "pdim(BettiTally)"
  * "poincare(BettiTally)"
  * "regularity(BettiTally)"
  * "Ring ^ BettiTally"
  * BettiTally == BettiTally (missing documentation)
  * "multigraded(BettiTally)" -- see multigraded, -- convert
    a Betti tally into a multigraded Betti tally

For the programmer
==================

The object BettiTally, is a type, with ancestor
classes VirtualTally, < HashTable <
Thing.

MultigradedBettiTally -- the class of all multigraded Betti tallies
*******************************************************************

Description
===========

A multigraded Betti tally is a special type of BettiTally,
that is printed as a diagram of the multigraded Betti numbers. The class was
created so that the method multigraded(BettiTally), could
return something that both prints nicely and from which information could be
extracted. The content of a multigraded Betti tally is identical to the Betti
tally from which it was constructed.

+-----------------------------------------------------------------------------+
|i1 : B = new BettiTally from {(0, {0, 0}, 0) => 1, (1, {0, 2}, 2) => 1, (1,  |
|                                                                             |
|            0 1 2 3                                                          |
|o1 = total: 1 4 4 1                                                          |
|         0: 1 . . .                                                          |
|         1: . 4 4 1                                                          |
|                                                                             |
|o1 : BettiTally                                                              |
|-----------------------------------------------------------------------------|
|{1, 1}, 2) => 2, (1, {2, 0}, 2) => 1, (2, {1, 2}, 3) => 2, (2, {2, 1}, 3) => |
|-----------------------------------------------------------------------------|
|2, (3, {2, 2}, 4) => 1}                                                      |
+-----------------------------------------------------------------------------+
|i2 : B = multigraded B                                                       |
|                                                                             |
|        0             1               2       3                              |
|o2 = 0: 1             .               .       .                              |
|     2: . a^2+2*a*b+b^2               .       .                              |
|     3: .             . 2*a^2*b+2*a*b^2       .                              |
|     4: .             .               . a^2*b^2                              |
|                                                                             |
|o2 : MultigradedBettiTally                                                   |
+-----------------------------------------------------------------------------+
|i3 : peek B                                                                  |
|                                                                             |
|o3 = MultigradedBettiTally{(0, {0, 0}, 0) => 1}                              |
|                           (1, {0, 2}, 2) => 1                               |
|                           (1, {1, 1}, 2) => 2                               |
|                           (1, {2, 0}, 2) => 1                               |
|                           (2, {1, 2}, 3) => 2                               |
|                           (2, {2, 1}, 3) => 2                               |
|                           (3, {2, 2}, 4) => 1                               |
+-----------------------------------------------------------------------------+

By default the data is presented as a table of polynomials where each column
corresponds to a given homological degree appearing as the top entry and each
monomial in the other entries represents the multidegree of a given summand.

When compactMatrixForm, is set to false, the entries
represent the multidegree of summands ordered by the total weight. The number
of summands corresponding to a given multidegree appears to the left of the
multidegree.

+----------------------------------------+
|i4 : compactMatrixForm = false          |
|                                        |
|o4 = false                              |
+----------------------------------------+
|i5 : B                                  |
|                                        |
|            0        1        2        3|
|o5 = 1:{0, 0} 1:{0, 2} 2:{1, 2} 1:{2, 2}|
|              1:{2, 0} 2:{2, 1}         |
|              2:{1, 1}                  |
|                                        |
|o5 : MultigradedBettiTally              |
+----------------------------------------+

For convenience, various operations on BettiTally such as direct sum (see ++),
tensor product (see **), see pdim, and degree shifting
(numbers in brackets or parentheses) are extended to work with multigraded
Betti tables. These operations mimic the corresponding operations on chain
complexes.

+-----------------------------------------------------------------------------+
|i6 : compactMatrixForm = true                                                |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+
|i7 : B(-1,-1)                                                                |
|                                                                             |
|          0                     1                   2       3                |
|o7 = 0: a*b                     .                   .       .                |
|     2:   . a^3*b+2*a^2*b^2+a*b^3                   .       .                |
|     3:   .                     . 2*a^3*b^2+2*a^2*b^3       .                |
|     4:   .                     .                   . a^3*b^3                |
|                                                                             |
|o7 : MultigradedBettiTally                                                   |
+-----------------------------------------------------------------------------+
|i8 : B[1]                                                                    |
|                                                                             |
|        -1             0               1       2                             |
|o8 = 0:  1             .               .       .                             |
|     2:  . a^2+2*a*b+b^2               .       .                             |
|     3:  .             . 2*a^2*b+2*a*b^2       .                             |
|     4:  .             .               . a^2*b^2                             |
|                                                                             |
|o8 : MultigradedBettiTally                                                   |
+-----------------------------------------------------------------------------+
|i9 : B[1] ++ B                                                               |
|                                                                             |
|        -1             0               1               2       3             |
|o9 = 0:  1             1               .               .       .             |
|     2:  . a^2+2*a*b+b^2   a^2+2*a*b+b^2               .       .             |
|     3:  .             . 2*a^2*b+2*a*b^2 2*a^2*b+2*a*b^2       .             |
|     4:  .             .               .         a^2*b^2 a^2*b^2             |
|                                                                             |
|o9 : MultigradedBettiTally                                                   |
+-----------------------------------------------------------------------------+
|i10 : B ** B                                                                 |
|                                                                             |
|         0                 1                                 2               |
|o10 = 0: 1                 .                                 .               |
|      2: . 2*a^2+4*a*b+2*b^2                                 .               |
|      3: .                 .                   4*a^2*b+4*a*b^2               |
|      4: .                 . a^4+4*a^3*b+6*a^2*b^2+4*a*b^3+b^4               |
|      5: .                 .                                 .               |
|      6: .                 .                                 .               |
|      7: .                 .                                 .               |
|      8: .                 .                                 .               |
|                                                                             |
|o10 : MultigradedBettiTally                                                  |
|-----------------------------------------------------------------------------|
|                                    3                              4         |
|                                    .                              .         |
|                                    .                              .         |
|                                    .                              .         |
|                            2*a^2*b^2                              .         |
|4*a^4*b+12*a^3*b^2+12*a^2*b^3+4*a*b^4                              .         |
|                                    . 6*a^4*b^2+12*a^3*b^3+6*a^2*b^4         |
|                                    .                              .         |
|                                    .                              .         |
|-----------------------------------------------------------------------------|
|                  5       6                                                  |
|                  .       .                                                  |
|                  .       .                                                  |
|                  .       .                                                  |
|                  .       .                                                  |
|                  .       .                                                  |
|                  .       .                                                  |
|4*a^4*b^3+4*a^3*b^4       .                                                  |
|                  . a^4*b^4                                                  |
+-----------------------------------------------------------------------------+
|i11 : compactMatrixForm = false                                              |
|                                                                             |
|o11 = false                                                                  |
+-----------------------------------------------------------------------------+
|i12 : B ** B                                                                 |
|                                                                             |
|             0        1        2         3         4        5        6       |
|o12 = 1:{0, 0} 2:{2, 0} 4:{3, 1} 12:{3, 2}  6:{4, 2} 4:{4, 3} 1:{4, 4}       |
|               4:{1, 1} 4:{2, 1}  2:{2, 2} 12:{3, 3} 4:{3, 4}                |
|               2:{0, 2} 6:{2, 2} 12:{2, 3}  6:{2, 4}                         |
|                        4:{1, 2}  4:{1, 4}                                   |
|                        4:{1, 3}  4:{4, 1}                                   |
|                        1:{4, 0}                                             |
|                        1:{0, 4}                                             |
|                                                                             |
|o12 : MultigradedBettiTally                                                  |
+-----------------------------------------------------------------------------+

Contributors
============

This feature was implemented by Mahrud Sayrafi based on earlier work by Gregory
G. Smith.

See also
========

  * BettiTally -- the class of all Betti tallies
  * multigraded(BettiTally) -- convert a Betti tally into a
    multigraded Betti tally
  * compactMatrixForm -- global flag for compact
    printing

Functions and methods returning a multigraded Betti tally:
==========================================================

  * "multigraded(BettiTally)" -- see multigraded, -- convert
    a Betti tally into a multigraded Betti tally

Methods that use a multigraded Betti tally:
===========================================

  * "MultigradedBettiTally Sequence"
  * MultigradedBettiTally List (missing documentation)

For the programmer
==================

The object MultigradedBettiTally, is a type,
with ancestor classes BettiTally, <
VirtualTally < HashTable < Thing.

multigraded -- convert a Betti tally into a multigraded Betti tally
*******************************************************************

Synopsis
========

  * Usage:
        multigraded t
  * Inputs:
      * t, a Betti tally,
  * Outputs:
      * a multigraded Betti tally, different from
        the input only in the printed diagram

Description
===========

A multigraded Betti tally is a special type of BettiTally,
that both prints nicely and from which multigraded Betti numbers could be
easily extracted.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a..d, Degrees => {2:{1,0},2:{0,1}}];                         |
+-----------------------------------------------------------------------------+
|i2 : I = ideal random(R^1, R^{2:{-2,-2},2:{-3,-3}});                         |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : t = betti res I                                                         |
|                                                                             |
|            0 1  2  3 4                                                      |
|o3 = total: 1 4 13 14 4                                                      |
|         0: 1 .  .  . .                                                      |
|         1: . .  .  . .                                                      |
|         2: . .  .  . .                                                      |
|         3: . 2  .  . .                                                      |
|         4: . .  .  . .                                                      |
|         5: . 2  .  . .                                                      |
|         6: . .  1  . .                                                      |
|         7: . .  8  6 .                                                      |
|         8: . .  4  8 4                                                      |
|                                                                             |
|o3 : BettiTally                                                              |
+-----------------------------------------------------------------------------+
|i4 : B = multigraded t                                                       |
|                                                                             |
|         0         1                   2                   3                 |
|o4 =  0: 1         .                   .                   .                 |
|      4: . 2*a^2*b^2                   .                   .                 |
|      6: . 2*a^3*b^3                   .                   .                 |
|      8: .         .             a^4*b^4                   .                 |
|      9: .         . 4*a^5*b^4+4*a^4*b^5                   .                 |
|     10: .         . 2*a^7*b^3+2*a^3*b^7           6*a^5*b^5                 |
|     11: .         .                   . 4*a^7*b^4+4*a^4*b^7                 |
|     12: .         .                   .                   .                 |
|                                                                             |
|o4 : MultigradedBettiTally                                                   |
|-----------------------------------------------------------------------------|
|                  4                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|2*a^7*b^5+2*a^5*b^7                                                          |
+-----------------------------------------------------------------------------+

By changing the weights, we can reorder the columns of the diagram. The
following three displays show the first degree, the second degree, and the
total degree, respectively.

+-----------------------------------------------------------------------------+
|i5 : betti(B, Weights => {1,0})                                              |
|                                                                             |
|        0         1                 2         3         4                    |
|o5 = 0: 1         .                 .         .         .                    |
|     2: . 2*a^2*b^2                 .         .         .                    |
|     3: . 2*a^3*b^3         2*a^3*b^7         .         .                    |
|     4: .         . 4*a^4*b^5+a^4*b^4 4*a^4*b^7         .                    |
|     5: .         .         4*a^5*b^4 6*a^5*b^5 2*a^5*b^7                    |
|     7: .         .         2*a^7*b^3 4*a^7*b^4 2*a^7*b^5                    |
|                                                                             |
|o5 : MultigradedBettiTally                                                   |
+-----------------------------------------------------------------------------+
|i6 : betti(B, Weights => {0,1})                                              |
|                                                                             |
|        0         1                 2         3         4                    |
|o6 = 0: 1         .                 .         .         .                    |
|     2: . 2*a^2*b^2                 .         .         .                    |
|     3: . 2*a^3*b^3         2*a^7*b^3         .         .                    |
|     4: .         . 4*a^5*b^4+a^4*b^4 4*a^7*b^4         .                    |
|     5: .         .         4*a^4*b^5 6*a^5*b^5 2*a^7*b^5                    |
|     7: .         .         2*a^3*b^7 4*a^4*b^7 2*a^5*b^7                    |
|                                                                             |
|o6 : MultigradedBettiTally                                                   |
+-----------------------------------------------------------------------------+
|i7 : betti(B, Weights => {1,1})                                              |
|                                                                             |
|         0         1                   2                   3                 |
|o7 =  0: 1         .                   .                   .                 |
|      4: . 2*a^2*b^2                   .                   .                 |
|      6: . 2*a^3*b^3                   .                   .                 |
|      8: .         .             a^4*b^4                   .                 |
|      9: .         . 4*a^5*b^4+4*a^4*b^5                   .                 |
|     10: .         . 2*a^7*b^3+2*a^3*b^7           6*a^5*b^5                 |
|     11: .         .                   . 4*a^7*b^4+4*a^4*b^7                 |
|     12: .         .                   .                   .                 |
|                                                                             |
|o7 : MultigradedBettiTally                                                   |
|-----------------------------------------------------------------------------|
|                  4                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|2*a^7*b^5+2*a^5*b^7                                                          |
+-----------------------------------------------------------------------------+

See also
========

  * MultigradedBettiTally -- the class of all
    multigraded Betti tallies
  * betti(BettiTally) -- view and set the weight
    vector of a Betti diagram

Ways to use multigraded:
========================

  * "multigraded(BettiTally)"

For the programmer
==================

The object multigraded, is a method function.

betti(BettiTally) -- view and set the weight vector of a Betti diagram
**********************************************************************

Synopsis
========

  * Function: betti,
  * Usage:
        betti(t, Weights => w)
  * Inputs:
      * t, a Betti tally,
  * Optional inputs,:
      * Weights => a list, default value null, with the same
        length as the multidegrees in t, used as the weight vector w
      * Minimize, => ...,
        default value false, minimal betti numbers of a non-minimal free
        resolution
  * Outputs:
      * a Betti tally, with the same homological degrees,
        multidegrees, and ranks. If a weight vector w is provided, the total
        degree weights in the resulting Betti tally will be recomputed by
        taking the dot products of w with the multidegrees in the tally.

Description
===========

+-----------------------------------------------------+
|i1 : R = ZZ/101[a..d, Degrees => {2:{1,0}, 2:{0,1}}];|
+-----------------------------------------------------+
|i2 : I = ideal random(R^1, R^{2:{-2,-2}, 2:{-3,-3}});|
|                                                     |
|o2 : Ideal of R                                      |
+-----------------------------------------------------+
|i3 : t = betti res I                                 |
|                                                     |
|            0 1  2  3 4                              |
|o3 = total: 1 4 13 14 4                              |
|         0: 1 .  .  . .                              |
|         1: . .  .  . .                              |
|         2: . .  .  . .                              |
|         3: . 2  .  . .                              |
|         4: . .  .  . .                              |
|         5: . 2  .  . .                              |
|         6: . .  1  . .                              |
|         7: . .  8  6 .                              |
|         8: . .  4  8 4                              |
|                                                     |
|o3 : BettiTally                                      |
+-----------------------------------------------------+
|i4 : peek t                                          |
|                                                     |
|o4 = BettiTally{(0, {0, 0}, 0) => 1 }                |
|                (1, {2, 2}, 4) => 2                  |
|                (1, {3, 3}, 6) => 2                  |
|                (2, {3, 7}, 10) => 2                 |
|                (2, {4, 4}, 8) => 1                  |
|                (2, {4, 5}, 9) => 4                  |
|                (2, {5, 4}, 9) => 4                  |
|                (2, {7, 3}, 10) => 2                 |
|                (3, {4, 7}, 11) => 4                 |
|                (3, {5, 5}, 10) => 6                 |
|                (3, {7, 4}, 11) => 4                 |
|                (4, {5, 7}, 12) => 2                 |
|                (4, {7, 5}, 12) => 2                 |
+-----------------------------------------------------+

The following three displays show the first degree, the second degree, and the
total degree, respectively.

+-------------------------------------+
|i5 : betti(t, Weights => {1,0})      |
|                                     |
|            0 1  2  3 4              |
|o5 = total: 1 4 13 14 4              |
|         0: 1 .  .  . .              |
|         1: . 2  2  4 2              |
|         2: . 2  5  6 .              |
|         3: . .  4  . 2              |
|         4: . .  .  4 .              |
|         5: . .  2  . .              |
|                                     |
|o5 : BettiTally                      |
+-------------------------------------+
|i6 : betti(t, Weights => {0,1})      |
|                                     |
|            0 1  2  3 4              |
|o6 = total: 1 4 13 14 4              |
|         0: 1 .  .  . .              |
|         1: . 2  2  4 2              |
|         2: . 2  5  6 .              |
|         3: . .  4  . 2              |
|         4: . .  .  4 .              |
|         5: . .  2  . .              |
|                                     |
|o6 : BettiTally                      |
+-------------------------------------+
|i7 : betti(t, Weights => {1,1})      |
|                                     |
|            0 1  2  3 4              |
|o7 = total: 1 4 13 14 4              |
|         0: 1 .  .  . .              |
|         1: . .  .  . .              |
|         2: . .  .  . .              |
|         3: . 2  .  . .              |
|         4: . .  .  . .              |
|         5: . 2  .  . .              |
|         6: . .  1  . .              |
|         7: . .  8  6 .              |
|         8: . .  4  8 4              |
|                                     |
|o7 : BettiTally                      |
+-------------------------------------+
|i8 : peek oo                         |
|                                     |
|o8 = BettiTally{(0, {0, 0}, 0) => 1 }|
|                (1, {2, 2}, 4) => 2  |
|                (1, {3, 3}, 6) => 2  |
|                (2, {3, 7}, 10) => 2 |
|                (2, {4, 4}, 8) => 1  |
|                (2, {4, 5}, 9) => 4  |
|                (2, {5, 4}, 9) => 4  |
|                (2, {7, 3}, 10) => 2 |
|                (3, {4, 7}, 11) => 4 |
|                (3, {5, 5}, 10) => 6 |
|                (3, {7, 4}, 11) => 4 |
|                (4, {5, 7}, 12) => 2 |
|                (4, {7, 5}, 12) => 2 |
+-------------------------------------+

+-----------------------------------------------------------------------------+
|i9 : t' = multigraded t                                                      |
|                                                                             |
|         0         1                   2                   3                 |
|o9 =  0: 1         .                   .                   .                 |
|      4: . 2*a^2*b^2                   .                   .                 |
|      6: . 2*a^3*b^3                   .                   .                 |
|      8: .         .             a^4*b^4                   .                 |
|      9: .         . 4*a^5*b^4+4*a^4*b^5                   .                 |
|     10: .         . 2*a^7*b^3+2*a^3*b^7           6*a^5*b^5                 |
|     11: .         .                   . 4*a^7*b^4+4*a^4*b^7                 |
|     12: .         .                   .                   .                 |
|                                                                             |
|o9 : MultigradedBettiTally                                                   |
|-----------------------------------------------------------------------------|
|                  4                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|2*a^7*b^5+2*a^5*b^7                                                          |
+-----------------------------------------------------------------------------+
|i10 : betti(t', Weights => {1,0})                                            |
|                                                                             |
|         0         1                 2         3         4                   |
|o10 = 0: 1         .                 .         .         .                   |
|      2: . 2*a^2*b^2                 .         .         .                   |
|      3: . 2*a^3*b^3         2*a^3*b^7         .         .                   |
|      4: .         . 4*a^4*b^5+a^4*b^4 4*a^4*b^7         .                   |
|      5: .         .         4*a^5*b^4 6*a^5*b^5 2*a^5*b^7                   |
|      7: .         .         2*a^7*b^3 4*a^7*b^4 2*a^7*b^5                   |
|                                                                             |
|o10 : MultigradedBettiTally                                                  |
+-----------------------------------------------------------------------------+
|i11 : betti(t', Weights => {0,1})                                            |
|                                                                             |
|         0         1                 2         3         4                   |
|o11 = 0: 1         .                 .         .         .                   |
|      2: . 2*a^2*b^2                 .         .         .                   |
|      3: . 2*a^3*b^3         2*a^7*b^3         .         .                   |
|      4: .         . 4*a^5*b^4+a^4*b^4 4*a^7*b^4         .                   |
|      5: .         .         4*a^4*b^5 6*a^5*b^5 2*a^7*b^5                   |
|      7: .         .         2*a^3*b^7 4*a^4*b^7 2*a^5*b^7                   |
|                                                                             |
|o11 : MultigradedBettiTally                                                  |
+-----------------------------------------------------------------------------+
|i12 : betti(t', Weights => {1,1})                                            |
|                                                                             |
|          0         1                   2                   3                |
|o12 =  0: 1         .                   .                   .                |
|       4: . 2*a^2*b^2                   .                   .                |
|       6: . 2*a^3*b^3                   .                   .                |
|       8: .         .             a^4*b^4                   .                |
|       9: .         . 4*a^5*b^4+4*a^4*b^5                   .                |
|      10: .         . 2*a^7*b^3+2*a^3*b^7           6*a^5*b^5                |
|      11: .         .                   . 4*a^7*b^4+4*a^4*b^7                |
|      12: .         .                   .                   .                |
|                                                                             |
|o12 : MultigradedBettiTally                                                  |
|-----------------------------------------------------------------------------|
|                  4                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|                  .                                                          |
|2*a^7*b^5+2*a^5*b^7                                                          |
+-----------------------------------------------------------------------------+

See also
========

  * heft vectors
  * MultigradedBettiTally -- the class of all
    multigraded Betti tallies
  * multigraded -- convert a Betti tally into a multigraded
    Betti tally

Ways to use this method:
========================

  * betti(BettiTally) -- view and set the weight
    vector of a Betti diagram

betti(...,Minimize=>...) -- minimal betti numbers of a non-minimal free resolution
**********************************************************************************

Synopsis
========

  * Usage:
        betti(C, Minimize => true)
  * Inputs:
      * C, a chain complex, computed using
        FastNonminimal, (and therefore a non-minimal free
        resolution of an ideal or module in a polynomial ring or skew commuting
        polynomial ring, over a finite prime field)
  * Outputs:
      * a Betti tally,

Description
===========

Given a chain complex computed using res(I, FastNonminimal => true) (see
FastNonminimal), returns the minimal graded Betti numbers of
this complex.

+-----------------------------------------------------------------------------+
|i1 : I = Grassmannian(1,6, CoefficientRing => ZZ/101);                       |
|                                                                             |
|               ZZ                                                            |
|o1 : Ideal of ---[p   ..p   , p   , p   , p   , p   , p   , p   , p   , p   ,|
|              101  0,1   0,2   1,2   0,3   1,3   2,3   0,4   1,4   2,4   3,4 |
|-----------------------------------------------------------------------------|
|p   , p   , p   , p   , p   , p   , p   , p   , p   , p   , p   ]            |
| 0,5   1,5   2,5   3,5   4,5   0,6   1,6   2,6   3,6   4,6   5,6             |
+-----------------------------------------------------------------------------+
|i2 : S = ring I                                                              |
|                                                                             |
|o2 = S                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : elapsedTime C = res(I, FastNonminimal => true)                          |
| -- 1.98605s elapsed                                                         |
|                                                                             |
|      1      35      241      841      1781      2464      2294      1432    |
|o3 = S  <-- S   <-- S    <-- S    <-- S     <-- S     <-- S     <-- S     <--|
|                                                                             |
|     0      1       2        3        4         5         6         7        |
|                                                                             |
|o3 : ChainComplex                                                            |
|-----------------------------------------------------------------------------|
| 576      135      14                                                        |
|S    <-- S    <-- S   <-- 0                                                  |
|                                                                             |
|8        9        10      11                                                 |
+-----------------------------------------------------------------------------+

For a non-minimal resolution, see betti, gives the actual ranks of the
complex. If the option Minimize => true is given, the minimal Betti numbers are
returned.

+-------------------------------------------------------+
|i4 : betti C                                           |
|                                                       |
|            0  1   2   3    4    5    6    7   8   9 10|
|o4 = total: 1 35 241 841 1781 2464 2294 1432 576 135 14|
|         0: 1  .   .   .    .    .    .    .   .   .  .|
|         1: . 35 140 290  402  402  293  152  53  11  1|
|         2: .  . 101 514 1174 1577 1365  780 287  62  6|
|         3: .  .   .  37  204  479  621  480 221  56  6|
|         4: .  .   .   .    1    6   15   20  15   6  1|
|                                                       |
|o4 : BettiTally                                        |
+-------------------------------------------------------+
|i5 : betti(C, Minimize => true)                        |
|                                                       |
|            0  1   2   3   4    5   6   7   8  9 10    |
|o5 = total: 1 35 140 385 819 1080 819 385 140 35  1    |
|         0: 1  .   .   .   .    .   .   .   .  .  .    |
|         1: . 35 140 189  84    .   .   .   .  .  .    |
|         2: .  .   . 196 735 1080 735 196   .  .  .    |
|         3: .  .   .   .   .    .  84 189 140 35  .    |
|         4: .  .   .   .   .    .   .   .   .  .  1    |
|                                                       |
|o5 : BettiTally                                        |
+-------------------------------------------------------+

This command is useful if the non-minimal free resolution has already been
computed. However, to get the minimal betti numbers of an ideal or module, it
is recommended to use the function minimalBetti, as that
avoids much computation and allows the use of length and degree limits.

Further information
===================

  * Default value: false,
  * Function: betti, -- display or modify a Betti diagram
  * Option key: Minimize, -- an optional argument

Caveat
======

Released in M2 1.9, still experimental.  Only works over finite prime field. If
the complex is the resolution of a non-homogeneous or multi-homogeneous object,
then this function will result in an error.

See also
========

  * minimalBetti -- minimal betti numbers of (the minimal
    free resolution of) a homogeneous ideal or module
  * betti -- display or modify a Betti diagram
  * resolution -- projective resolution
  * resolution(...,FastNonminimal=>...) -- compute a
    non-minimal graded free resolution

Functions with optional argument named Minimize:
================================================

  * betti(...,Minimize=>...),
    -- minimal betti numbers of a non-minimal free resolution

minimalBetti -- minimal betti numbers of (the minimal free resolution of) a homogeneous ideal or module
*******************************************************************************************************

Synopsis
========

  * Usage:
        B = minimalBetti I
        B = minimalBetti(I, DegreeLimit=>d, LengthLimit=>len, Weights=>h)
  * Inputs:
      * I, an ideal, or a module, a homogeneous
        ideal or module in a singly graded polynomial ring or skew commuting
        polynomial ring over a finite prime field
  * Optional inputs,:
      * DegreeLimit => an integer, default value null, if given,
        only compute enough to determine the Betti diagram up to and including
        the row labelled d
      * LengthLimit => an integer, default value infinity, if given,
        only compute enough to determine the Betti diagram up to and including
        the column labelled len
      * Weights => a list, default value null, see
        betti(...,Weights=>...),
      * ParallelizeByDegree => a Boolean value, default value
        false, Use additional parallelism to compute different (homological
        degree, internal degree) pairs in parallel when possible. To control
        parallelism, see parallelism in engine computations,
  * Outputs:
      * a Betti tally,

Description
===========

Given a singly-graded module, this function computes the minimal betti numbers
of the module. If the input is an ideal $I \subset S$, it computes the minimal
betti numbers of $S^1/I$.

The algorithm used is based on the FastNonminimal,
algorithm, except that the complex is not constructed, resulting in a smaller
memory footprint and often reduced computation time.

+-----------------------------------------------------------------------------+
|i1 : I = Grassmannian(1,6, CoefficientRing => ZZ/101);                       |
|                                                                             |
|               ZZ                                                            |
|o1 : Ideal of ---[p   ..p   , p   , p   , p   , p   , p   , p   , p   , p   ,|
|              101  0,1   0,2   1,2   0,3   1,3   2,3   0,4   1,4   2,4   3,4 |
|-----------------------------------------------------------------------------|
|p   , p   , p   , p   , p   , p   , p   , p   , p   , p   , p   ]            |
| 0,5   1,5   2,5   3,5   4,5   0,6   1,6   2,6   3,6   4,6   5,6             |
+-----------------------------------------------------------------------------+
|i2 : S = ring I                                                              |
|                                                                             |
|o2 = S                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : elapsedTime C = minimalBetti I                                          |
| -- 1.98708s elapsed                                                         |
|                                                                             |
|            0  1   2   3   4    5   6   7   8  9 10                          |
|o3 = total: 1 35 140 385 819 1080 819 385 140 35  1                          |
|         0: 1  .   .   .   .    .   .   .   .  .  .                          |
|         1: . 35 140 189  84    .   .   .   .  .  .                          |
|         2: .  .   . 196 735 1080 735 196   .  .  .                          |
|         3: .  .   .   .   .    .  84 189 140 35  .                          |
|         4: .  .   .   .   .    .   .   .   .  .  1                          |
|                                                                             |
|o3 : BettiTally                                                              |
+-----------------------------------------------------------------------------+

One can compute smaller parts of the Betti table, by using DegreeLimit,
and/or LengthLimit.

+--------------------------------------------------------------------+
|i4 : I = ideal I_*;                                                 |
|                                                                    |
|o4 : Ideal of S                                                     |
+--------------------------------------------------------------------+
|i5 : elapsedTime C = minimalBetti(I, DegreeLimit=>2)                |
| -- .823763s elapsed                                                |
|                                                                    |
|            0  1   2   3   4    5   6   7                           |
|o5 = total: 1 35 140 385 819 1080 735 196                           |
|         0: 1  .   .   .   .    .   .   .                           |
|         1: . 35 140 189  84    .   .   .                           |
|         2: .  .   . 196 735 1080 735 196                           |
|                                                                    |
|o5 : BettiTally                                                     |
+--------------------------------------------------------------------+
|i6 : I = ideal I_*;                                                 |
|                                                                    |
|o6 : Ideal of S                                                     |
+--------------------------------------------------------------------+
|i7 : elapsedTime C = minimalBetti(I, DegreeLimit=>1, LengthLimit=>5)|
| -- .0273412s elapsed                                               |
|                                                                    |
|            0  1   2   3  4                                         |
|o7 = total: 1 35 140 189 84                                         |
|         0: 1  .   .   .  .                                         |
|         1: . 35 140 189 84                                         |
|                                                                    |
|o7 : BettiTally                                                     |
+--------------------------------------------------------------------+
|i8 : I = ideal I_*;                                                 |
|                                                                    |
|o8 : Ideal of S                                                     |
+--------------------------------------------------------------------+
|i9 : elapsedTime C = minimalBetti(I, LengthLimit=>5)                |
| -- 1.38998s elapsed                                                |
|                                                                    |
|            0  1   2   3   4    5                                   |
|o9 = total: 1 35 140 385 819 1080                                   |
|         0: 1  .   .   .   .    .                                   |
|         1: . 35 140 189  84    .                                   |
|         2: .  .   . 196 735 1080                                   |
|                                                                    |
|o9 : BettiTally                                                     |
+--------------------------------------------------------------------+

This function computes only as much of the non-minimal resolution as needed to
compute the desired Betti numbers.  Further calls will generally not recompute
previously computed parts of the resolution, except that if you ask for a
longer resolution than previously, it currently will recompute the resolution.
This behavior might change in later releases.

If one has already computed the non-minimal free resolution using
FastNonminimal, then one can use
betti(...,Minimize=>...), except
that it doesn't currently have support for DegreeLimit and LengthLimit, and
probably still computes more than is needed (it is still experimental).

Caveat
======

Only works over finite prime field. If the ideal or module is a non-homogeneous
or multi-homogeneous object, then this function will result in an error.

See also
========

  * betti -- display or modify a Betti diagram
  * betti(...,Minimize=>...),
    -- minimal betti numbers of a non-minimal free resolution
  * resolution -- projective resolution
  * resolution(...,FastNonminimal=>...) -- compute a
    non-minimal graded free resolution

Ways to use minimalBetti:
=========================

  * "minimalBetti(Ideal)"
  * "minimalBetti(Module)"

For the programmer
==================

The object minimalBetti, is a method function with options.

basis -- basis or generating set of all or part of a ring, ideal or module
**************************************************************************

Synopsis
========

  * Usage:
        f = basis M
        f = basis(deg, M)
        f = basis(lo, hi, M)
  * Inputs:
      * M, a module, a ring, an ideal,
        or a matrix,
      * deg, an integer, or a list, a degree or degree
        vector
      * lo, an integer, or an infinite number,
        or -infinity, the low degree
      * hi, an integer, or an infinite number,
        or infinity, the high degree
  * Optional inputs,:
      * Limit => an integer, default value infinity, an upper bound
        on the number of basis elements to collect
      * Variables => a list, default value null, a list of
        variables, or variable indices (defaults to the generators of the ring
        of M)
      * SourceRing => a ring, default value null, if not the ring
        (of) M, then returns a module map whose target and source have
        different rings
      * Strategy => a thing, default value null, specifies the
        algorithm
      * Degree => an integer, or a list, default value
        null, sets the degree of the resulting matrix.  Default is 0.  Seldom
        Used
      * Truncate => a Boolean value, default value false,
        internal use only.  Used to implement truncate(ZZ,Module) (Truncations),
  * Outputs:
      * f, a matrix, a map from a free module over the ring of M
        (or by the ring specified with the SourceRing option, if given), to M
        which sends the basis elements of the free module to a basis (over the
        coefficient field) of the specified part of M

Description
===========

The function basis finds a basis or generating set of a module over a
coefficient ring, either for the full module, or for a degree range, or for a
specific (multi-)degree. A ring or ideal may also be provided instead of a
module.  Partial multi-degrees may also be given, see below for the usage and
meaning.

If $M$ is a matrix, then the matrix between the corresponding bases of the
source and target of $M$ is returned.  This feature should be considered
experimental.

The following examples show the varied uses of this function.

Basis of the whole ring

If no degree or degree range is given, then a full basis is given.  In the
example below, the 12 entries generate $R$ over the base ring ${\mathbb Q}$. If
the object is not finite, then an error is given.

+---------------------------------------------+
|i1 : R = QQ[a,b,c]/(a^2, b^3, a*c, c^3);     |
+---------------------------------------------+
|i2 : basis R                                 |
|                                             |
|o2 = | 1 a ab ab2 b b2 b2c b2c2 bc bc2 c c2 ||
|                                             |
|             1      12                       |
|o2 : Matrix R  <-- R                         |
+---------------------------------------------+
|i3 : sort basis R                            |
|                                             |
|o3 = | 1 c b a c2 bc b2 ab bc2 b2c ab2 b2c2 ||
|                                             |
|             1      12                       |
|o3 : Matrix R  <-- R                         |
+---------------------------------------------+

Basis in a degree or range of degrees

If a single degree or degree range is given, give a basis (or generating set)
of that particular degree (or degree range) of $M$.

+--------------------------+
|i4 : R = QQ[x,y,z]        |
|                          |
|o4 = R                    |
|                          |
|o4 : PolynomialRing       |
+--------------------------+
|i5 : basis(2,R)           |
|                          |
|o5 = | x2 xy xz y2 yz z2 ||
|                          |
|             1      6     |
|o5 : Matrix R  <-- R      |
+--------------------------+
|i6 : I = ideal"x2,y3"     |
|                          |
|             2   3        |
|o6 = ideal (x , y )       |
|                          |
|o6 : Ideal of R           |
+--------------------------+
|i7 : phi = basis(3,I)     |
|                          |
|o7 = {2} | x y z 0 |      |
|     {3} | 0 0 0 1 |      |
|                          |
|o7 : Matrix               |
+--------------------------+
|i8 : super phi            |
|                          |
|o8 = | x3 x2y x2z y3 |    |
|                          |
|             1      4     |
|o8 : Matrix R  <-- R      |
+--------------------------+

Notice that phi is a matrix whose source is a free module, and whose target is
the ideal.  See super, is used to get the actual elements of $I$.

Basis in a specific multi-degree

If a multidegree is given, then a range cannot be given. In this example, the
dimension over QQ of this multigraded piece of R is 2.

+------------------------------------------------+
|i9 : R = QQ[a..c,Degrees=>{{1,0},{1,-1},{1,-2}}]|
|                                                |
|o9 = R                                          |
|                                                |
|o9 : PolynomialRing                             |
+------------------------------------------------+
|i10 : basis({4,-5},R)                           |
|                                                |
|o10 = | abc2 b3c |                              |
|                                                |
|              1      2                          |
|o10 : Matrix R  <-- R                           |
+------------------------------------------------+

Partially described multidegrees

A partial multidegree can be given.  The given columns generate (form a basis
in this case) the degree \{2,*\} part of R, over the subring QQ[d] generated by
the variables which have degree \{0,*\}.

+-------------------------------------------------------+
|i11 : R = QQ[a..d,Degrees=>{{1,0},{1,-1},{1,-2},{0,1}}]|
|                                                       |
|o11 = R                                                |
|                                                       |
|o11 : PolynomialRing                                   |
+-------------------------------------------------------+
|i12 : basis(2,R)                                       |
|                                                       |
|o12 = | a2 ab ac b2 bc c2 |                            |
|                                                       |
|              1      6                                 |
|o12 : Matrix R  <-- R                                  |
+-------------------------------------------------------+

The base ring does not need to be a field.  In these cases, the given image
vectors might only generate over the base ring, not be a basis. For instance,
in the following example, $B$ is generated over $A$ by 4 elements, but $B$ is
not a free module.

+---------------------------------+
|i13 : A = ZZ/101[a..d];          |
+---------------------------------+
|i14 : B = A[x,y]/(a*x, x^2, y^2);|
+---------------------------------+
|i15 : try basis B                |
+---------------------------------+
|i16 : basis(B, Variables => B_*) |
|                                 |
|o16 = | 1 x xy y |               |
|                                 |
|              1      4           |
|o16 : Matrix B  <-- B            |
+---------------------------------+

If $M$ is an ideal or module, the resulting map looks somewhat strange, since
maps between modules are given from generators, in terms of the generators of
the target module.  Use super, or cover, to recover
the actual elements.

+------------------------------------------+
|i17 : R = QQ[a,b,c]/(a^2, b^3, a*c, c^3); |
+------------------------------------------+
|i18 : I = ideal(a,b^2,c)                  |
|                                          |
|                 2                        |
|o18 = ideal (a, b , c)                    |
|                                          |
|o18 : Ideal of R                          |
+------------------------------------------+
|i19 : F = basis I                         |
|                                          |
|o19 = {1} | 1 b 0 0 0 0  0 0 0  0 |       |
|      {2} | 0 0 1 a c c2 0 0 0  0 |       |
|      {1} | 0 0 0 0 0 0  1 b bc c |       |
|                                          |
|o19 : Matrix                              |
+------------------------------------------+
|i20 : super F                             |
|                                          |
|o20 = | a ab b2 ab2 b2c b2c2 c bc bc2 c2 ||
|                                          |
|              1      10                   |
|o20 : Matrix R  <-- R                     |
+------------------------------------------+
+---------------------------------------------------------+
|i21 : C = B[u,v]/(u^2,u*v,v^2)                           |
|                                                         |
|o21 = C                                                  |
|                                                         |
|o21 : QuotientRing                                       |
+---------------------------------------------------------+
|i22 : basis(C, Variables=>{u,v,x_C,y_C}, SourceRing => A)|
|                                                         |
|o22 = | 1 u xu xyu yu v xv xyv yv x xy y |               |
|                                                         |
|              1      12                                  |
|o22 : Matrix C  <-- A                                    |
+---------------------------------------------------------+

If Variables is given as an optional argument, only monomial multiples of the
generators which involve these variables will be considered.  In this case, the
resulting elements might not form a generating set over the coefficient ring.
They do generate over the subring generated by the other variables.

+----------------------------------+
|i23 : D = QQ[a..d]/(a^2, b^2)     |
|                                  |
|o23 = D                           |
|                                  |
|o23 : QuotientRing                |
+----------------------------------+
|i24 : basis(D, Variables => {a,b})|
|                                  |
|o24 = | 1 a ab b |                |
|                                  |
|              1      4            |
|o24 : Matrix D  <-- D             |
+----------------------------------+

If the base ring has a local term order, then the generating set or basis will
be over this ring.

+-----------------------------------------------------------------------------+
|i25 : E = QQ{a..d}                                                           |
|                                                                             |
|o25 = E                                                                      |
|                                                                             |
|o25 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i26 : I = ideal(a+d^3-d^4, b^2 + d^3, c^2 + d^4, d^5)                        |
|                                                                             |
|                  3    4   2    3   2    4   5                               |
|o26 = ideal (a + d  - d , b  + d , c  + d , d )                              |
|                                                                             |
|o26 : Ideal of E                                                             |
+-----------------------------------------------------------------------------+
|i27 : f = basis (E^1/I)                                                      |
|                                                                             |
|o27 = | 1 b bc bcd bcd2 bcd3 bcd4 bd bd2 bd3 bd4 c cd cd2 cd3 cd4 d d2 d3 d4 |
|      -----------------------------------------------------------------------|
|      |                                                                      |
|                                                                             |
|o27 : Matrix                                                                 |
+-----------------------------------------------------------------------------+
|i28 : cover f                                                                |
|                                                                             |
|o28 = | 1 b bc bcd bcd2 bcd3 bcd4 bd bd2 bd3 bd4 c cd cd2 cd3 cd4 d d2 d3 d4 |
|      -----------------------------------------------------------------------|
|      |                                                                      |
|                                                                             |
|              1      20                                                      |
|o28 : Matrix E  <-- E                                                        |
+-----------------------------------------------------------------------------+

Functoriality

basis is functorial, meaning that if $M : A \rightarrow B$ is a matrix between
two modules, then the result is the induced matrix on the images of the result
of basis applied to A and B.

+---------------------------------------------+
|i29 : R = ZZ/101[a..d]                       |
|                                             |
|o29 = R                                      |
|                                             |
|o29 : PolynomialRing                         |
+---------------------------------------------+
|i30 : M = koszul(2,vars R)                   |
|                                             |
|o30 = {1} | -b -c 0  -d 0  0  |              |
|      {1} | a  0  -c 0  -d 0  |              |
|      {1} | 0  a  b  0  0  -d |              |
|      {1} | 0  0  0  a  b  c  |              |
|                                             |
|              4      6                       |
|o30 : Matrix R  <-- R                        |
+---------------------------------------------+
|i31 : f1 = basis(2, source M)                |
|                                             |
|o31 = {2} | 1 0 0 0 0 0 |                    |
|      {2} | 0 1 0 0 0 0 |                    |
|      {2} | 0 0 1 0 0 0 |                    |
|      {2} | 0 0 0 1 0 0 |                    |
|      {2} | 0 0 0 0 1 0 |                    |
|      {2} | 0 0 0 0 0 1 |                    |
|                                             |
|              6      6                       |
|o31 : Matrix R  <-- R                        |
+---------------------------------------------+
|i32 : f2 = basis(2, target M)                |
|                                             |
|o32 = {1} | a b c d 0 0 0 0 0 0 0 0 0 0 0 0 ||
|      {1} | 0 0 0 0 a b c d 0 0 0 0 0 0 0 0 ||
|      {1} | 0 0 0 0 0 0 0 0 a b c d 0 0 0 0 ||
|      {1} | 0 0 0 0 0 0 0 0 0 0 0 0 a b c d ||
|                                             |
|              4      16                      |
|o32 : Matrix R  <-- R                        |
+---------------------------------------------+
|i33 : f = basis(2,M)                         |
|                                             |
|o33 = {2} | 0  0  0  0  0  0  |              |
|      {2} | -1 0  0  0  0  0  |              |
|      {2} | 0  -1 0  0  0  0  |              |
|      {2} | 0  0  0  -1 0  0  |              |
|      {2} | 1  0  0  0  0  0  |              |
|      {2} | 0  0  0  0  0  0  |              |
|      {2} | 0  0  -1 0  0  0  |              |
|      {2} | 0  0  0  0  -1 0  |              |
|      {2} | 0  1  0  0  0  0  |              |
|      {2} | 0  0  1  0  0  0  |              |
|      {2} | 0  0  0  0  0  0  |              |
|      {2} | 0  0  0  0  0  -1 |              |
|      {2} | 0  0  0  1  0  0  |              |
|      {2} | 0  0  0  0  1  0  |              |
|      {2} | 0  0  0  0  0  1  |              |
|      {2} | 0  0  0  0  0  0  |              |
|                                             |
|o33 : Matrix                                 |
+---------------------------------------------+
|i34 : source f == image f1                   |
|                                             |
|o34 = true                                   |
+---------------------------------------------+
|i35 : target f == image f2                   |
|                                             |
|o35 = true                                   |
+---------------------------------------------+

Obtain the map of free modules using matrix,:

+-------------------------------+
|i36 : matrix f                 |
|                               |
|o36 = {2} | 0  0  0  0  0  0  ||
|      {2} | -1 0  0  0  0  0  ||
|      {2} | 0  -1 0  0  0  0  ||
|      {2} | 0  0  0  -1 0  0  ||
|      {2} | 1  0  0  0  0  0  ||
|      {2} | 0  0  0  0  0  0  ||
|      {2} | 0  0  -1 0  0  0  ||
|      {2} | 0  0  0  0  -1 0  ||
|      {2} | 0  1  0  0  0  0  ||
|      {2} | 0  0  1  0  0  0  ||
|      {2} | 0  0  0  0  0  0  ||
|      {2} | 0  0  0  0  0  -1 ||
|      {2} | 0  0  0  1  0  0  ||
|      {2} | 0  0  0  0  1  0  ||
|      {2} | 0  0  0  0  0  1  ||
|      {2} | 0  0  0  0  0  0  ||
|                               |
|              16      6        |
|o36 : Matrix R   <-- R         |
+-------------------------------+

Caveat
======

If the base ring is not a field, then the result is only a generating set.  If
the optional argument Variables is provided, then even this might not be
correct.

See also
========

  * truncate(ZZ,Module) (Truncations), --
    truncation of the graded ring, ideal or module at a specified degree or set
    of degrees
  * sort(Matrix) -- sort the columns of a matrix
  * comodule -- submodule to quotient module
  * super -- get the ambient module
  * cover -- get the covering free module

Ways to use basis:
==================

  * "basis(Ideal)"
  * "basis(InfiniteNumber,InfiniteNumber,Ideal)"
  * "basis(InfiniteNumber,InfiniteNumber,Matrix)"
  * "basis(InfiniteNumber,InfiniteNumber,Module)"
  * "basis(InfiniteNumber,InfiniteNumber,Ring)"
  * "basis(InfiniteNumber,List,Ideal)"
  * "basis(InfiniteNumber,List,Matrix)"
  * "basis(InfiniteNumber,List,Module)"
  * "basis(InfiniteNumber,List,Ring)"
  * "basis(InfiniteNumber,ZZ,Ideal)"
  * "basis(InfiniteNumber,ZZ,Matrix)"
  * "basis(InfiniteNumber,ZZ,Module)"
  * "basis(InfiniteNumber,ZZ,Ring)"
  * "basis(List,Ideal)"
  * "basis(List,InfiniteNumber,Ideal)"
  * "basis(List,InfiniteNumber,Matrix)"
  * "basis(List,InfiniteNumber,Module)"
  * "basis(List,InfiniteNumber,Ring)"
  * "basis(List,List,Ideal)"
  * "basis(List,List,Matrix)"
  * "basis(List,List,Module)"
  * "basis(List,List,Ring)"
  * "basis(List,Matrix)"
  * "basis(List,Module)"
  * "basis(List,Ring)"
  * "basis(List,RingMap)"
  * "basis(List,ZZ,Ideal)"
  * "basis(List,ZZ,Matrix)"
  * "basis(List,ZZ,Module)"
  * "basis(List,ZZ,Ring)"
  * "basis(Matrix)"
  * "basis(Module)"
  * "basis(Ring)"
  * "basis(RingMap)"
  * "basis(Sequence,RingMap)"
  * "basis(ZZ,Ideal)"
  * "basis(ZZ,InfiniteNumber,Ideal)"
  * "basis(ZZ,InfiniteNumber,Matrix)"
  * "basis(ZZ,InfiniteNumber,Module)"
  * "basis(ZZ,InfiniteNumber,Ring)"
  * "basis(ZZ,List,Ideal)"
  * "basis(ZZ,List,Matrix)"
  * "basis(ZZ,List,Module)"
  * "basis(ZZ,List,Ring)"
  * "basis(ZZ,Matrix)"
  * "basis(ZZ,Module)"
  * "basis(ZZ,Ring)"
  * "basis(ZZ,RingMap)"
  * "basis(ZZ,ZZ,Ideal)"
  * "basis(ZZ,ZZ,Matrix)"
  * "basis(ZZ,ZZ,Module)"
  * "basis(ZZ,ZZ,Ring)"

For the programmer
==================

The object basis, is a method function with options.

exterior power of a module
**************************

The k-th exterior power of a module M is the k-fold tensor product of M
together with the equivalence relation:

        m_1 ** m_2 ** .. ** m_k = 0     if m_i = m_j for i != j

If M is a free R-module of rank n, then the k-th exterior power of M is a free
R-module of rank binomial(n,k). Macaulay2 computes the k-th exterior power of a
module M with the command exteriorPower.
+-------------------------+
|i1 : R = ZZ/2[x,y]       |
|                         |
|o1 = R                   |
|                         |
|o1 : PolynomialRing      |
+-------------------------+
|i2 : exteriorPower(3,R^6)|
|                         |
|      20                 |
|o2 = R                   |
|                         |
|o2 : R-module, free      |
+-------------------------+
|i3 : binomial(6,3)       |
|                         |
|o3 = 20                  |
+-------------------------+
Macaulay2 can compute exterior powers of modules that are not free as well.
+------------------------------+
|i4 : exteriorPower(2,R^1)     |
|                              |
|o4 = 0                        |
|                              |
|o4 : R-module                 |
+------------------------------+
|i5 : I = module ideal (x,y)   |
|                              |
|o5 = image | x y |            |
|                              |
|                             1|
|o5 : R-module, submodule of R |
+------------------------------+
|i6 : exteriorPower(2,I)       |
|                              |
|o6 = cokernel {2} | x y |     |
|                              |
|                            1 |
|o6 : R-module, quotient of R  |
+------------------------------+

See also
========

  * exterior power of a matrix

chain complexes
***************

For additional common operations and a comprehensive list of all routines in
Macaulay2 which return or use chain complexes or maps between chain complexes,
see ChainComplex, and ChainComplexMap.

free resolutions of modules
***************************

The function resolution, (also called res), can be used to
produce a free resolution of a module.
+---------------------------------------------+
|i1 : R = ZZ/101[x,y];                        |
+---------------------------------------------+
|i2 : m = ideal vars R                        |
|                                             |
|o2 = ideal (x, y)                            |
|                                             |
|o2 : Ideal of R                              |
+---------------------------------------------+
|i3 : M = m/m^3                               |
|                                             |
|o3 = subquotient (| x y |, | x3 x2y xy2 y3 |)|
|                                             |
|                               1             |
|o3 : R-module, subquotient of R              |
+---------------------------------------------+
|i4 : C = resolution M                        |
|                                             |
|      2      5      3                        |
|o4 = R  <-- R  <-- R  <-- 0                  |
|                                             |
|     0      1      2      3                  |
|                                             |
|o4 : ChainComplex                            |
+---------------------------------------------+
The default display for a chain complex shows the modules and the number of the
stage at which they appear.  See the documentation of resolution,
for details on the options that can be used to control the
computation.

The same function, applied to a map f, will produce a map from a free
resolution of the source of f to a free resolution of the target of f.
+---------------------------------------------+
|i5 : h = resolution inducedMap(M, m^2/m^4)   |
|                                             |
|          2                     3            |
|o5 = 0 : R  <----------------- R  : 0        |
|               {1} | x y 0 |                 |
|               {1} | 0 0 y |                 |
|                                             |
|          5                             7    |
|     1 : R  <------------------------- R  : 1|
|               {2} | 0 y 0 0 0 0 0 |         |
|               {3} | 0 0 x y 0 0 0 |         |
|               {3} | 0 0 0 0 0 0 0 |         |
|               {3} | 0 0 0 0 x y 0 |         |
|               {3} | 0 0 0 0 0 0 y |         |
|                                             |
|          3                       4          |
|     2 : R  <------------------- R  : 2      |
|               {4} | 0 y 0 0 |               |
|               {4} | 0 x 0 0 |               |
|               {4} | 0 0 0 y |               |
|                                             |
|     3 : 0 <----- 0 : 3                      |
|              0                              |
|                                             |
|o5 : ChainComplexMap                         |
+---------------------------------------------+

computing resolutions
*********************

Use the function resolution, often abbreviated as res, to
compute a free resolution of a module.
+----------------------------------+
|i1 : R = QQ[x..z];                |
+----------------------------------+
|i2 : M = cokernel vars R          |
|                                  |
|o2 = cokernel | x y z |           |
|                                  |
|                            1     |
|o2 : R-module, quotient of R      |
+----------------------------------+
|i3 : C = res M                    |
|                                  |
|      1      3      3      1      |
|o3 = R  <-- R  <-- R  <-- R  <-- 0|
|                                  |
|     0      1      2      3      4|
|                                  |
|o3 : ChainComplex                 |
+----------------------------------+
See chain complexes, for further details about how to
handle and examine the result.

A reference to the result is stored within the module M, so that requesting a
computation of res M a second time yields the formerly computed result
immediately.

If the computation is interrupted or discontinued after the skeleton has been
successfully computed, then the partially completed resolution is available as
M.cache.resolution, and can be examined with status.  The
computation can be continued with res M.  Here is an example, with an alarm
interrupting the computation several times before it's complete.  (On my
machine, the computation takes a total of 14 seconds.)  (Example code, such as
the code below, is run in such a way that interrupts stop the program, so to
prevent that, we set handleInterrupts, to true.)

+-----------------------------------------------------+
|i4 : R = ZZ/2[a..d];                                 |
+-----------------------------------------------------+
|i5 : M = coker random(R^4, R^{5:-3,6:-4});           |
+-----------------------------------------------------+
|i6 : handleInterrupts = true                         |
|                                                     |
|o6 = true                                            |
+-----------------------------------------------------+
|i7 : (<< "-- computation started: " << endl;         |
|      while true do try (                            |
|          alarm 1;                                   |
|          time res M;                                |
|          alarm 0;                                   |
|          << "-- computation complete" << endl;      |
|          status M.cache.resolution;                 |
|          << res M << endl << endl;                  |
|          break;                                     |
|          ) else (                                   |
|          << "-- computation interrupted" << endl;   |
|          status M.cache.resolution;                 |
|          << "-- continuing the computation" << endl;|
|          ))                                         |
| -- used 1.1341s (cpu); 1.00245s (thread); 0s (gc)   |
| -- used 0.37918s (cpu); 0.327655s (thread); 0s (gc) |
|-- computation started:                              |
|-- computation interrupted                           |
|-- continuing the computation                        |
|-- computation complete                              |
| 4      11      89      122      40                  |
|R  <-- R   <-- R   <-- R    <-- R   <-- 0            |
|                                                     |
|0      1       2       3        4       5            |
+-----------------------------------------------------+
If the user has a chain complex in hand that is known to be a projective
resolution of M, then it can be installed with M.cache.resolution = C.

There are various optional arguments associated with res,
which allow detailed control over the progress of the computation.

extracting information from chain complexes
*******************************************

Let's make a chain complex.
+----------------------------------------+
|i1 : R = ZZ/101[x,y,z];                 |
+----------------------------------------+
|i2 : C = res coker matrix {{x,y^2,z^3}};|
+----------------------------------------+
Some simple functions for discovering the shape of C.
  * length(ChainComplex) -- length of a chain
    complex or graded module
  * max(GradedModule)
  * min(GradedModule)
+-------------+
|i3 : length C|
|             |
|o3 = 3       |
+-------------+
|i4 : max C   |
|             |
|o4 = 4       |
+-------------+
|i5 : min C   |
|             |
|o5 = 0       |
+-------------+
In order to see the matrices of the differential maps in a chain complex,
examine C.dd.
+-------------------------------------------+
|i6 : C.dd                                  |
|                                           |
|          1                   3            |
|o6 = 0 : R  <--------------- R  : 1        |
|               | x y2 z3 |                 |
|                                           |
|          3                           3    |
|     1 : R  <----------------------- R  : 2|
|               {1} | -y2 -z3 0   |         |
|               {2} | x   0   -z3 |         |
|               {3} | 0   x   y2  |         |
|                                           |
|          3                   1            |
|     2 : R  <--------------- R  : 3        |
|               {3} | z3  |                 |
|               {4} | -y2 |                 |
|               {5} | x   |                 |
|                                           |
|          1                                |
|     3 : R  <----- 0 : 4                   |
|               0                           |
|                                           |
|o6 : ChainComplexMap                       |
+-------------------------------------------+
If C is a chain complex, then C_i will produce the i-th module in the complex,
C^i will produce the -i-th module in it, and C.dd_i will produce the
differential whose source is C_i.
+-----------------------------------+
|i7 : C_1                           |
|                                   |
|      3                            |
|o7 = R                             |
|                                   |
|o7 : R-module, free, degrees {1..3}|
+-----------------------------------+
|i8 : C^-1                          |
|                                   |
|      3                            |
|o8 = R                             |
|                                   |
|o8 : R-module, free, degrees {1..3}|
+-----------------------------------+
|i9 : C.dd_2                        |
|                                   |
|o9 = {1} | -y2 -z3 0   |           |
|     {2} | x   0   -z3 |           |
|     {3} | 0   x   y2  |           |
|                                   |
|             3      3              |
|o9 : Matrix R  <-- R               |
+-----------------------------------+
The function betti, can be used to display the ranks of the free
modules in C, together with the distribution of the basis elements by degree,
at least for resolutions of homogeneous modules.
+--------------------+
|i10 : betti C       |
|                    |
|             0 1 2 3|
|o10 = total: 1 3 3 1|
|          0: 1 1 . .|
|          1: . 1 1 .|
|          2: . 1 1 .|
|          3: . . 1 1|
|                    |
|o10 : BettiTally    |
+--------------------+
The ranks are displayed in the top row, and below that in row i column j is
displayed the number of basis elements of degree i+j in C_j.

making chain complexes by hand
******************************

A new chain complex can be made with C = new ChainComplex.  This will
automatically initialize C.dd, in which the differentials are stored. The
modules can be installed with statements like C#i=M and the differentials can
be installed with statements like C.dd#i=d. The ring is installed with C.ring =
R.  It's up to the user to ensure that the composite of consecutive
differential maps is zero.
+-------------------------+
|i1 : R = QQ[x,y,z];      |
+-------------------------+
|i2 : d1 = matrix {{x,y}};|
|                         |
|             1      2    |
|o2 : Matrix R  <-- R     |
+-------------------------+
We take care to use map, to ensure that the target of d2 is exactly
the same as the source of d1.
+------------------------------------------+
|i3 : d2 = map(source d1, ,{{y*z},{-x*z}});|
|                                          |
|             2      1                     |
|o3 : Matrix R  <-- R                      |
+------------------------------------------+
|i4 : d1 * d2 == 0                         |
|                                          |
|o4 = true                                 |
+------------------------------------------+
Now we make the chain complex, as explained above.
+-------------------------------------------------------+
|i5 : C = new ChainComplex; C.ring = R;                 |
+-------------------------------------------------------+
|i7 : C#0 = target d1; C#1 = source d1; C#2 = source d2;|
+-------------------------------------------------------+
|i10 : C.dd#1 = d1; C.dd#2 = d2;                        |
|                                                       |
|              1      2                                 |
|o10 : Matrix R  <-- R                                  |
|                                                       |
|              2      1                                 |
|o11 : Matrix R  <-- R                                  |
+-------------------------------------------------------+
Our complex is ready to use.
+------------------------------+
|i12 : C                       |
|                              |
|       1      2      1        |
|o12 = R  <-- R  <-- R         |
|                              |
|      0      1      2         |
|                              |
|o12 : ChainComplex            |
+------------------------------+
|i13 : HH_0 C                  |
|                              |
|o13 = cokernel | x y |        |
|                              |
|                             1|
|o13 : R-module, quotient of R |
+------------------------------+
|i14 : prune HH_1 C            |
|                              |
|o14 = cokernel {2} | z |      |
|                              |
|                             1|
|o14 : R-module, quotient of R |
+------------------------------+
The chain complex we've just made is simple, in the sense that it's a
homological chain complex with nonzero modules in degrees 0, 1, ..., n.  Such a
chain complex can be made also with chainComplex.  It goes
to a bit of extra trouble to adjust the differentials to match the degrees of
the basis elements.
+------------------------------------------------------------+
|i15 : D = chainComplex(matrix{{x,y}}, matrix {{y*z},{-x*z}})|
|                                                            |
|       1      2      1                                      |
|o15 = R  <-- R  <-- R                                       |
|                                                            |
|      0      1      2                                       |
|                                                            |
|o15 : ChainComplex                                          |
+------------------------------------------------------------+
|i16 : degrees source D.dd_2                                 |
|                                                            |
|o16 = {{3}}                                                 |
|                                                            |
|o16 : List                                                  |
+------------------------------------------------------------+

manipulating chain complexes
****************************

There are several natural ways to handle chain complexes; for details, see
ChainComplex.  Let's illustrate by making two chain
complexes.
+-----------------------------+
|i1 : R = QQ[x,y];            |
+-----------------------------+
|i2 : M = coker vars R        |
|                             |
|o2 = cokernel | x y |        |
|                             |
|                            1|
|o2 : R-module, quotient of R |
+-----------------------------+
|i3 : N = coker matrix {{x}}  |
|                             |
|o3 = cokernel | x |          |
|                             |
|                            1|
|o3 : R-module, quotient of R |
+-----------------------------+
|i4 : C = res M               |
|                             |
|      1      2      1        |
|o4 = R  <-- R  <-- R  <-- 0  |
|                             |
|     0      1      2      3  |
|                             |
|o4 : ChainComplex            |
+-----------------------------+
|i5 : D = res N               |
|                             |
|      1      1               |
|o5 = R  <-- R  <-- 0         |
|                             |
|     0      1      2         |
|                             |
|o5 : ChainComplex            |
+-----------------------------+
We can form the direct sum as follows.
+---------------------------+
|i6 : C ++ D                |
|                           |
|      2      3      1      |
|o6 = R  <-- R  <-- R  <-- 0|
|                           |
|     0      1      2      3|
|                           |
|o6 : ChainComplex          |
+---------------------------+
We can shift the degree, using the traditional notation.
+----------------------------+
|i7 : E = C[5]               |
|                            |
|      1      2      1       |
|o7 = R  <-- R  <-- R  <-- 0 |
|                            |
|     -5     -4     -3     -2|
|                            |
|o7 : ChainComplex           |
+----------------------------+
|i8 : E_-4 == C_1            |
|                            |
|o8 = true                   |
+----------------------------+
The same syntax can be used to make a chain complex from a single module.
+-----------------+
|i9 : R^4[1]      |
|                 |
|      4          |
|o9 = R           |
|                 |
|     -1          |
|                 |
|o9 : ChainComplex|
+-----------------+
We can form various tensor products with **, and compute
Tor, using them.
+-----------------------------------------+
|i10 : M ** D                             |
|                                         |
|o10 = M <-- cokernel {1} | x y |         |
|                                         |
|      0     1                            |
|                                         |
|o10 : ChainComplex                       |
+-----------------------------------------+
|i11 : C ** D                             |
|                                         |
|       1      3      3      1            |
|o11 = R  <-- R  <-- R  <-- R  <-- 0 <-- 0|
|                                         |
|      0      1      2      3      4     5|
|                                         |
|o11 : ChainComplex                       |
+-----------------------------------------+
|i12 : prune HH_1(C ** D)                 |
|                                         |
|o12 = cokernel {1} | y x |               |
|                                         |
|                             1           |
|o12 : R-module, quotient of R            |
+-----------------------------------------+
|i13 : prune HH_1(M ** D)                 |
|                                         |
|o13 = cokernel {1} | y x |               |
|                                         |
|                             1           |
|o13 : R-module, quotient of R            |
+-----------------------------------------+
|i14 : prune HH_1(C ** N)                 |
|                                         |
|o14 = cokernel {1} | y x |               |
|                                         |
|                             1           |
|o14 : R-module, quotient of R            |
+-----------------------------------------+
Of course, we can use Tor, to get the same result.
+------------------------------+
|i15 : prune Tor_1(M,N)        |
|                              |
|o15 = cokernel {1} | y x |    |
|                              |
|                             1|
|o15 : R-module, quotient of R |
+------------------------------+

maps between chain complexes
****************************

One way to make maps between chain complexes is by lifting maps between modules
to resolutions of those modules.  First we make some modules.
+-----------------------------+
|i1 : R = QQ[x,y];            |
+-----------------------------+
|i2 : M = coker vars R        |
|                             |
|o2 = cokernel | x y |        |
|                             |
|                            1|
|o2 : R-module, quotient of R |
+-----------------------------+
|i3 : N = coker matrix {{x}}  |
|                             |
|o3 = cokernel | x |          |
|                             |
|                            1|
|o3 : R-module, quotient of R |
+-----------------------------+
Let's construct the natural map from N to M.
+------------------------+
|i4 : f = inducedMap(M,N)|
|                        |
|o4 = | 1 |              |
|                        |
|o4 : Matrix M <-- N     |
+------------------------+
Let's lift the map to a map of free resolutions.
+---------------------------------+
|i5 : g = res f                   |
|                                 |
|          1             1        |
|o5 = 0 : R  <--------- R  : 0    |
|               | 1 |             |
|                                 |
|          2                 1    |
|     1 : R  <------------- R  : 1|
|               {1} | 1 |         |
|               {1} | 0 |         |
|                                 |
|          1                      |
|     2 : R  <----- 0 : 2         |
|               0                 |
|                                 |
|o5 : ChainComplexMap             |
+---------------------------------+
We can check that it's a map of chain complexes this way.
+-------------------------------------------+
|i6 : g * (source g).dd == (target g).dd * g|
|                                           |
|o6 = true                                  |
+-------------------------------------------+
We can form the mapping cone of g.
+---------------------------+
|i7 : F = cone g            |
|                           |
|      1      3      2      |
|o7 = R  <-- R  <-- R  <-- 0|
|                           |
|     0      1      2      3|
|                           |
|o7 : ChainComplex          |
+---------------------------+
Since f is surjective, we know that F is quasi-isomorphic to (kernel f)[-1].
Let's check that.
+------------------------------+
|i8 : prune HH_0 F             |
|                              |
|o8 = 0                        |
|                              |
|o8 : R-module                 |
+------------------------------+
|i9 : prune HH_1 F             |
|                              |
|o9 = cokernel {1} | x |       |
|                              |
|                            1 |
|o9 : R-module, quotient of R  |
+------------------------------+
|i10 : prune kernel f          |
|                              |
|o10 = cokernel {1} | x |      |
|                              |
|                             1|
|o10 : R-module, quotient of R |
+------------------------------+
There are more elementary ways to make maps between chain complexes.  The
identity map is available from id.
+------------------------------------+
|i11 : C = res M                     |
|                                    |
|       1      2      1              |
|o11 = R  <-- R  <-- R  <-- 0        |
|                                    |
|      0      1      2      3        |
|                                    |
|o11 : ChainComplex                  |
+------------------------------------+
|i12 : id_C                          |
|                                    |
|           1             1          |
|o12 = 0 : R  <--------- R  : 0      |
|                | 1 |               |
|                                    |
|           2                   2    |
|      1 : R  <--------------- R  : 1|
|                {1} | 1 0 |         |
|                {1} | 0 1 |         |
|                                    |
|           1                 1      |
|      2 : R  <------------- R  : 2  |
|                {2} | 1 |           |
|                                    |
|      3 : 0 <----- 0 : 3            |
|               0                    |
|                                    |
|o12 : ChainComplexMap               |
+------------------------------------+
|i13 : x * id_C                      |
|                                    |
|           1             1          |
|o13 = 0 : R  <--------- R  : 0      |
|                | x |               |
|                                    |
|           2                   2    |
|      1 : R  <--------------- R  : 1|
|                {1} | x 0 |         |
|                {1} | 0 x |         |
|                                    |
|           1                 1      |
|      2 : R  <------------- R  : 2  |
|                {2} | x |           |
|                                    |
|      3 : 0 <----- 0 : 3            |
|               0                    |
|                                    |
|o13 : ChainComplexMap               |
+------------------------------------+
We can use inducedMap, or ** to construct natural maps
between chain complexes.
+--------------------------------------------------------------------+
|i14 : inducedMap(C ** R^1/x,C)                                      |
|                                                                    |
|                                     1                              |
|o14 = 0 : cokernel | x | <--------- R  : 0                          |
|                            | 1 |                                   |
|                                                                    |
|                                                 2                  |
|      1 : cokernel {1} | x 0 | <--------------- R  : 1              |
|                   {1} | 0 x |    {1} | 1 0 |                       |
|                                  {1} | 0 1 |                       |
|                                                                    |
|                                             1                      |
|      2 : cokernel {2} | x | <------------- R  : 2                  |
|                                {2} | 1 |                           |
|                                                                    |
|o14 : ChainComplexMap                                               |
+--------------------------------------------------------------------+
|i15 : g ** R^1/x                                                    |
|                                                                    |
|o15 = 0 : cokernel | x | <--------- cokernel | x | : 0              |
|                            | 1 |                                   |
|                                                                    |
|      1 : cokernel {1} | x 0 | <------------- cokernel {1} | x | : 1|
|                   {1} | 0 x |    {1} | 1 |                         |
|                                  {1} | 0 |                         |
|                                                                    |
|o15 : ChainComplexMap                                               |
+--------------------------------------------------------------------+
There is a way to make a chain complex map by calling a function for each spot
that needs a map.
+----------------------------------------+
|i16 : q = map(C,C,i -> (i+1) * id_(C_i))|
|                                        |
|           1             1              |
|o16 = 0 : R  <--------- R  : 0          |
|                | 1 |                   |
|                                        |
|           2                   2        |
|      1 : R  <--------------- R  : 1    |
|                {1} | 2 0 |             |
|                {1} | 0 2 |             |
|                                        |
|           1                 1          |
|      2 : R  <------------- R  : 2      |
|                {2} | 3 |               |
|                                        |
|      3 : 0 <----- 0 : 3                |
|               0                        |
|                                        |
|o16 : ChainComplexMap                   |
+----------------------------------------+
Of course, the formula we used doesn't yield a map of chain complexes.
+--------------------------+
|i17 : C.dd * q == q * C.dd|
|                          |
|o17 = false               |
+--------------------------+

Gröbner bases
*************

A Groebner basis is a specific generating set for an ideal or submodule, often
used to compute other information, such as numerical invariants, operations
such as intersections and ideal quotients, syzygies, etc.  In Macaulay2,
Groebner bases are computed behind the scenes when needed, and the Groebner
basis is cached in case it is needed later.

See GroebnerBasis, for additional common operations and a
comprehensive list of all routines in Macaulay2 which either take Groebner
bases as arguments, or return one.

In Macaulay2, Groebner bases may be computed for ideals and submodules over the
following rings:
  * ZZ -- Hermite normal form
  * fields -- Gaussian elimination
  * polynomial rings over a field or over the integers (including skew
    commutative multiplication)
  * quotients of such rings
  * Weyl algebras
Groebner bases of ideals in polynomial rings over other polynomial rings are
also allowed.

fine control of Groebner basis computations

what is a Groebner basis?
*************************

A Groebner basis is a specific generating set of an ideal or submodule over a
polynomial ring. It is not minimal in general, but has extremely nice
properties; it is reasonably easy to extract information about the ideal or
submodule from a Groebner basis. We first describe Groebner bases in the
important special case of an ideal in a polynomial ring. We will then describe
Groebner bases of submodules, and over more general rings.

Let $R = k[x_1, ..., x_n]$ be a polynomial ring over a field $k$, and let $I
\subset R$ be an ideal.  A monomial order on $R$ is a total order, $>$,  on the
monomials of $R$, which satisfies two conditions: (1) $m > 1$, for every
monomial $m \neq 1$, and (2) the order is multiplicative: $m > n$ implies that
$mp > np$, for all monomials $m$, $n$, $p$.

In Macaulay2, each ring has a monomial order (also called a term order)
associated with it.  The default monomial order is GRevLex. See monomial orderings,
for more information.

Given a term order, the leading term is the one whose monomial is greatest in
this order.
+------------------------------------+
|i1 : R = ZZ/1277[a..d]              |
|                                    |
|o1 = R                              |
|                                    |
|o1 : PolynomialRing                 |
+------------------------------------+
|i2 : F = 5*a^3 + d^2 + a*d + b*c + 1|
|                                    |
|       3                2           |
|o2 = 5a  + b*c + a*d + d  + 1       |
|                                    |
|o2 : R                              |
+------------------------------------+
|i3 : leadTerm F                     |
|                                    |
|       3                            |
|o3 = 5a                             |
|                                    |
|o3 : R                              |
+------------------------------------+
For an ideal $I \subset R$, the initial ideal $in(I)$ is the ideal generated by
the leading terms of the elements in I. A Groebner basis for I is a set of
generators for I whose leading terms generate $in(I)$.

+-----------------------------------------------+
|i4 : R = ZZ/1277[x,y];                         |
+-----------------------------------------------+
|i5 : I = ideal(x^3 - 2*x*y, x^2*y - 2*y^2 + x);|
|                                               |
|o5 : Ideal of R                                |
+-----------------------------------------------+
|i6 : leadTerm I                                |
|                                               |
|o6 = | y2 xy x2 |                              |
|                                               |
|             1      3                          |
|o6 : Matrix R  <-- R                           |
+-----------------------------------------------+
|i7 : gens gb I                                 |
|                                               |
|o7 = | y2+638x xy x2 |                         |
|                                               |
|             1      3                          |
|o7 : Matrix R  <-- R                           |
+-----------------------------------------------+
The above example also shows that the leading terms of any set of generators of
I do not necessarily generate in(I).

A Groebner basis for an ideal depends on the monomial ordering used in the ring
.
+-----------------------------------------------+
|i8 : R = ZZ/1277[x,y, MonomialOrder => Lex];   |
+-----------------------------------------------+
|i9 : I = ideal(x^3 - 2*x*y, x^2*y - 2*y^2 + x);|
|                                               |
|o9 : Ideal of R                                |
+-----------------------------------------------+
|i10 : gens gb I                                |
|                                               |
|o10 = | y3 x-2y2 |                             |
|                                               |
|              1      2                         |
|o10 : Matrix R  <-- R                          |
+-----------------------------------------------+

See also
========

  * monomial orderings
  * leadTerm -- get the greatest term
  * Gröbner bases
  * normal forms

Groebner basis examples and applications
****************************************

simple Groebner basis computations over various rings
*****************************************************

For a definition of Groebner basis, see what is a Groebner basis?.

A first Groebner basis
======================

Weight vectors and non-strict monomial orders
=============================================

The monomial order may be given by a weight vector (see monomial orderings),
+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..f,MonomialOrder=>Weights=>{1,1,1,1,0,0}]                      |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(a*b*c-d*e*f,a*c*e-b*d*f,a*d*f-b*c*e)                          |
|                                                                             |
|o2 = ideal (a*b*c - d*e*f, a*c*e - b*d*f, - b*c*e + a*d*f)                   |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : gens gb I                                                               |
|                                                                             |
|o3 = | bce-adf ace-bdf abc-def b2df-de2f a2df-de2f c2de3f-d3ef3 abd2f2-cde3f |
|     ------------------------------------------------------------------------|
|     |                                                                       |
|                                                                             |
|             1      7                                                        |
|o3 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i4 : leadTerm I                                                              |
|                                                                             |
|o4 = | bce ace abc b2df a2df c2de3f abd2f2 |                                 |
|                                                                             |
|             1      7                                                        |
|o4 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
The monomial order used here is: first consider the dot product of the weight
vector and the exponent vectors.  The larger determines the lead term.  If
these dot products are the same, then ties are broken with graded reverse
lexicographic order.  Sometimes, one wants the lead term ideal with respect to
the weight vector itself. This ideal, often not a monomial ideal, may be
obtained by selecting only the first part of the monomial order while finding
the lead term matrix:
+----------------------------------------------------------+
|i5 : leadTerm(1,I)                                        |
|                                                          |
|o5 = | bce-adf ace-bdf abc b2df a2df c2de3f-d3ef3 abd2f2 ||
|                                                          |
|             1      7                                     |
|o5 : Matrix R  <-- R                                      |
+----------------------------------------------------------+

Groebner basis over the integers
================================

A strong Groebner basis of an ideal $I \subset{} ZZ[x_1,...,x_n]$ is a set $G$
of elements of $I$ such that, if $cm$ is any lead term of $I$ ($c$ a
coefficient, and $m$ a monomial), then there is an element of $G$ whose lead
term divides $cm$.

Macaulay2 computes such strong Groebner bases over ZZ.
+------------------------------------------------+
|i6 : R = ZZ[x,y]                                |
|                                                |
|o6 = R                                          |
|                                                |
|o6 : PolynomialRing                             |
+------------------------------------------------+
|i7 : F = y^2-(x^3+3*x+5)                        |
|                                                |
|        3    2                                  |
|o7 = - x  + y  - 3x - 5                         |
|                                                |
|o7 : R                                          |
+------------------------------------------------+
|i8 : I = ideal(F, diff(x,F), diff(y,F))         |
|                                                |
|               3    2               2           |
|o8 = ideal (- x  + y  - 3x - 5, - 3x  - 3, 2y)  |
|                                                |
|o8 : Ideal of R                                 |
+------------------------------------------------+
|i9 : gens gb I                                  |
|                                                |
|o9 = | 174 2y 6x-72 y2+87 3x2+3 x2y+y x3+3x-82 ||
|                                                |
|             1      7                           |
|o9 : Matrix R  <-- R                            |
+------------------------------------------------+
|i10 : leadTerm I                                |
|                                                |
|o10 = | 174 2y 6x y2 3x2 x2y x3 |               |
|                                                |
|              1      7                          |
|o10 : Matrix R  <-- R                           |
+------------------------------------------------+
|i11 : factor 174                                |
|                                                |
|o11 = 2*3*29                                    |
|                                                |
|o11 : Expression of class Product               |
+------------------------------------------------+
This elliptic curve is smooth for all primes $p \neq 2, 3, 29$.

Groebner basis over a quotient ring
===================================

The lead terms of the Groebner basis generate all possible lead terms modulo
the lead terms of the quotient ideal.
+--------------------------------------+
|i12 : R = QQ[a..d]/(a^2+b^2+c^2+d^2-1)|
|                                      |
|o12 = R                               |
|                                      |
|o12 : QuotientRing                    |
+--------------------------------------+
|i13 : I = ideal(a*b*c*d)              |
|                                      |
|o13 = ideal(a*b*c*d)                  |
|                                      |
|o13 : Ideal of R                      |
+--------------------------------------+
|i14 : gens gb I                       |
|                                      |
|o14 = | abcd b3cd+bc3d+bcd3-bcd |     |
|                                      |
|              1      2                |
|o14 : Matrix R  <-- R                 |
+--------------------------------------+

A Groebner basis over a skew-commutative ring
=============================================

The lead terms of the Groebner basis generate all possible lead terms, as in
the commutative case.  Essentially the same algorithm is applicable in this
case.
+----------------------------------------------------+
|i15 : R = QQ[a..d,SkewCommutative=>true]            |
|                                                    |
|o15 = R                                             |
|                                                    |
|o15 : PolynomialRing, 4 skew commutative variable(s)|
+----------------------------------------------------+
|i16 : I = ideal(a*b-c*d)                            |
|                                                    |
|o16 = ideal(a*b - c*d)                              |
|                                                    |
|o16 : Ideal of R                                    |
+----------------------------------------------------+
|i17 : gens gb I                                     |
|                                                    |
|o17 = | ab-cd bcd acd |                             |
|                                                    |
|              1      3                              |
|o17 : Matrix R  <-- R                               |
+----------------------------------------------------+

Groebner basis over polynomial rings over polynomial rings
==========================================================

For such rings, we may imagine a polynomial ring over a base field, or over the
integers, possibly modulo some ideal.  The resulting Groebner basis is this
one.  The monomial order is a product order, with the variables in the
outermost polynomial ring the most expensive.
+--------------------------------------+
|i18 : A = QQ[s,c]/(s^2+c^2-1)         |
|                                      |
|o18 = A                               |
|                                      |
|o18 : QuotientRing                    |
+--------------------------------------+
|i19 : B = A[x,y,z]                    |
|                                      |
|o19 = B                               |
|                                      |
|o19 : PolynomialRing                  |
+--------------------------------------+
|i20 : I = ideal(c*x^2, s*y^2, c*y-s*x)|
|                                      |
|                2     2               |
|o20 = ideal (c*x , s*y , - s*x + c*y) |
|                                      |
|o20 : Ideal of B                      |
+--------------------------------------+
|i21 : gens gb I                       |
|                                      |
|o21 = | sx-cy (c2-1)x+scy y2 xy x2 |  |
|                                      |
|              1      5                |
|o21 : Matrix B  <-- B                 |
+--------------------------------------+
|i22 : leadTerm oo                     |
|                                      |
|o22 = | sx c2x y2 xy x2 |             |
|                                      |
|              1      5                |
|o22 : Matrix B  <-- B                 |
+--------------------------------------+

A Groebner basis of a submodule
===============================

computing Groebner bases
************************

Groebner bases are computed with the gb command; see gb. It returns
an object of class GroebnerBasis.
+--------------------------------------------------------------------+
|i1 : R = ZZ/1277[x,y];                                              |
+--------------------------------------------------------------------+
|i2 : I = ideal(x^3 - 2*x*y, x^2*y - 2*y^2 + x);                     |
|                                                                    |
|o2 : Ideal of R                                                     |
+--------------------------------------------------------------------+
|i3 : g = gb I                                                       |
|                                                                    |
|o3 = GroebnerBasis[status: done; S-pairs encountered up to degree 8]|
|                                                                    |
|o3 : GroebnerBasis                                                  |
+--------------------------------------------------------------------+
To get the polynomials in the Groebner basis, use gens
+----------------------+
|i4 : gens g           |
|                      |
|o4 = | y2+638x xy x2 ||
|                      |
|             1      3 |
|o4 : Matrix R  <-- R  |
+----------------------+

How do we control the computation of Groebner bases? If we are working with
homogeneous ideals, we may stop the computation of a Groebner basis after
S-polynomials up to a certain degree have been handled, with the option
DegreeLimit. (This is meaningful only in homogeneous cases.)
+---------------------------------------------------------------------------+
|i5 : R = ZZ/1277[x,y,z,w];                                                 |
+---------------------------------------------------------------------------+
|i6 : I = ideal(x*y-z^2,y^2-w^2);                                           |
|                                                                           |
|o6 : Ideal of R                                                            |
+---------------------------------------------------------------------------+
|i7 : g2 = gb(I,DegreeLimit => 2)                                           |
|                                                                           |
|o7 = GroebnerBasis[status: DegreeLimit; all S-pairs handled up to degree 2]|
|                                                                           |
|o7 : GroebnerBasis                                                         |
+---------------------------------------------------------------------------+
|i8 : gens g2                                                               |
|                                                                           |
|o8 = | y2-w2 xy-z2 |                                                       |
|                                                                           |
|             1      2                                                      |
|o8 : Matrix R  <-- R                                                       |
+---------------------------------------------------------------------------+
The result of the computation is stored internally, so when gb is called with a
higher degree limit, only the additionally required computation is done.
+---------------------------------+
|i9 : g3 = gb(I,DegreeLimit => 3);|
+---------------------------------+
|i10 : gens g3                    |
|                                 |
|o10 = | y2-w2 xy-z2 yz2-xw2 |    |
|                                 |
|              1      3           |
|o10 : Matrix R  <-- R            |
+---------------------------------+

The second computation advances the state of the Groebner basis object started
by the first, and the two results are exactly the same Groebner basis object.
+----------------------------------------------------------------------------+
|i11 : g2                                                                    |
|                                                                            |
|o11 = GroebnerBasis[status: DegreeLimit; all S-pairs handled up to degree 3]|
|                                                                            |
|o11 : GroebnerBasis                                                         |
+----------------------------------------------------------------------------+
|i12 : g2 === g3                                                             |
|                                                                            |
|o12 = true                                                                  |
+----------------------------------------------------------------------------+
The option PairLimit, can be used to stop after a certain
number of S-polynomials have been reduced.  After being reduced, the
S-polynomial is added to the basis, or a syzygy has been found.
+--------------------------------------------------------------------------+
|i13 : I = ideal(x*y-z^2,y^2-w^2)                                          |
|                                                                          |
|                    2   2    2                                            |
|o13 = ideal (x*y - z , y  - w )                                           |
|                                                                          |
|o13 : Ideal of R                                                          |
+--------------------------------------------------------------------------+
|i14 : gb(I,PairLimit => 2)                                                |
|                                                                          |
|o14 = GroebnerBasis[status: PairLimit; all S-pairs handled up to degree 1]|
|                                                                          |
|o14 : GroebnerBasis                                                       |
+--------------------------------------------------------------------------+
|i15 : gb(I,PairLimit => 3)                                                |
|                                                                          |
|o15 = GroebnerBasis[status: PairLimit; all S-pairs handled up to degree 2]|
|                                                                          |
|o15 : GroebnerBasis                                                       |
+--------------------------------------------------------------------------+
The option BasisElementLimit, can be used to stop
after a certain number of basis elements have been found.
+-----------------------------------------------------------------------------+
|i16 : I = ideal(x*y-z^2,y^2-w^2)                                             |
|                                                                             |
|                    2   2    2                                               |
|o16 = ideal (x*y - z , y  - w )                                              |
|                                                                             |
|o16 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i17 : gb(I,BasisElementLimit => 2)                                           |
|                                                                             |
|o17 = GroebnerBasis[status: BasisElementLimit; all S-pairs handled up to     |
|                                                                             |
|o17 : GroebnerBasis                                                          |
|-----------------------------------------------------------------------------|
|degree 1]                                                                    |
+-----------------------------------------------------------------------------+
|i18 : gb(I,BasisElementLimit => 3)                                           |
|                                                                             |
|o18 = GroebnerBasis[status: BasisElementLimit; all S-pairs handled up to     |
|                                                                             |
|o18 : GroebnerBasis                                                          |
|-----------------------------------------------------------------------------|
|degree 2]                                                                    |
+-----------------------------------------------------------------------------+
The option CodimensionLimit, can be used to stop after
the apparent codimension, as gauged by the leading terms of the basis elements
found so far, reaches a certain number.

The option SubringLimit, can be used to stop after a
certain number of basis elements in a subring have been found.  The subring is
determined by the monomial ordering in use.  For Eliminate n the subring
consists of those polynomials not involving any of the first n variables.  For
Lex the subring consists of those polynomials not involving the first variable.
For ProductOrder {m,n,p} the subring consists of those polynomials not
involving the first m variables.

Here is an example where we are satisfied to find one relation from which the
variable t has been eliminated.
+-------------------------------------------------------+
|i19 : R = ZZ/1277[t,F,G,MonomialOrder => Eliminate 1]; |
+-------------------------------------------------------+
|i20 : I = ideal(F - (t^3 + t^2 + 1), G - (t^4 - t))    |
|                                                       |
|                3    2             4                   |
|o20 = ideal (- t  - t  + F - 1, - t  + t + G)          |
|                                                       |
|o20 : Ideal of R                                       |
+-------------------------------------------------------+
|i21 : transpose gens gb (I, SubringLimit => 1)         |
|                                                       |
|o21 = {-4} | F4-7F3-2F2G-4FG2-G3+18F2+3FG+6G2-21F-G+9 ||
|      {-3} | tG2-tF+6tG+5t-F3+3F2+3FG+3G2+G-2         ||
|      {-3} | tFG+tF-4tG-3t+F2-FG-G2-4F-G+3            ||
|      {-3} | tF2-4tF+tG+5t-F2-FG+3F+3G-2              ||
|      {-2} | t2+tF-2t-F-G+1                           ||
|                                                       |
|              5      1                                 |
|o21 : Matrix R  <-- R                                  |
+-------------------------------------------------------+

Sometimes a Groebner basis computation can seem to last forever.  An ongoing
visual display of its progress can be obtained with gbTrace.
+-----------------------------------------------------------------------------+
|i22 : gbTrace = 3                                                            |
|                                                                             |
|o22 = 3                                                                      |
+-----------------------------------------------------------------------------+
|i23 : I = ideal(x*y-z^2,y^2-w^2)                                             |
|                                                                             |
|                    2   2    2                                               |
|o23 = ideal (x*y - z , y  - w )                                              |
|                                                                             |
|                ZZ                                                           |
|o23 : Ideal of ----[x..z, w]                                                 |
|               1277                                                          |
+-----------------------------------------------------------------------------+
|i24 : gb I                                                                   |
|                                                                             |
|   -- registering gb 5 at 0x78c54f6d7700                                     |
|                                                                             |
|   -- [gb]{2}(2)mm{3}(1)m{4}(2)om{5}(1)onumber of (nonminimal) gb elements = |
|   -- number of monomials                = 8                                 |
|   -- #reduction steps = 2                                                   |
|   -- #spairs done = 6                                                       |
|   -- ncalls = 0                                                             |
|   -- nloop = 0                                                              |
|   -- nsaved = 0                                                             |
|   --                                                                        |
|o24 = GroebnerBasis[status: done; S-pairs encountered up to degree 4]        |
|                                                                             |
|o24 : GroebnerBasis                                                          |
|-----------------------------------------------------------------------------|
|4                                                                            |
+-----------------------------------------------------------------------------+
Here is what the tracing symbols indicate.
    {2}   ready to reduce S-polynomials of degree 2
    (0)   there are 0 more S-polynomials (the basis is empty)
     g    the generator yx-z2 has been added to the basis
     g    the generator y2-w2 has been added to the basis
    {3}   ready to reduce S-polynomials of degree 3
    (1)   there is 1 more S-polynomial
     m    the reduced S-polynomial yz2-xw2 has been added to the basis
    {4}   ready to reduce S-polynomials of degree 4
    (2)   there are 2 more S-polynomials
     m    the reduced S-polynomial z4-x2w2 has been added to the basis
     o    an S-polynomial reduced to zero and has been discarded
    {5}   ready to reduce S-polynomials of degree 5
    (1)   there is 1 more S-polynomial
     o    an S-polynomial reduced to zero and has been discarded

Let's turn off the tracing.
+-----------------+
|i25 : gbTrace = 0|
|                 |
|o25 = 0          |
+-----------------+

Each of the operations dealing with Groebner bases may be interrupted or
stopped (by typing CTRL-C).  The computation is continued by re-issuing the
same command.  Alternatively, the command can be issued with the option
StopBeforeComputation => true. It will stop immediately, and return a Groebner
basis object that can be inspected with gens, or syz.
The computation can be continued later.
+-----------------------------------------------------------------------------+
|i26 : R = ZZ/1277[x..z];                                                     |
+-----------------------------------------------------------------------------+
|i27 : I = ideal(x*y+y*z, y^2, x^2);                                          |
|                                                                             |
|o27 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i28 : g = gb(I, StopBeforeComputation => true)                               |
|                                                                             |
|o28 = GroebnerBasis[status: not started; all S-pairs handled up to degree -1]|
|                                                                             |
|o28 : GroebnerBasis                                                          |
+-----------------------------------------------------------------------------+
|i29 : gens g                                                                 |
|                                                                             |
|o29 = 0                                                                      |
|                                                                             |
|              1                                                              |
|o29 : Matrix R  <-- 0                                                        |
+-----------------------------------------------------------------------------+

The function forceGB, can be used to create a Groebner basis
object with a specified Groebner basis.  No computation is performed to check
whether the specified basis is a Groebner basis.

If the Poincare polynomial (or Hilbert function) for a homogeneous submodule M
is known, you can speed up the computation of a Groebner basis by informing the
system.  This is done by storing the Poincare polynomial in M.cache.poincare.

As an example, we compute the Groebner basis of a random ideal, which is almost
certainly a complete intersection, in which case we know the Hilbert function
already.
+-----------------------------------------------------+
|i30 : R = ZZ/1277[a..e];                             |
+-----------------------------------------------------+
|i31 : T = (degreesRing R)_0                          |
|                                                     |
|o31 = T                                              |
|                                                     |
|o31 : ZZ[T]                                          |
+-----------------------------------------------------+
|i32 : f = random(R^1,R^{-3,-3,-5,-6});               |
|                                                     |
|              1      4                               |
|o32 : Matrix R  <-- R                                |
+-----------------------------------------------------+
|i33 : time betti gb f                                |
| -- used 0.193001s (cpu); 0.193736s (thread); 0s (gc)|
|                                                     |
|             0  1                                    |
|o33 = total: 1 53                                    |
|          0: 1  .                                    |
|          1: .  .                                    |
|          2: .  2                                    |
|          3: .  1                                    |
|          4: .  2                                    |
|          5: .  3                                    |
|          6: .  5                                    |
|          7: .  5                                    |
|          8: .  8                                    |
|          9: .  9                                    |
|         10: .  8                                    |
|         11: .  6                                    |
|         12: .  3                                    |
|         13: .  1                                    |
|                                                     |
|o33 : BettiTally                                     |
+-----------------------------------------------------+
The matrix was randomly chosen, and we'd like to use the same one again, but
this time with a hint about the Hilbert function, so first we must erase the
memory of the Groebner basis computed above.
+-------------------------------+
|i34 : remove(f.cache,{false,0})|
+-------------------------------+
Now we provide the hint and compute the Groebner basis anew.
+-----------------------------------------------------------------------------+
|i35 : poincare cokernel f = (1-T^3)*(1-T^3)*(1-T^5)*(1-T^6) -- cache poincare|
|                                                                             |
|            3    5     8     9    12     14    17                            |
|o35 = 1 - 2T  - T  + 2T  + 2T  - T   - 2T   + T                              |
|                                                                             |
|o35 : ZZ[T]                                                                  |
+-----------------------------------------------------------------------------+
|i36 : time betti gb f                                                        |
| -- used 0.00299717s (cpu); 0.00274277s (thread); 0s (gc)                    |
|                                                                             |
|             0  1                                                            |
|o36 = total: 1 53                                                            |
|          0: 1  .                                                            |
|          1: .  .                                                            |
|          2: .  2                                                            |
|          3: .  1                                                            |
|          4: .  2                                                            |
|          5: .  3                                                            |
|          6: .  5                                                            |
|          7: .  5                                                            |
|          8: .  8                                                            |
|          9: .  9                                                            |
|         10: .  8                                                            |
|         11: .  6                                                            |
|         12: .  3                                                            |
|         13: .  1                                                            |
|                                                                             |
|o36 : BettiTally                                                             |
+-----------------------------------------------------------------------------+
The computation turns out to be substantially faster.

normal forms
************

Let $R = k[x_1, ..., x_n]$ be a polynomial ring over a field k, and let $I
\subset{} R$ be an ideal. Let $\{g_1, ..., g_t\}$ be a Groebner basis for $I$.
For any $f \in{} R$, there is a unique `remainder' $r \in{} R$ such that no
term of $r$ is divisible by the leading term of any $g_i$ and such that $f-r$
belongs to $I$. This polynomial $r$ is sometimes called the normal form of $f$.

For an example, consider symmetric polynomials.  The normal form of the
symmetric polynomial f with respect to the ideal I below writes f in terms of
the elementary symmetric functions a,b,c.
+----------------------------------------------------------------+
|i1 : R = QQ[x,y,z,a,b,c,MonomialOrder=>Eliminate 3];            |
+----------------------------------------------------------------+
|i2 : I = ideal(a-(x+y+z), b-(x*y+x*z+y*z), c-x*y*z)             |
|                                                                |
|o2 = ideal (- x - y - z + a, - x*y - x*z - y*z + b, - x*y*z + c)|
|                                                                |
|o2 : Ideal of R                                                 |
+----------------------------------------------------------------+
|i3 : f = x^3+y^3+z^3                                            |
|                                                                |
|      3    3    3                                               |
|o3 = x  + y  + z                                                |
|                                                                |
|o3 : R                                                          |
+----------------------------------------------------------------+
|i4 : f % I                                                      |
|                                                                |
|      3                                                         |
|o4 = a  - 3a*b + 3c                                             |
|                                                                |
|o4 : R                                                          |
+----------------------------------------------------------------+

See also
========

  * Gröbner bases
  * RingElement % Ideal, --
    normal form of ring elements and matrices

elimination of variables
************************

Let's consider the problem of finding the polynomial relation of the three
polynomials $x = s^3+st+1$, $y = t^3+3t^2+t$, and $z = st^3$. The first method
we use is to compute a Groebner basis using an elimination order which
eliminates the variables s,t, and then select those Groebner basis elements
that do not involve the variables s and t.
+-----------------------------------------------------------------------------+
|i1 : R = QQ[s,t,x,y,z, MonomialOrder=>Eliminate 2];                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(x-s^3-s*t-1, y-t^3-3*t^2-t, z-s*t^3)                          |
|                                                                             |
|               3                   3     2               3                   |
|o2 = ideal (- s  - s*t + x - 1, - t  - 3t  - t + y, - s*t  + z)              |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : time leadTerm gens gb I                                                 |
| -- used 0.0972298s (cpu); 0.097228s (thread); 0s (gc)                       |
|                                                                             |
|o3 = | x3y9 5148txy3 108729sxy2z2 sy4z 46644741sxy3z 143sy5 6sxy4            |
|     ------------------------------------------------------------------------|
|     563515116021sx2y3 4374txy2z3 612704350498473090tx2yz3 217458ty4z2       |
|     ------------------------------------------------------------------------|
|     267076255345488270sy3z4 5256861933965245618410txyz6                     |
|     ------------------------------------------------------------------------|
|     259806064190048723110954950tx2z6 281231296878799148310ty3z5             |
|     ------------------------------------------------------------------------|
|     178193459663956600213275sx2yz5 2019525876191508135750450sy2z7           |
|     ------------------------------------------------------------------------|
|     3470026149887950992631901569317758202349494375sx2z8 4004st 12012t2z     |
|     ------------------------------------------------------------------------|
|     3003s2z 9009t2x 14s2y3 t3 4004s3 |                                      |
|                                                                             |
|             1      25                                                       |
|o3 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i4 : G = selectInSubring(1,gens gb I)                                        |
|                                                                             |
|o4 = | x3y9-3x2y9-6x2y8z-3x2y6z3+3xy9-x2y7z+12xy8z+7xy7z2-324x2y5z3+6xy6z3-  |
|     ------------------------------------------------------------------------|
|     y7z3-15xy5z4+3xy3z6-y9+2xy7z-6y8z-7y7z2-1233x2y4z3+648xy5z3-3y6z3+      |
|     ------------------------------------------------------------------------|
|     440xy4z4+15y5z4-70y4z5-405xy2z6-3y3z6+21y2z7-z9-y7z-945x2y3z3+2466xy4z3-|
|     ------------------------------------------------------------------------|
|     324y5z3+1749xy3z4-440y4z4-252y3z5+3393xyz6+405y2z6-385yz7-252x2y2z3+    |
|     ------------------------------------------------------------------------|
|     1890xy3z3-1233y4z3+930xy2z4-1749y3z4-133y2z5-5778xz6-3393yz6+843z7-     |
|     ------------------------------------------------------------------------|
|     27x2yz3+504xy2z3-945y3z3+147xyz4-930y2z4-21yz5+5778z6-x2z3+54xyz3-      |
|     ------------------------------------------------------------------------|
|     252y2z3+7xz4-147yz4-z5+2xz3-27yz3-7z4-z3 |                              |
|                                                                             |
|             1      1                                                        |
|o4 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i5 : ans1 = G_(0,0)                                                          |
|                                                                             |
|      3 9     2 9     2 8      2 6 3       9    2 7         8        7 2     |
|o5 = x y  - 3x y  - 6x y z - 3x y z  + 3x*y  - x y z + 12x*y z + 7x*y z  -   |
|     ------------------------------------------------------------------------|
|         2 5 3       6 3    7 3        5 4       3 6    9       7      8     |
|     324x y z  + 6x*y z  - y z  - 15x*y z  + 3x*y z  - y  + 2x*y z - 6y z -  |
|     ------------------------------------------------------------------------|
|       7 2        2 4 3         5 3     6 3         4 4      5 4      4 5    |
|     7y z  - 1233x y z  + 648x*y z  - 3y z  + 440x*y z  + 15y z  - 70y z  -  |
|     ------------------------------------------------------------------------|
|           2 6     3 6      2 7    9    7        2 3 3          4 3       5 3|
|     405x*y z  - 3y z  + 21y z  - z  - y z - 945x y z  + 2466x*y z  - 324y z |
|     ------------------------------------------------------------------------|
|              3 4       4 4       3 5            6       2 6         7       |
|     + 1749x*y z  - 440y z  - 252y z  + 3393x*y*z  + 405y z  - 385y*z  -     |
|     ------------------------------------------------------------------------|
|         2 2 3          3 3        4 3         2 4        3 4       2 5      |
|     252x y z  + 1890x*y z  - 1233y z  + 930x*y z  - 1749y z  - 133y z  -    |
|     ------------------------------------------------------------------------|
|            6          6       7      2   3         2 3       3 3           4|
|     5778x*z  - 3393y*z  + 843z  - 27x y*z  + 504x*y z  - 945y z  + 147x*y*z |
|     ------------------------------------------------------------------------|
|           2 4        5        6    2 3          3       2 3       4         |
|     - 930y z  - 21y*z  + 5778z  - x z  + 54x*y*z  - 252y z  + 7x*z  -       |
|     ------------------------------------------------------------------------|
|           4    5       3        3     4    3                                |
|     147y*z  - z  + 2x*z  - 27y*z  - 7z  - z                                 |
|                                                                             |
|o5 : R                                                                       |
+-----------------------------------------------------------------------------+

This method (with some optimizations incorporated) is provided by the
eliminate (Elimination), function.
+-----------------------------------------------------------------------------+
|i6 : R = QQ[x,y,z,s,t];                                                      |
+-----------------------------------------------------------------------------+
|i7 : I = ideal(x-s^3-s*t-1, y-t^3-3*t^2-t, z-s*t^3)                          |
|                                                                             |
|               3                   3     2               3                   |
|o7 = ideal (- s  - s*t + x - 1, - t  - 3t  + y - t, - s*t  + z)              |
|                                                                             |
|o7 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i8 : time G = eliminate(I,{s,t})                                             |
| -- used 0.216474s (cpu); 0.131255s (thread); 0s (gc)                        |
|                                                                             |
|            3 9     2 9     2 8      2 6 3       9    2 7         8          |
|o8 = ideal(x y  - 3x y  - 6x y z - 3x y z  + 3x*y  - x y z + 12x*y z +       |
|     ------------------------------------------------------------------------|
|         7 2       2 5 3       6 3    7 3        5 4       3 6    9       7  |
|     7x*y z  - 324x y z  + 6x*y z  - y z  - 15x*y z  + 3x*y z  - y  + 2x*y z |
|     ------------------------------------------------------------------------|
|         8      7 2        2 4 3         5 3     6 3         4 4      5 4    |
|     - 6y z - 7y z  - 1233x y z  + 648x*y z  - 3y z  + 440x*y z  + 15y z  -  |
|     ------------------------------------------------------------------------|
|        4 5         2 6     3 6      2 7    9    7        2 3 3          4 3 |
|     70y z  - 405x*y z  - 3y z  + 21y z  - z  - y z - 945x y z  + 2466x*y z  |
|     ------------------------------------------------------------------------|
|           5 3          3 4       4 4       3 5            6       2 6       |
|     - 324y z  + 1749x*y z  - 440y z  - 252y z  + 3393x*y*z  + 405y z  -     |
|     ------------------------------------------------------------------------|
|           7       2 2 3          3 3        4 3         2 4        3 4      |
|     385y*z  - 252x y z  + 1890x*y z  - 1233y z  + 930x*y z  - 1749y z  -    |
|     ------------------------------------------------------------------------|
|         2 5          6          6       7      2   3         2 3       3 3  |
|     133y z  - 5778x*z  - 3393y*z  + 843z  - 27x y*z  + 504x*y z  - 945y z  +|
|     ------------------------------------------------------------------------|
|             4       2 4        5        6    2 3          3       2 3       |
|     147x*y*z  - 930y z  - 21y*z  + 5778z  - x z  + 54x*y*z  - 252y z  +     |
|     ------------------------------------------------------------------------|
|         4         4    5       3        3     4    3                        |
|     7x*z  - 147y*z  - z  + 2x*z  - 27y*z  - 7z  - z )                       |
|                                                                             |
|o8 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i9 : ans2 = G_0                                                              |
|                                                                             |
|      3 9     2 9     2 8      2 6 3       9    2 7         8        7 2     |
|o9 = x y  - 3x y  - 6x y z - 3x y z  + 3x*y  - x y z + 12x*y z + 7x*y z  -   |
|     ------------------------------------------------------------------------|
|         2 5 3       6 3    7 3        5 4       3 6    9       7      8     |
|     324x y z  + 6x*y z  - y z  - 15x*y z  + 3x*y z  - y  + 2x*y z - 6y z -  |
|     ------------------------------------------------------------------------|
|       7 2        2 4 3         5 3     6 3         4 4      5 4      4 5    |
|     7y z  - 1233x y z  + 648x*y z  - 3y z  + 440x*y z  + 15y z  - 70y z  -  |
|     ------------------------------------------------------------------------|
|           2 6     3 6      2 7    9    7        2 3 3          4 3       5 3|
|     405x*y z  - 3y z  + 21y z  - z  - y z - 945x y z  + 2466x*y z  - 324y z |
|     ------------------------------------------------------------------------|
|              3 4       4 4       3 5            6       2 6         7       |
|     + 1749x*y z  - 440y z  - 252y z  + 3393x*y*z  + 405y z  - 385y*z  -     |
|     ------------------------------------------------------------------------|
|         2 2 3          3 3        4 3         2 4        3 4       2 5      |
|     252x y z  + 1890x*y z  - 1233y z  + 930x*y z  - 1749y z  - 133y z  -    |
|     ------------------------------------------------------------------------|
|            6          6       7      2   3         2 3       3 3           4|
|     5778x*z  - 3393y*z  + 843z  - 27x y*z  + 504x*y z  - 945y z  + 147x*y*z |
|     ------------------------------------------------------------------------|
|           2 4        5        6    2 3          3       2 3       4         |
|     - 930y z  - 21y*z  + 5778z  - x z  + 54x*y*z  - 252y z  + 7x*z  -       |
|     ------------------------------------------------------------------------|
|           4    5       3        3     4    3                                |
|     147y*z  - z  + 2x*z  - 27y*z  - 7z  - z                                 |
|                                                                             |
|o9 : R                                                                       |
+-----------------------------------------------------------------------------+
Sometimes giving the variables different degrees will speed up the
computations.  Here, we set the degrees of x, y, and z to be the total degrees.
+-----------------------------------------------------------------------------+
|i10 : R1 = QQ[x,y,z,s,t, Degrees=>{3,3,4,1,1}];                              |
+-----------------------------------------------------------------------------+
|i11 : I1 = substitute(I,R1);                                                 |
|                                                                             |
|o11 : Ideal of R1                                                            |
+-----------------------------------------------------------------------------+
|i12 : time G = eliminate(I1,{s,t})                                           |
| -- used 0.0254705s (cpu); 0.0254713s (thread); 0s (gc)                      |
|                                                                             |
|             3 9     2 6 3       3 6    9     2 8         5 4      2 7       |
|o12 = ideal(x y  - 3x y z  + 3x*y z  - z  - 6x y z - 15x*y z  + 21y z  -     |
|      -----------------------------------------------------------------------|
|        2 9       2 5 3       6 3    7 3         2 6     3 6       7 2       |
|      3x y  - 324x y z  + 6x*y z  - y z  - 405x*y z  - 3y z  + 7x*y z  -     |
|      -----------------------------------------------------------------------|
|         4 5    2 7         8          4 4      5 4         7       9        |
|      70y z  - x y z + 12x*y z + 440x*y z  + 15y z  - 385y*z  + 3x*y  -      |
|      -----------------------------------------------------------------------|
|           2 4 3         5 3     6 3            6       2 6     7 2       3 5|
|      1233x y z  + 648x*y z  - 3y z  + 3393x*y*z  + 405y z  - 7y z  - 252y z |
|      -----------------------------------------------------------------------|
|            7      8           3 4       4 4       7    9       2 3 3        |
|      + 2x*y z - 6y z + 1749x*y z  - 440y z  + 843z  - y  - 945x y z  +      |
|      -----------------------------------------------------------------------|
|             4 3       5 3          6          6       2 5    7          2 4 |
|      2466x*y z  - 324y z  - 5778x*z  - 3393y*z  - 133y z  - y z + 930x*y z  |
|      -----------------------------------------------------------------------|
|             3 4       2 2 3          3 3        4 3        6        5       |
|      - 1749y z  - 252x y z  + 1890x*y z  - 1233y z  + 5778z  - 21y*z  +     |
|      -----------------------------------------------------------------------|
|              4       2 4      2   3         2 3       3 3    5       4      |
|      147x*y*z  - 930y z  - 27x y*z  + 504x*y z  - 945y z  - z  + 7x*z  -    |
|      -----------------------------------------------------------------------|
|            4    2 3          3       2 3     4       3        3    3        |
|      147y*z  - x z  + 54x*y*z  - 252y z  - 7z  + 2x*z  - 27y*z  - z )       |
|                                                                             |
|o12 : Ideal of R1                                                            |
+-----------------------------------------------------------------------------+
|i13 : ans3 = G_0                                                             |
|                                                                             |
|       3 9     2 6 3       3 6    9     2 8         5 4      2 7     2 9     |
|o13 = x y  - 3x y z  + 3x*y z  - z  - 6x y z - 15x*y z  + 21y z  - 3x y  -   |
|      -----------------------------------------------------------------------|
|          2 5 3       6 3    7 3         2 6     3 6       7 2      4 5      |
|      324x y z  + 6x*y z  - y z  - 405x*y z  - 3y z  + 7x*y z  - 70y z  -    |
|      -----------------------------------------------------------------------|
|       2 7         8          4 4      5 4         7       9        2 4 3    |
|      x y z + 12x*y z + 440x*y z  + 15y z  - 385y*z  + 3x*y  - 1233x y z  +  |
|      -----------------------------------------------------------------------|
|            5 3     6 3            6       2 6     7 2       3 5       7     |
|      648x*y z  - 3y z  + 3393x*y*z  + 405y z  - 7y z  - 252y z  + 2x*y z -  |
|      -----------------------------------------------------------------------|
|        8           3 4       4 4       7    9       2 3 3          4 3      |
|      6y z + 1749x*y z  - 440y z  + 843z  - y  - 945x y z  + 2466x*y z  -    |
|      -----------------------------------------------------------------------|
|          5 3          6          6       2 5    7          2 4        3 4   |
|      324y z  - 5778x*z  - 3393y*z  - 133y z  - y z + 930x*y z  - 1749y z  - |
|      -----------------------------------------------------------------------|
|          2 2 3          3 3        4 3        6        5           4        |
|      252x y z  + 1890x*y z  - 1233y z  + 5778z  - 21y*z  + 147x*y*z  -      |
|      -----------------------------------------------------------------------|
|          2 4      2   3         2 3       3 3    5       4         4    2 3 |
|      930y z  - 27x y*z  + 504x*y z  - 945y z  - z  + 7x*z  - 147y*z  - x z  |
|      -----------------------------------------------------------------------|
|               3       2 3     4       3        3    3                       |
|      + 54x*y*z  - 252y z  - 7z  + 2x*z  - 27y*z  - z                        |
|                                                                             |
|o13 : R1                                                                     |
+-----------------------------------------------------------------------------+

Another approach is to create the ring map $F : k[x,y,z] \rightarrow{} k[s,t]$,
and find its kernel.
+-----------------------------------------------------------------------------+
|i14 : A = QQ[s,t];                                                           |
+-----------------------------------------------------------------------------+
|i15 : B = QQ[x,y,z];                                                         |
+-----------------------------------------------------------------------------+
|i16 : F = map(A,B,{s^3+s*t+1, t^3+3*t^2+t, s*t^3})                           |
|                                                                             |
|                   3             3     2         3                           |
|o16 = map (A, B, {s  + s*t + 1, t  + 3t  + t, s*t })                         |
|                                                                             |
|o16 : RingMap A <-- B                                                        |
+-----------------------------------------------------------------------------+
|i17 : time G = kernel F                                                      |
| -- used 0.206172s (cpu); 0.108555s (thread); 0s (gc)                        |
|                                                                             |
|             3 9     2 9     2 8      2 6 3       9    2 7         8         |
|o17 = ideal(x y  - 3x y  - 6x y z - 3x y z  + 3x*y  - x y z + 12x*y z +      |
|      -----------------------------------------------------------------------|
|          7 2       2 5 3       6 3    7 3        5 4       3 6    9       7 |
|      7x*y z  - 324x y z  + 6x*y z  - y z  - 15x*y z  + 3x*y z  - y  + 2x*y z|
|      -----------------------------------------------------------------------|
|          8      7 2        2 4 3         5 3     6 3         4 4      5 4   |
|      - 6y z - 7y z  - 1233x y z  + 648x*y z  - 3y z  + 440x*y z  + 15y z  - |
|      -----------------------------------------------------------------------|
|         4 5         2 6     3 6      2 7    9    7        2 3 3          4 3|
|      70y z  - 405x*y z  - 3y z  + 21y z  - z  - y z - 945x y z  + 2466x*y z |
|      -----------------------------------------------------------------------|
|            5 3          3 4       4 4       3 5            6       2 6      |
|      - 324y z  + 1749x*y z  - 440y z  - 252y z  + 3393x*y*z  + 405y z  -    |
|      -----------------------------------------------------------------------|
|            7       2 2 3          3 3        4 3         2 4        3 4     |
|      385y*z  - 252x y z  + 1890x*y z  - 1233y z  + 930x*y z  - 1749y z  -   |
|      -----------------------------------------------------------------------|
|          2 5          6          6       7      2   3         2 3       3 3 |
|      133y z  - 5778x*z  - 3393y*z  + 843z  - 27x y*z  + 504x*y z  - 945y z  |
|      -----------------------------------------------------------------------|
|                4       2 4        5        6    2 3          3       2 3    |
|      + 147x*y*z  - 930y z  - 21y*z  + 5778z  - x z  + 54x*y*z  - 252y z  +  |
|      -----------------------------------------------------------------------|
|          4         4    5       3        3     4    3                       |
|      7x*z  - 147y*z  - z  + 2x*z  - 27y*z  - 7z  - z )                      |
|                                                                             |
|o17 : Ideal of B                                                             |
+-----------------------------------------------------------------------------+
|i18 : ans4 = G_0                                                             |
|                                                                             |
|       3 9     2 9     2 8      2 6 3       9    2 7         8        7 2    |
|o18 = x y  - 3x y  - 6x y z - 3x y z  + 3x*y  - x y z + 12x*y z + 7x*y z  -  |
|      -----------------------------------------------------------------------|
|          2 5 3       6 3    7 3        5 4       3 6    9       7      8    |
|      324x y z  + 6x*y z  - y z  - 15x*y z  + 3x*y z  - y  + 2x*y z - 6y z - |
|      -----------------------------------------------------------------------|
|        7 2        2 4 3         5 3     6 3         4 4      5 4      4 5   |
|      7y z  - 1233x y z  + 648x*y z  - 3y z  + 440x*y z  + 15y z  - 70y z  - |
|      -----------------------------------------------------------------------|
|            2 6     3 6      2 7    9    7        2 3 3          4 3         |
|      405x*y z  - 3y z  + 21y z  - z  - y z - 945x y z  + 2466x*y z  -       |
|      -----------------------------------------------------------------------|
|          5 3          3 4       4 4       3 5            6       2 6        |
|      324y z  + 1749x*y z  - 440y z  - 252y z  + 3393x*y*z  + 405y z  -      |
|      -----------------------------------------------------------------------|
|            7       2 2 3          3 3        4 3         2 4        3 4     |
|      385y*z  - 252x y z  + 1890x*y z  - 1233y z  + 930x*y z  - 1749y z  -   |
|      -----------------------------------------------------------------------|
|          2 5          6          6       7      2   3         2 3       3 3 |
|      133y z  - 5778x*z  - 3393y*z  + 843z  - 27x y*z  + 504x*y z  - 945y z  |
|      -----------------------------------------------------------------------|
|                4       2 4        5        6    2 3          3       2 3    |
|      + 147x*y*z  - 930y z  - 21y*z  + 5778z  - x z  + 54x*y*z  - 252y z  +  |
|      -----------------------------------------------------------------------|
|          4         4    5       3        3     4    3                       |
|      7x*z  - 147y*z  - z  + 2x*z  - 27y*z  - 7z  - z                        |
|                                                                             |
|o18 : B                                                                      |
+-----------------------------------------------------------------------------+
This appears to be much faster than the first two methods.

Finally, we may use resultants to find elements of the ideal I which do not
involve the variables s and t.
+-----------------------------------------------------------------------------+
|i19 : use ring I                                                             |
|                                                                             |
|o19 = R                                                                      |
|                                                                             |
|o19 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i20 : time f1 = resultant(I_0,I_2,s)                                         |
| -- used 0.00125213s (cpu); 0.00125229s (thread); 0s (gc)                    |
|                                                                             |
|         9    9      7    3                                                  |
|o20 = x*t  - t  - z*t  - z                                                   |
|                                                                             |
|o20 : R                                                                      |
+-----------------------------------------------------------------------------+
|i21 : time f2 = resultant(I_1,f1,t)                                          |
| -- used 0.029882s (cpu); 0.0298849s (thread); 0s (gc)                       |
|                                                                             |
|         3 9     2 9     2 8      2 6 3       9    2 7         8        7 2  |
|o21 = - x y  + 3x y  + 6x y z + 3x y z  - 3x*y  + x y z - 12x*y z - 7x*y z  +|
|      -----------------------------------------------------------------------|
|          2 5 3       6 3    7 3        5 4       3 6    9       7      8    |
|      324x y z  - 6x*y z  + y z  + 15x*y z  - 3x*y z  + y  - 2x*y z + 6y z + |
|      -----------------------------------------------------------------------|
|        7 2        2 4 3         5 3     6 3         4 4      5 4      4 5   |
|      7y z  + 1233x y z  - 648x*y z  + 3y z  - 440x*y z  - 15y z  + 70y z  + |
|      -----------------------------------------------------------------------|
|            2 6     3 6      2 7    9    7        2 3 3          4 3         |
|      405x*y z  + 3y z  - 21y z  + z  + y z + 945x y z  - 2466x*y z  +       |
|      -----------------------------------------------------------------------|
|          5 3          3 4       4 4       3 5            6       2 6        |
|      324y z  - 1749x*y z  + 440y z  + 252y z  - 3393x*y*z  - 405y z  +      |
|      -----------------------------------------------------------------------|
|            7       2 2 3          3 3        4 3         2 4        3 4     |
|      385y*z  + 252x y z  - 1890x*y z  + 1233y z  - 930x*y z  + 1749y z  +   |
|      -----------------------------------------------------------------------|
|          2 5          6          6       7      2   3         2 3       3 3 |
|      133y z  + 5778x*z  + 3393y*z  - 843z  + 27x y*z  - 504x*y z  + 945y z  |
|      -----------------------------------------------------------------------|
|                4       2 4        5        6    2 3          3       2 3    |
|      - 147x*y*z  + 930y z  + 21y*z  - 5778z  + x z  - 54x*y*z  + 252y z  -  |
|      -----------------------------------------------------------------------|
|          4         4    5       3        3     4    3                       |
|      7x*z  + 147y*z  + z  - 2x*z  + 27y*z  + 7z  + z                        |
|                                                                             |
|o21 : R                                                                      |
+-----------------------------------------------------------------------------+
|i22 : ans5 = -f2                                                             |
|                                                                             |
|       3 9     2 9     2 8      2 6 3       9    2 7         8        7 2    |
|o22 = x y  - 3x y  - 6x y z - 3x y z  + 3x*y  - x y z + 12x*y z + 7x*y z  -  |
|      -----------------------------------------------------------------------|
|          2 5 3       6 3    7 3        5 4       3 6    9       7      8    |
|      324x y z  + 6x*y z  - y z  - 15x*y z  + 3x*y z  - y  + 2x*y z - 6y z - |
|      -----------------------------------------------------------------------|
|        7 2        2 4 3         5 3     6 3         4 4      5 4      4 5   |
|      7y z  - 1233x y z  + 648x*y z  - 3y z  + 440x*y z  + 15y z  - 70y z  - |
|      -----------------------------------------------------------------------|
|            2 6     3 6      2 7    9    7        2 3 3          4 3         |
|      405x*y z  - 3y z  + 21y z  - z  - y z - 945x y z  + 2466x*y z  -       |
|      -----------------------------------------------------------------------|
|          5 3          3 4       4 4       3 5            6       2 6        |
|      324y z  + 1749x*y z  - 440y z  - 252y z  + 3393x*y*z  + 405y z  -      |
|      -----------------------------------------------------------------------|
|            7       2 2 3          3 3        4 3         2 4        3 4     |
|      385y*z  - 252x y z  + 1890x*y z  - 1233y z  + 930x*y z  - 1749y z  -   |
|      -----------------------------------------------------------------------|
|          2 5          6          6       7      2   3         2 3       3 3 |
|      133y z  - 5778x*z  - 3393y*z  + 843z  - 27x y*z  + 504x*y z  - 945y z  |
|      -----------------------------------------------------------------------|
|                4       2 4        5        6    2 3          3       2 3    |
|      + 147x*y*z  - 930y z  - 21y*z  + 5778z  - x z  + 54x*y*z  - 252y z  +  |
|      -----------------------------------------------------------------------|
|          4         4    5       3        3     4    3                       |
|      7x*z  - 147y*z  - z  + 2x*z  - 27y*z  - 7z  - z                        |
|                                                                             |
|o22 : R                                                                      |
+-----------------------------------------------------------------------------+
This is the fastest method in this case.

These answers should all be the same (with the possible exception of the last),
but are they?  They live in different rings, so we cannot compare them
directly.  Instead, let's move them to the ring B, and then remove duplicates.
+-----------------------------------------+
|i23 : L = {ans1,ans2,ans3,ans4,ans5};    |
+-----------------------------------------+
|i24 : L = apply(L, f -> substitute(f,B));|
+-----------------------------------------+
|i25 : length unique L                    |
|                                         |
|o25 = 1                                  |
+-----------------------------------------+
They are all the same!

See also
========

  * selectInSubring -- select columns in a subring
  * RingMap -- the class of all ring maps
  * eliminate (Elimination)
  * resultant (Elimination)
  * apply -- apply a function to each element
  * unique -- eliminate duplicates from a list
  * length -- length of an object

combinatorial functions
***********************

  * binomial -- binomial coefficient
  * compositions -- list the compositions of an integer
  * partitions -- list the partitions of an integer
  * random -- get a random object
  * subsets -- produce the subsets of a set or list
  * tally -- tally the elements of a list, sequence, array, or
    string

The Macaulay2 language
**********************

The Macaulay2 language is a simple yet powerful interpreted language.  Every
object has a type, such as Type, ZZ, (integer), see
String, HashTable, Ring, Matrix,
see Function, etc.  User defined variables may hold
values of any type.

The Macaulay2 language is based on expressions, which, generally speaking, are
used to create new objects from old ones. Other computer languages have things
called statements, but Macaulay2 does not. Other computer languages use newline
characters and even indentation to indicate separate and nesting of statements,
but Macaulay2 does not. Expressions in Macaulay2 include function calls,
control structures (e.g., see for, and while, loops),
function definitions, and operator expressions.  Every expression returns an
object, although the basic object null, is often returned if the
expression is being used only to produce some side effect.

There is special syntax for creating and accessing strings, lists, sequences,
and hashtables.  These are the key data types underlying many new types.  The
Macaulay2 engine implements rings, ring elements, and matrices, as instances of
low-level types, and various high-level types, visible to the user, are based
on them.  Examples include Ring, RingElement,
Matrix, Ideal, RingMap,
Module, and ChainComplex.

The user can create new types of higher level mathematical objects, whose types
form a hierarchy that facilitates the installation and use of appropriate
methods for computing with them.

basic data types

expressions

functions

classes and types

input and output

packages

parallel programming

system facilities

debugging

variables
*********

Valid names for symbols may be constructed using letters, digits, and the
apostrophe, and should not begin with a digit.
+-----------+
|i1 : x     |
|           |
|o1 = x     |
|           |
|o1 : Symbol|
+-----------+
|i2 : q0r55 |
|           |
|o2 = q0r55 |
|           |
|o2 : Symbol|
+-----------+
|i3 : f'    |
|           |
|o3 = f'    |
|           |
|o3 : Symbol|
+-----------+
Some symbols have preassigned meanings and values.  For example, symbols
consisting of the letter o followed by a number are used to store output
values.
+-----------+
|i4 : o2    |
|           |
|o4 = q0r55 |
|           |
|o4 : Symbol|
+-----------+
Other symbols refer to functions built into Macaulay2 that provide much of its
functionality.

Sometimes, one wants the symbol, rather than the particular value it happens to
have at the moment.  For example after setting the value of x to 5, the value
of the variable x is no longer the symbol x. Use symbol, to
recover the symbol itself.
+-------------+
|i5 : x=5     |
|             |
|o5 = 5       |
+-------------+
|i6 : x       |
|             |
|o6 = 5       |
+-------------+
|i7 : symbol x|
|             |
|o7 = x       |
|             |
|o7 : Symbol  |
+-------------+

See also
========

  * symbol -- get a symbol
  * local -- get a local symbol
  * global -- get a global symbol
  * listUserSymbols -- display the user's symbols
  * clearOutput -- forget output values
  * clearAll -- forget everything
  * Symbol -- the class of all symbols

valid names
***********

Valid names for symbols may be constructed using letters, digits, and the
apostrophe, and should not begin with a digit.
+-----------+
|i1 : x     |
|           |
|o1 = x     |
|           |
|o1 : Symbol|
+-----------+
|i2 : q0r55 |
|           |
|o2 = q0r55 |
|           |
|o2 : Symbol|
+-----------+
|i3 : f'    |
|           |
|o3 = f'    |
|           |
|o3 : Symbol|
+-----------+
Some symbols have preassigned meanings and values.  For example, symbols
consisting of the letter o followed by a number are used to store output
values.
+-----------+
|i4 : o2    |
|           |
|o4 = q0r55 |
|           |
|o4 : Symbol|
+-----------+
Other symbols refer to functions built into Macaulay2 that provide much of its
functionality, as we will learn.

The class of all symbols is Symbol.

assigning values
****************

Use an equal sign to assign values to variables.
+----------------+
|i1 : x = "abcde"|
|                |
|o1 = abcde      |
+----------------+
|i2 : x          |
|                |
|o2 = abcde      |
+----------------+
Before assignment, any reference to a variable provides the symbol with that
name.  After assignment, the assigned value is provided. The variable created
is global, in the sense that any code placed elsewhere that contains a
reference to a variable called x will refer to the one we just set.

It is important to distinguish between a symbol and its value.  The initial
value of a global symbol is the symbol itself, and the initial value of a local
variable is null.  One possibility for confusion comes from the
possibility of having a symbol whose value is another symbol; it's even more
confusing if the two symbols have the same name but different scopes, for
example, if one of them is global and the other is local.
+------------+
|i3 : y      |
|            |
|o3 = y      |
|            |
|o3 : Symbol |
+------------+
|i4 : y = z  |
|            |
|o4 = z      |
|            |
|o4 : Symbol |
+------------+
|i5 : y      |
|            |
|o5 = z      |
|            |
|o5 : Symbol |
+------------+
|i6 : z = 444|
|            |
|o6 = 444    |
+------------+
|i7 : z      |
|            |
|o7 = 444    |
+------------+
|i8 : y      |
|            |
|o8 = z      |
|            |
|o8 : Symbol |
+------------+
In the example above, the final value of y is the symbol z, even though the
symbol z has acquired a value of its own.  The function value can be used to
get the value of a symbol.
+------------+
|i9 : value y|
|            |
|o9 = 444    |
+------------+
The operator <-, can be used to set the value of a symbol.  This
operator differs from =, in that the symbol or expression on the left
hand side is evaluated.
+--------------+
|i10 : y <- 555|
|              |
|o10 = 555     |
+--------------+
|i11 : y       |
|              |
|o11 = z       |
|              |
|o11 : Symbol  |
+--------------+
|i12 : z       |
|              |
|o12 = 555     |
+--------------+
|i13 : y = 666 |
|              |
|o13 = 666     |
+--------------+
|i14 : y       |
|              |
|o14 = 666     |
+--------------+
|i15 : z       |
|              |
|o15 = 555     |
+--------------+
One reason the user needs to understand this concept is that assignments with
the operator <-, are occasionally done on the user's behalf by bits
of code already in the system, for example, when creating a polynomial ring the
prospective variables are given new values that are the generators of the
polynomial ring.

See also
========

  * GlobalAssignHook -- hook for assignment to global
    variables
  * GlobalReleaseHook

local variables in a file
*************************

There is a way to construct variables that can be used within a given source
file, and are invisible to code placed in other files.  We use _colon_=,
for this.  Assume the code below is placed in a file, and that the file
is loaded with the load, command.
+------------+
|i1 : ff := 5|
|            |
|o1 = 5      |
+------------+
|i2 : ff     |
|            |
|o2 = 5      |
+------------+
The variable above is a local one.  Its value is not available to code in other
files.

Assume the code above is entered directly by the user into Macaulay2.  Then the
variable is still a local one and is not available to code previously loaded or
to functions previously defined, but it will be available to code loaded
subsequently.  We illustrate this below with the variable j.

+--------------------+
|i3 : j              |
|                    |
|o3 = j              |
|                    |
|o3 : Symbol         |
+--------------------+
|i4 : h = () -> j    |
|                    |
|o4 = h              |
|                    |
|o4 : FunctionClosure|
+--------------------+
|i5 : h()            |
|                    |
|o5 = j              |
|                    |
|o5 : Symbol         |
+--------------------+
|i6 : j = 444        |
|                    |
|o6 = 444            |
+--------------------+
|i7 : h()            |
|                    |
|o7 = 444            |
+--------------------+
|i8 : j := 555       |
|                    |
|o8 = 555            |
+--------------------+
|i9 : h()            |
|                    |
|o9 = 444            |
+--------------------+
|i10 : j             |
|                    |
|o10 = 555           |
+--------------------+

viewing the symbols defined so far
**********************************

After using Macaulay2 for a while, you may have stored data in several
variables.  The system also stores output values for you in output variables.
You may wish to free the memory space occupied by that data, or you may simply
wish to remind yourself where you stored a previously computed value.

We may use the command listUserSymbols, to obtain a list
of the user's symbols encountered so far.
+-----------------------------------------------------------------------------+
|i1 : ff = 20:4; h = true; kk                                                 |
|                                                                             |
|o3 = kk                                                                      |
|                                                                             |
|o3 : Symbol                                                                  |
+-----------------------------------------------------------------------------+
|i4 : listUserSymbols                                                         |
|                                                                             |
|o4 = symbol  class     value                                                 |
|     ------  -----     -----                                                 |
|     h       Boolean   true                                                  |
|     ff      Sequence  (4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,   |
|-----------------------------------------------------------------------------|
|     location of symbol                                                      |
|     ------------------                                                      |
|     currentString:1:11-1:12                                                 |
|4,.  currentString:1:0-1:2                                                   |
+-----------------------------------------------------------------------------+
The symbols are listed in chronological order, and the type of value stored
under it is displayed.

We can clear the output symbols with clearOutput.
+-----------------------------------------------------------------------------+
|i5 : clearOutput                                                             |
+-----------------------------------------------------------------------------+
|i6 : listUserSymbols                                                         |
|                                                                             |
|o6 = symbol  class     value                                                 |
|     ------  -----     -----                                                 |
|     h       Boolean   true                                                  |
|     ff      Sequence  (4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,   |
|-----------------------------------------------------------------------------|
|     location of symbol                                                      |
|     ------------------                                                      |
|     currentString:1:11-1:12                                                 |
|4,.  currentString:1:0-1:2                                                   |
+-----------------------------------------------------------------------------+
We can clear all the symbols with clearAll.
+---------------------------------------------+
|i7 : clearAll                                |
+---------------------------------------------+
|i8 : listUserSymbols                         |
|                                             |
|o8 = symbol  class  value  location of symbol|
|     ------  -----  -----  ------------------|
+---------------------------------------------+

subscripted variables
*********************

It is common in mathematics to use subscripted variables.  We use the
underscore to represent subscripts.  If we haven't assigned a value to x we may
simply start using it as a subscripted variable.  The subscripts can be
anything.
+--------------------+
|i1 : x              |
|                    |
|o1 = x              |
|                    |
|o1 : Symbol         |
+--------------------+
|i2 : x_4            |
|                    |
|o2 = x              |
|      4             |
|                    |
|o2 : IndexedVariable|
+--------------------+
|i3 : x_(2,3)        |
|                    |
|o3 = x              |
|      2,3           |
|                    |
|o3 : IndexedVariable|
+--------------------+
The .., operator knows what to do with subscripted variables.
+------------------------------------------------------------+
|i4 : x_10 .. x_20                                           |
|                                                            |
|o4 = (x  , x  , x  , x  , x  , x  , x  , x  , x  , x  , x  )|
|       10   11   12   13   14   15   16   17   18   19   20 |
|                                                            |
|o4 : Sequence                                               |
+------------------------------------------------------------+
|i5 : x_(1,1) .. x_(2,3)                                     |
|                                                            |
|o5 = (x   , x   , x   , x   , x   , x   )                   |
|       1,1   1,2   1,3   2,1   2,2   2,3                    |
|                                                            |
|o5 : Sequence                                               |
+------------------------------------------------------------+
Values can be assigned to these variables with =.
+----------------+
|i6 : y_10 = 555;|
+----------------+
|i7 : y_10       |
|                |
|o7 = 555        |
+----------------+

See also
========

  * IndexedVariable -- the class of all indexed
    variables

numbered variables
******************

One way to get many variables suitable for use as indeterminates in a
polynomial ring is with the function vars.  It converts a list or
sequence of integers into symbols.  It prefers to hand out symbols whose name
consists of a single letter, but there are only 52 such symbols, so it also
uses symbols such as x55 and X44.
+-------------------------------------------------+
|i1 : vars (0 .. 9,40,100,-100)                   |
|                                                 |
|o1 = (a, b, c, d, e, f, g, h, i, j, O, x48, X100)|
|                                                 |
|o1 : Sequence                                    |
+-------------------------------------------------+
These variables can be used to make polynomial rings.
+----------------------+
|i2 : ZZ[vars(0 .. 10)]|
|                      |
|o2 = ZZ[a..k]         |
|                      |
|o2 : PolynomialRing   |
+----------------------+

augmented assignment
********************

Most binary operators, have an associated augmented assignment
(see https://en.wikipedia.org/wiki/augmented_assignment ) operator that
modifies the given object using the corresponding binary operator.
Essentially, x OP= y is equivalent to x = x OP y.

+-----------+
|i1 : x = 2 |
|           |
|o1 = 2     |
+-----------+
|i2 : x += 3|
|           |
|o2 = 5     |
+-----------+
|i3 : x -= 4|
|           |
|o3 = 1     |
+-----------+
|i4 : x *= 5|
|           |
|o4 = 5     |
+-----------+
|i5 : x /= 6|
|           |
|     5     |
|o5 = -     |
|     6     |
|           |
|o5 : QQ    |
+-----------+

The following augmented assignment operators are supported.

+-----------------------------------------------------------------------------+
|i6 : importFrom(Core, "augmentedAssignmentOperators");                       |
+-----------------------------------------------------------------------------+
|i7 : augmentedAssignmentOperators                                            |
|                                                                             |
|o7 = (<<=, >>=, ||=, <==>=, |-=, ??=, ==>=, ===>=, |=, ^^=, &=, ..=, ..<=,   |
|     ------------------------------------------------------------------------|
|     -=, +=, ++=, **=, *=, \\=, /=, \=, %=, //=, @=, @@=, |_=, ^=, _=, ^**=) |
|                                                                             |
|o7 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * installing augmented assignment methods

numeric types
*************

Integers and rational numbers
-----------------------------

In Macaulay2, integers and rational numbers have any number of digits (up to
memory limits at least).
+-----------------------------------------+
|i1 : 21672378126371263123123             |
|                                         |
|o1 = 21672378126371263123123             |
+-----------------------------------------+
|i2 : 3748568762746238746278/5876584978947|
|                                         |
|     1249522920915412915426              |
|o2 = ----------------------              |
|          1958861659649                  |
|                                         |
|o2 : QQ                                  |
+-----------------------------------------+
Integers are elements of the ring ZZ, of integers, and rational
numbers are elements of the ring QQ, of rational numbers.

One point to notice is that there are two kinds of division, see /, and
//.  The first returns a rational number (element of QQ),
while the second does division in ZZ.
+---------+
|i3 : 6/3 |
|         |
|o3 = 2   |
|         |
|o3 : QQ  |
+---------+
|i4 : 7//3|
|         |
|o4 = 2   |
+---------+

Real and complex numbers
------------------------

Real and complex numbers are approximate numbers, implemented using the
MPFR, library.
+------------------------------------------------------------------+
|i5 : 1.372489274987                                               |
|                                                                  |
|o5 = 1.372489274987                                               |
|                                                                  |
|o5 : RR (of precision 53)                                         |
+------------------------------------------------------------------+
|i6 : 1.3454353 * 10^20                                            |
|                                                                  |
|o6 = 1.3454353e20                                                 |
|                                                                  |
|o6 : RR (of precision 53)                                         |
+------------------------------------------------------------------+
|i7 : sqrt 4.5                                                     |
|                                                                  |
|o7 = 2.121320343559642                                            |
|                                                                  |
|o7 : RR (of precision 53)                                         |
+------------------------------------------------------------------+
|i8 : toRR_200 4.5                                                 |
|                                                                  |
|o8 = 4.5                                                          |
|                                                                  |
|o8 : RR (of precision 200)                                        |
+------------------------------------------------------------------+
|i9 : sqrt oo                                                      |
|                                                                  |
|o9 = 2.12132034355964257320253308631454711785450781306542210976502|
|                                                                  |
|o9 : RR (of precision 200)                                        |
+------------------------------------------------------------------+
+--------------------------+
|i10 : 1/(1+ii)            |
|                          |
|o10 = .5-.5*ii            |
|                          |
|o10 : CC (of precision 53)|
+--------------------------+

See also
========

  * Number -- the class of all numbers
  * ZZ -- the class of all integers
  * QQ -- the class of all rational numbers
  * RR -- the class of all real numbers
  * CC -- the class of all complex numbers
  * toRR -- convert to high-precision real number
  * toCC -- convert to high-precision complex number

strings and nets -- an overview of strings and nets in Macaulay2
****************************************************************

In this section we discuss strings and nets.  Strings are sequences of
characters intended to be printed, and are encountered in almost every
programming language.  Nets are two-dimensional arrays of characters intended
to be printed, and constitute a natural generalization of strings that makes
ascii printing of complicated objects much easier.

strings
=======

A string is a sequence of characters.  Strings can be manipulated in various
ways to produce printed output. One enters a string by surrounding a sequence
of characters with quotation marks.
+-----------------+
|i1 : "abcdefghij"|
|                 |
|o1 = abcdefghij  |
+-----------------+
Strings may contain newline characters.
+-----------+
|i2 : "abcde|
|     fghij"|
|           |
|o2 = abcde |
|     fghij |
+-----------+
Strings, like anything else, can be assigned to variables.
+---------------------+
|i3 : w = "abcdefghij"|
|                     |
|o3 = abcdefghij      |
+---------------------+

There are escape sequences that make it possible to enter special characters,
see ".

+-----------------------------+
|i4 : u = "abc\101\102\n\tstu"|
|                             |
|o4 = abcAB                   |
|             stu             |
+-----------------------------+

We can use peek, to see what characters are in the string.

+-----------+
|i5 : peek u|
|           |
|o5 = "abcAB|
|     \tstu"|
+-----------+
Another way to enter special characters into strings is to use ///,
as the string delimiter.  That makes it easier to enter the special characters
into the string, but impossible to enter three consecutive slashes.
+----------------------+
|i6 : ///a \ n = "c"///|
|                      |
|o6 = a \ n = "c"      |
+----------------------+
The function ascii, converts strings to lists of ascii character
code, and back again.
+-----------------------------------------------+
|i7 : ascii u                                   |
|                                               |
|o7 = {97, 98, 99, 65, 66, 10, 9, 115, 116, 117}|
|                                               |
|o7 : List                                      |
+-----------------------------------------------+
|i8 : ascii oo                                  |
|                                               |
|o8 = abcAB                                     |
|             stu                               |
+-----------------------------------------------+
We may use the operator |, to concatenate strings.
+-----------------------------------+
|i9 : w|w|w                         |
|                                   |
|o9 = abcdefghijabcdefghijabcdefghij|
+-----------------------------------+
The operator #, computes the length of a string.
+--------+
|i10 : #w|
|        |
|o10 = 10|
+--------+
We may also use the operator #, to extract single characters from a
string.  Warning: we number the characters starting with 0.
+---------+
|i11 : w#5|
|         |
|o11 = f  |
+---------+
The function substring, will extract portions of a string for
us.
+----------------------+
|i12 : substring(5,w)  |
|                      |
|o12 = fghij           |
+----------------------+
|i13 : substring(5,2,w)|
|                      |
|o13 = fg              |
+----------------------+

nets
====

A net is a rectangular two-dimensional array of characters, together with an
imaginary horizontal baseline that allows nets to be assembled easily into
lines of text.  A string is regarded as a net with one row.

Nets are used extensively for such things as formatting polynomials for display
on ascii terminals.  Use net, to obtain such nets directly.

+--------------------+
|i14 : R = ZZ[x,y];  |
+--------------------+
|i15 : (x+y)^2       |
|                    |
|       2           2|
|o15 = x  + 2x*y + y |
|                    |
|o15 : R             |
+--------------------+
|i16 : n = net oo    |
|                    |
|       2           2|
|o16 = x  + 2x*y + y |
+--------------------+
The net n above looks exactly the same as the original polynomial - that's
because a polynomial is printed by printing its net.  But the net n is no
longer usable as a polynomial; it's just an array of characters.  We may use
peek, to clarify the extent of a net.
+----------------------+
|i17 : peek n          |
|                      |
|      +--------------+|
|      | 2           2||
|o17 = |x  + 2x*y + y ||
|      +--------------+|
+----------------------+
One way to create nets directly is with the operator ||, which concatenates
strings or nets vertically.
+------------------------------+
|i18 : x = "a" || "bb" || "ccc"|
|                              |
|o18 = a                       |
|      bb                      |
|      ccc                     |
+------------------------------+
We may use the operator ^, to raise or lower a net with respect to its
baseline.  Look carefully to see how the baseline has moved - it is aligned
with the equal sign.
+---------+
|i19 : x^2|
|         |
|      a  |
|      bb |
|o19 = ccc|
+---------+
Nets may appear in lists, and elsewhere.
+---------------------+
|i20 : {x,x^1,x^2}    |
|                     |
|                 a   |
|            a    bb  |
|o20 = {a  , bb , ccc}|
|       bb   ccc      |
|       ccc           |
|                     |
|o20 : List           |
+---------------------+
Nets and strings can be concatenated horizontally with the operator |.
+-------------------------+
|i21 : x^2 | "-------" | x|
|                         |
|      a                  |
|      bb                 |
|o21 = ccc-------a        |
|                bb       |
|                ccc      |
+-------------------------+
Each net has a width, a depth, and a height.  The width is the number of
characters in each row.  The depth is the number of rows below the baseline,
and the height is the number of rows above the baseline. The depth and the
height can be negative.
+--------------------------------+
|i22 : width x, height x, depth x|
|                                |
|o22 = (3, 1, 2)                 |
|                                |
|o22 : Sequence                  |
+--------------------------------+
We may extract the rows of a net as strings with unstack, and
put them back together again with stack.
+------------------------+
|i23 : v = unstack x     |
|                        |
|o23 = {a, bb, ccc}      |
|                        |
|o23 : List              |
+------------------------+
|i24 : peek oo           |
|                        |
|o24 = {"a", "bb", "ccc"}|
+------------------------+
|i25 : stack v           |
|                        |
|o25 = a                 |
|      bb                |
|      ccc               |
+------------------------+

functions for handling strings

functions for handling nets

more information

regular expressions -- syntax for regular expressions
*****************************************************

A regular expression is a string that specifies a pattern that describes a set
of matching subject strings. Typically the string is compiled into a
deterministic finite automaton whose execution, guided by the subject string,
determines whether there is a match.

Characters match themselves, except for the following special characters.

.  [  {  }  (  )  \  *  +  ?  |  ^  $

Regular expressions are constructed inductively as follows: the empty regular
expression matches the empty string; a concatenation of regular expressions
matches the concatenation of the corresponding matching strings.  Regular
expressions separated by the character | match strings matched by any of them.
Parentheses can be used for grouping, except that now, with the use of the
Boost, library, their insertion may alter the matching of
subexpressions of ambiguous expressions. Additionally, the substrings matched
by parenthesized subexpressions are captured for later use in replacement
strings.

Syntax for special characters
-----------------------------

  * Wildcard
      * .        -- match any character except the newline character
  * Anchors
      * ^        -- match the beginning of the string or the beginning of a
        line
      * $        -- match the end of the string or the end of a line
  * Sub-expressions
      * (...)        -- marked sub-expression, may be referred to by a
        back-reference
      * \i        -- match the same string that the i-th parenthesized
        sub-expression matched
  * Repeats
      * *        -- match previous expression 0 or more times
      * +        -- match previous expression 1 or more times
      * ?        -- match previous expression 1 or 0 times
      * {m}        -- match previous expression exactly m times
      * {m,n}        -- match previous expression at least m and at most n
        times
      * {,n}        -- match previous expression at most n times
      * {m,}        -- match previous expression at least m times
  * Alternation
      * |        -- match expression to left or expression to right
  * Word and buffer boundaries
      * \b        -- match word boundary
      * \B        -- match within word
      * \<        -- match beginning of word
      * \>        -- match end of word
      * \`        -- match beginning of string
      * \'        -- match end of string
  * Character sets
      * [...]        -- match any single character that is a member of the set
          * [abc]        -- match either a, b, or c
          * [A-C]        -- match any character from A through C
      * [^...]        -- match non-listed characters, ranges, or classes
  * Character classes
      * [:alnum:]        -- any alphanumeric character
      * [:alpha:]        -- any alphabetic character
      * [:blank:]        -- any whitespace or tab character
      * [:cntrl:]        -- any control character
      * [:digit:]        -- any decimal digit
      * [:graph:]        -- any graphical character (same as [:print:] except
        omits space)
      * [:lower:]        -- any lowercase character
      * [:print:]        -- any printable character
      * [:punct:]        -- any punctuation character
      * [:space:]        -- any whitespace, tab, carriage return, newline,
        vertical tab, and form feed
      * [:unicode:]        -- any unicode character with code point above 255
        in value
      * [:upper:]        -- any uppercase character
      * [:word:]        -- any word character (alphanumeric characters plus the
        underscore
      * [:xdigit:]        -- any hexadecimal digit character
  * "Single character" character classes
      * \d        -- same as [[:digit:]]
      * \l        -- same as [[:lower:]]
      * \s        -- same as [[:space:]]
      * \u        -- same as [[:upper:]]
      * \w        -- same as [[:word:]]
      * \D        -- same as [^[:digit:]]
      * \L        -- same as [^[:lower:]]
      * \S        -- same as [^[:space:]]
      * \U        -- same as [^[:upper:]]
      * \W        -- same as [^[:word:]]

The special character \ may be confusing, as inside a string delimited by
quotation marks ("..."), you type two of them to specify a special character,
whereas inside a string delimited by triple slashes (///...///), you only need
one. Thus regular expressions delimited by triple slashes are more readable. To
match \ against itself, double the number of backslashes.

In order to match one of the special characters itself, precede it with a
backslash or use regexQuote.

Flavors of Regular Expressions
==============================

The regular expression functions in Macaulay2 are powered by calls to the
Boost.Regex (see https://www.boost.org/doc/libs/release/libs/regex/ ) C++
library, which supports multiple flavors, or standards, of regular expression.

Since Macaulay2 v1.17 (missing documentation), the Perl flavor is the default.
In general, the Perl flavor supports all patterns designed for the POSIX
Extended flavor, but allows for more fine-tuning in the patterns.
Alternatively, the POSIX Extended flavor can be chosen by passing the option
POSIX => true. One key difference is what happens when there is more that one
way to match a regular expression:

  * Perl -- the "first" match is arrived at by a depth-first search.
  * POSIX -- the "best" match is obtained using the "leftmost-longest" rule;

If there's a tie in the POSIX flavor, the rule is applied to the first
parenthetical subexpression.

Additional Perl Regular Expression Syntax
=========================================

The Perl flavor adds the following, non-backward compatible constructions:

Non-marking grouping; i.e., a grouping that does not generate a sub-expression
------------------------------------------------------------------------------

  * (?#...)        -- ignored and treated as a comment
  * (?:...)        -- non-marked sub-expression, may not be referred to by a
    back-reference
  * (?=...)        -- positive lookahead; consumes zero characters, only if
    pattern matches
  * (?!...)        -- negative lookahead; consumes zero characters, only if
    pattern does not match
  * (?<=..)        -- positive lookbehind; consumes zero characters, only if
    pattern could be matched against the characters preceding the current
    position (pattern must be of fixed length)
  * (?<!..)        -- negative lookbehind; consumes zero characters, only if
    pattern could not be matched against the characters preceding the current
    position (pattern must be of fixed length)
  * (?>...)        -- match independently of the surrounding pattern and the
    expression will never backtrack into the pattern

Non-greedy repeats
------------------

  * *?        -- match the previous atom 0 or more times, while consuming as
    little input as possible
  * +?        -- match the previous atom 1 or more times, while consuming as
    little input as possible
  * ??        -- match the previous atom 1 or 0 times, while consuming as
    little input as possible
  * {m,}?        -- match the previous atom m or more times, while consuming as
    little input as possible
  * {m,n}?        -- match the previous atom at between m and n times, while
    consuming as little input as possible

Possessive repeats
------------------

  * *+        -- match the previous atom 0 or more times, while giving nothing
    back
  * ++        -- match the previous atom 1 or more times, while giving nothing
    back
  * ?+        -- match the previous atom 1 or 0 times, while giving nothing
    back
  * {m,}+        -- match the previous atom m or more times, while giving
    nothing back
  * {m,n}+        -- match the previous atom at between m and n times, while
    giving nothing back

Back references
---------------

  * \g1        -- match whatever matched sub-expression 1
  * \g{1}        -- match whatever matched sub-expression 1
  * \g-1        -- match whatever matched the last opened sub-expression
  * \g{-2}        -- match whatever matched the last but one opened
    sub-expression
  * \g{that}        -- match whatever matched the sub-expression named "that"
  * \k<that>        -- match whatever matched the sub-expression named "that"
  * (?<NAME>...)        -- named sub-expression, may be referred to by a named
    back-reference
  * (?'NAME'...)        -- named sub-expression, may be referred to by a named
    back-reference

See references below for more in depth syntax for controlling the backtracking
algorithm.

String Formatting Syntax
========================

The replacement string in replace(String,String,String),
and select(String,String,String),
supports additional syntax for escape
sequences as well as inserting captured sub-expressions:

Using Perl regular expression syntax (default)
----------------------------------------------

  * Syntax for inserting captured sub-expressions:
      * $&        -- outputs what matched the whole expression
      * $`        -- outputs the text between the end of the last match (or
        beginning if no previous match was found) and the start of the current
        match
      * $'        -- outputs the text following the end of the current match
      * $+        -- outputs what matched the last marked sub-expression in the
        regular expression
      * $^N        -- outputs what matched the last sub-expression to be
        actually matched
      * $n        -- outputs what matched the n-th sub-expression
      * ${n}        -- outputs what matched the n-th sub-expression
      * $+{NAME}        -- outputs what matched the sub-expression named NAME
        (Perl syntax only)
      * $$        -- outputs a literal $
  * Syntax for manipulating the captured groups:
      * \l        -- converts the next character to be outputted to lower case
      * \u        -- converts the next character to be outputted to upper case
      * \L        -- converts all subsequent characters to be outputted to
        lower case, until it reaches \E
      * \U        -- converts all subsequent characters to be outputted to
        upper case, until it reaches \E
      * \E        -- terminates a \U or \L sequence
      * \        -- specifies an escape sequence (e.g. \\)

Using POSIX Extended syntax (POSIX => true)
-------------------------------------------

  * Syntax for inserting captured groups:
      * &        -- outputs what matched the whole expression
      * \0        -- outputs what matched the whole expression
      * \n        -- if n is in the range 1-9, outputs what matched the n-th
        sub-expression
      * \        -- specifies an escape sequence (e.g. \&)

For the complete list, including characters escape sequences, see the
Boost.Regex manual on format string syntax (see
https://www.boost.org/doc/libs/release/libs/regex/doc/html/boost_regex/format/
perl_format.html ).

String processing functions that accept regular expressions
-----------------------------------------------------------

  * match -- regular expression matching
  * regex -- evaluate a regular expression search
  * separate -- split a string into substrings using a regular
    expression
  * select(String,String,String),
    -- select and reformat substrings matching a regular expression
  * replace(String,String,String),
    -- replace substrings matching a regular expression

Other functions that accept regular expressions
-----------------------------------------------

  * about -- search the documentation
  * apropos -- symbols matching a pattern
  * findFiles -- find files recursively
  * copyDirectory
  * symlinkDirectory -- make
    symbolic links for all files in a directory tree

Complete References
===================

For complete documentation on regular expressions supported in Macaulay2, see
the Boost.Regex manual on Perl (see
https://www.boost.org/doc/libs/release/libs/regex/doc/html/boost_regex/syntax/
perl_syntax.html ) and Extended (see
https://www.boost.org/doc/libs/release/libs/regex/doc/html/boost_regex/syntax/
basic_extended.html ) flavors, or read the entry for regex in section 7 of the
unix man pages.

In addition to the functions mentioned below, regular expressions appear in
about, apropos, findFiles,
copyDirectory, and
symlinkDirectory.

functions that accept regular expressions

match -- regular expression matching
************************************

Synopsis
========

  * Usage:
        match(re, str)
        match(patterns, str)
  * Inputs:
      * re, a string, a regular expression,
        describing a pattern
      * str, a string, a subject string to be searched
      * patterns, a list, a list of regular expressions
  * Optional inputs,:
      * POSIX => a Boolean value, default value false, if true,
        interpret the re using the POSIX Extended flavor, otherwise the Perl
        flavor
      * Strategy => a function, default value any, logical
        quantifier for matching a list of patterns, typically all,
        or any,
  * Outputs:
      * a Boolean value, whether the string str is a match for
        the regular expression re, or at least one of patterns when Strategy =>
        any (default)
  * Consequences:
      * the variable lastMatch, is set to the value returned by
        regex, which is called by match.

Description
===========

For an introduction to regular expressions, see regular expressions.

+-----------------------------------------------+
|i1 : s = "three dogs, two catfishes, and a cat"|
|                                               |
|o1 = three dogs, two catfishes, and a cat      |
+-----------------------------------------------+
|i2 : match("cat", s)                           |
|                                               |
|o2 = true                                      |
+-----------------------------------------------+
|i3 : lastMatch                                 |
|                                               |
|o3 = {(16, 3)}                                 |
|                                               |
|o3 : List                                      |
+-----------------------------------------------+
|i4 : substring(first lastMatch, s)             |
|                                               |
|o4 = cat                                       |
+-----------------------------------------------+
|i5 : match ("cats", s)                         |
|                                               |
|o5 = false                                     |
+-----------------------------------------------+
|i6 : lastMatch                                 |
+-----------------------------------------------+

The POSIX => true option can be used to specify the POSIX Extended flavor for
the regular expression used to match. Note that only the Perl flavor allows the
use of lookahead and lookbehinds.

+----------------------------------------------------+
|i7 : s = "catfish cat dog"                          |
|                                                    |
|o7 = catfish cat dog                                |
+----------------------------------------------------+
|i8 : match("cat(?!fish)", s)                        |
|                                                    |
|o8 = true                                           |
+----------------------------------------------------+
|i9 : substring(lastMatch#0#0, lastMatch#0#1 + 4, s) |
|                                                    |
|o9 = cat dog                                        |
+----------------------------------------------------+
|i10 : match("cat(?=fish)", s)                       |
|                                                    |
|o10 = true                                          |
+----------------------------------------------------+
|i11 : substring(lastMatch#0#0, lastMatch#0#1 + 4, s)|
|                                                    |
|o11 = catfish                                       |
+----------------------------------------------------+
|i12 : match("(?<!cat)fish", "cat catfish dog")      |
|                                                    |
|o12 = false                                         |
+----------------------------------------------------+
|i13 : match("(?<!cat)fish", "cat swordfish dog")    |
|                                                    |
|o13 = true                                          |
+----------------------------------------------------+

When the first input is a list, by default the output is true if str is a match
for at least one of the given regular expressions.

+--------------------------------------+
|i14 : match({"Cat", "Dog"}, "CatDog") |
|                                      |
|o14 = true                            |
+--------------------------------------+
|i15 : match({"Cat", "Dog"}, "Catfish")|
|                                      |
|o15 = true                            |
+--------------------------------------+

Optionally, Strategy => all indicates that the string should match every
pattern in the list to be a match.

+-----------------------------------------------------------+
|i16 : match({"Cat", "Dog"}, "CatDog", Strategy => all)     |
|                                                           |
|o16 = true                                                 |
+-----------------------------------------------------------+
|i17 : not match({"Cat", "Dog"}, "Catfish", Strategy => all)|
|                                                           |
|o17 = true                                                 |
+-----------------------------------------------------------+

The Strategy option is not used when the first input is not a list.

See also
========

  * regular expressions -- syntax for regular
    expressions
  * strings and nets -- an overview of strings and
    nets in Macaulay2
  * regex -- evaluate a regular expression search
  * replace -- replacement in strings and lists
  * substring -- extract part of a string
  * any -- whether any elements satisfy a specified condition
  * all -- whether all elements satisfy a specified condition

Ways to use match:
==================

  * "match(List,String)"
  * "match(String,String)"

For the programmer
==================

The object match, is a method function with options.

regex -- evaluate a regular expression search
*********************************************

Synopsis
========

  * Usage:
        regex(re, str)
        regex(re, start, str)
        regex(re, start, range, str)
  * Inputs:
      * re, a string, a regular expression,
        describing a pattern
      * start, an integer, positive, the position in str at which to
        begin the search. when omitted, the search starts at the beginning of
        the string.
      * range, an integer, restricts matches to those beginning at a
        position between start and start + range; when 0, the pattern is
        matched only at the starting position; when negative, only positions to
        the left of the starting position are examined for matches; when
        omitted, the search extends to the end of the string.
      * str, a string, the subject string to be searched
  * Optional inputs,:
      * POSIX => a Boolean value, default value false, if true,
        interpret the re using the POSIX Extended flavor, otherwise the Perl
        flavor
  * Outputs:
      * a list, a list of pairs of integers; each pair denotes the
        beginning position and the length of a substring. Only the leftmost
        matching substring of str and the capturing groups within it are
        returned. If no match is found, the output is null.

Description
===========

The value returned is a list of pairs of integers corresponding to the
parenthesized subexpressions successfully matched, suitable for use as the
first argument of substring. The first member of each pair is
the offset within str of the substring matched, and the second is the length.

See regular expressions, for a brief introduction to
the topic.

+----------------------------------------+
|i1 : s = "The cat is black.";           |
+----------------------------------------+
|i2 : m = regex("(\\w+) (\\w+) (\\w+)",s)|
|                                        |
|o2 = {(0, 10), (0, 3), (4, 3), (8, 2)}  |
|                                        |
|o2 : List                               |
+----------------------------------------+
|i3 : substring(m#0, s)                  |
|                                        |
|o3 = The cat is                         |
+----------------------------------------+
|i4 : substring(m#1, s)                  |
|                                        |
|o4 = The                                |
+----------------------------------------+
|i5 : substring(m#2, s)                  |
|                                        |
|o5 = cat                                |
+----------------------------------------+
|i6 : substring(m#3, s)                  |
|                                        |
|o6 = is                                 |
+----------------------------------------+
|i7 : s = "aa     aaaa";                 |
+----------------------------------------+
|i8 : m = regex("a+", 0, s)              |
|                                        |
|o8 = {(0, 2)}                           |
|                                        |
|o8 : List                               |
+----------------------------------------+
|i9 : substring(m#0, s)                  |
|                                        |
|o9 = aa                                 |
+----------------------------------------+
|i10 : m = regex("a+", 2, s)             |
|                                        |
|o10 = {(7, 4)}                          |
|                                        |
|o10 : List                              |
+----------------------------------------+
|i11 : substring(m#0, s)                 |
|                                        |
|o11 = aaaa                              |
+----------------------------------------+
|i12 : m = regex("a+", 2, 3, s)          |
+----------------------------------------+
|i13 : s = "line 1\nline 2\r\nline 3";   |
+----------------------------------------+
|i14 : m = regex("^.*$", 8, -8, s)       |
|                                        |
|o14 = {(7, 6)}                          |
|                                        |
|o14 : List                              |
+----------------------------------------+
|i15 : substring(m#0, s)                 |
|                                        |
|o15 = line 2                            |
+----------------------------------------+
|i16 : m = regex("^", 10, -10, s)        |
|                                        |
|o16 = {(7, 0)}                          |
|                                        |
|o16 : List                              |
+----------------------------------------+
|i17 : substring(0, m#0#0, s)            |
|                                        |
|o17 = line 1                            |
+----------------------------------------+
|i18 : substring(m#0#0, s)               |
|                                        |
|o18 = line 2                            |
|      line 3                            |
+----------------------------------------+
|i19 : m = regex("^.*$", 4, -10, s)      |
|                                        |
|o19 = {(0, 6)}                          |
|                                        |
|o19 : List                              |
+----------------------------------------+
|i20 : substring(m#0, s)                 |
|                                        |
|o20 = line 1                            |
+----------------------------------------+
|i21 : m = regex("a.*$", 4, -10, s)      |
+----------------------------------------+

By default, the regular expressions are interpreted using the Perl flavor,
which supports features such as lookaheads and lookbehinds for fine-tuning the
matches. This syntax is used in Perl and JavaScript languages.

+------------------------------+
|i22 : regex("A(?!C)", "AC AB")|
|                              |
|o22 = {(3, 1)}                |
|                              |
|o22 : List                    |
+------------------------------+
|i23 : regex("A(?=B)", "AC AB")|
|                              |
|o23 = {(3, 1)}                |
|                              |
|o23 : List                    |
+------------------------------+

Alternatively, one can choose the POSIX Extended flavor of regex using POSIX =>
true. This syntax is similar to the one used by the Unix utilities egrep and
awk and enforces the leftmost, longest rule for finding matches. If there's a
tie, the rule is applied to the first subexpression.

+-------------------------------------------------+
|i24 : s = "<b>bold</b> and <b>strong</b>";       |
+-------------------------------------------------+
|i25 : m = regex("<b>(.*)</b>", s, POSIX => true);|
+-------------------------------------------------+
|i26 : substring(m#1, s)                          |
|                                                 |
|o26 = bold</b> and <b>strong                     |
+-------------------------------------------------+

In the Perl flavor, one can specify whether repetitions should be possessive or
non-greedy.

+-----------------------------------+
|i27 : m = regex("<b>(.*?)</b>", s);|
+-----------------------------------+
|i28 : substring(m#1, s)            |
|                                   |
|o28 = bold                         |
+-----------------------------------+

See also
========

  * regular expressions -- syntax for regular
    expressions
  * strings and nets -- an overview of strings and
    nets in Macaulay2
  * match -- regular expression matching
  * separate -- split a string into substrings using a regular
    expression
  * replace(String,String,String),
    -- replace substrings matching a regular expression
  * select(String,String,String),
    -- select and reformat substrings matching a regular expression
  * regexQuote -- escape special characters in regular
    expressions
  * substring -- extract part of a string

Ways to use regex:
==================

  * "regex(String,String)"
  * "regex(String,ZZ,String)"
  * "regex(String,ZZ,ZZ,String)"

For the programmer
==================

The object regex, is a method function with options.

separate -- split a string into substrings using a regular expression
*********************************************************************

Synopsis
========

  * Usage:
        separate str
        separate(re, str)
        separate(re, n, str)
  * Inputs:
      * re, a string, a regular expression,
        describing a pattern
      * str, a string, the string to split
      * n, an integer, the index of the parenthesized expression to
        split on
  * Optional inputs,:
      * POSIX => a Boolean value, default value false, if true,
        interpret the re using the POSIX Extended flavor, otherwise the Perl
        flavor
  * Outputs:
      * a list, a list of strings obtained by breaking str at
        every match to the pattern re, or, if a natural number n is specified,
        using the $n$-th parenthesized expression in re as the separator. If no
        re is specified, str is split at every new line.

Description
===========

For an introduction to regular expressions, see regular expressions.

Example 1: The command separate(s) breaks the string at every occurrence of
\r\n or \n.

+-----------------------------------------------------------------------------+
|i1 : s = "A string with both Unix-style\nand Windows-style\r\nnew line       |
|                                                                             |
|o1 = A string with both Unix-style                                           |
|     and Windows-style                                                       |
|     new line characters.                                                    |
|-----------------------------------------------------------------------------|
|characters."                                                                 |
+-----------------------------------------------------------------------------+
|i2 : separate s                                                              |
|                                                                             |
|o2 = {A string with both Unix-style, and Windows-style, new line characters.}|
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

This is equivalent to using the lines, function.

+-----------------------------------------------------------------------------+
|i3 : lines s                                                                 |
|                                                                             |
|o3 = {A string with both Unix-style, and Windows-style, new line characters.}|
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

Example 2: use commas, periods, and semicolons as separators.

+-----------------------------------------------------------------------------+
|i4 : separate("[,.;]", "Example: a string. That, is punctuated, weirdly; for |
|                                                                             |
|o4 = {Example: a string,  That,  is punctuated,  weirdly,  for demonstration |
|     ------------------------------------------------------------------------|
|     purposes, }                                                             |
|                                                                             |
|o4 : List                                                                    |
|-----------------------------------------------------------------------------|
|demonstration purposes.")                                                    |
+-----------------------------------------------------------------------------+

Example 3: match any number of consecutive spaces.

+-----------------------------------------------------------------------------+
|i5 : t = separate("[ ]+", "this    string has   different   lengths of       |
|                                                                             |
|o5 = {this, string, has, different, lengths, of, spacing, between, words}    |
|                                                                             |
|o5 : List                                                                    |
|-----------------------------------------------------------------------------|
|spacing  between     words")                                                 |
+-----------------------------------------------------------------------------+

We can now correct the original string using the demark, and
replace, functions.

+-------------------------------------------------------------------------+
|i6 : replace("has", "does not have", demark(" ", t))                     |
|                                                                         |
|o6 = this string does not have different lengths of spacing between words|
+-------------------------------------------------------------------------+

Example 4: delete every word starting with "x" from a string, by using
concatenate, together with separate.

+-----------------------------------------------------------------+
|i7 : s = "algng xjfr kfjxse xhgfj xooi xwj kvexr anvi endj xkfi";|
+-----------------------------------------------------------------+
|i8 : concatenate separate(" x[A-Za-z]*", s)                      |
|                                                                 |
|o8 = algng kfjxse kvexr anvi endj                                |
+-----------------------------------------------------------------+

Example 5: The optional argument n allows us to specify a separator that
differs from the match criteria. In the previous example, words beginning with
"x" were both the match and the separator. In this example, we match words
beginning with "x", but separate the string using the leading "x". With
concatenate, this results in deleting just the "x" from words
starting with "x" (not the same as removing every "x").

+-----------------------------------------------------+
|i9 : concatenate separate(" (x)[A-Za-z]*", 1, s)     |
|                                                     |
|o9 = algng jfr kfjxse hgfj ooi wj kvexr anvi endj kfi|
+-----------------------------------------------------+

separateRegexp is a deprecated synonym for separate.

Caveat
======

For backwards compatibility, if the pattern is a single character and it is an
unescaped special character, such as +, *, or ., then it is treated as a
literal character. In future code, the pattern must be escaped.

See also
========

  * regular expressions -- syntax for regular
    expressions
  * strings and nets -- an overview of strings and
    nets in Macaulay2
  * regex -- evaluate a regular expression search
  * lines -- split a string into lines
  * demark -- insert a string between elements of a list of
    strings
  * concatenate -- join strings

Ways to use separate:
=====================

  * "separate(String)"
  * "separate(String,String)"
  * "separate(String,ZZ,String)"

For the programmer
==================

The object separate, is a method function with options.

select(String,String,String) -- select and reformat substrings matching a regular expression
********************************************************************************************

Synopsis
========

  * Function: select,
  * Usage:
        select(re, replacement, str)
        select(re, str)
  * Inputs:
      * re, a string, a regular expression,
        describing a pattern
      * replacement, a string, following the formatting syntax,
      * str, a string, a subject string to be searched
  * Optional inputs,:
      * POSIX => a Boolean value, default value false, if true,
        interpret the re using the POSIX Extended flavor, otherwise the Perl
        flavor
  * Outputs:
      * a list, of mutually exclusive substrings of str matching
        the pattern re; if replacement is given, the matching substrings are
        formatted based on it.

Description
===========

For an introduction to regular expressions, see regular expressions.

+--------------------------------------------------+
|i1 : select("[[:alpha:]]+", "Dog, cat, and deer.")|
|                                                  |
|o1 = {Dog, cat, and, deer}                        |
|                                                  |
|o1 : List                                         |
+--------------------------------------------------+
|i2 : select("^.*$", "ABC\nDEF\r\nGHI")            |
|                                                  |
|o2 = {ABC, DEF, GHI}                              |
|                                                  |
|o2 : List                                         |
+--------------------------------------------------+

The replacement string may contain formatting syntax,
such as backreferences $1 or \\1, which will be replaced by the
string matching the corresponding parenthesized subexpression of re.

+----------------------------------------------------+
|i3 : select("([a-zA-Z]+);", "$1", "Dog; cat, deer;")|
|                                                    |
|o3 = {Dog, deer}                                    |
|                                                    |
|o3 : List                                           |
+----------------------------------------------------+

Special operators such as the lowercase operator \\L may also be used to
manipulate the replacement substring.

+-------------------------------------------------------+
|i4 : select("([a-zA-Z]+);", "\\L$1", "Dog; cat, deer;")|
|                                                       |
|o4 = {dog, deer}                                       |
|                                                       |
|o4 : List                                              |
+-------------------------------------------------------+

Lookaheads and lookbehinds can be used to precisely control the regular
expression matches.

+---------------------------------------------+
|i5 : s = "catfish cats dogs";                |
+---------------------------------------------+
|i6 : select("cat(?!fish)s?", s)              |
|                                             |
|o6 = {cats}                                  |
|                                             |
|o6 : List                                    |
+---------------------------------------------+
|i7 : select("\\w+(?=s\\b)", s)               |
|                                             |
|o7 = {cat, dog}                              |
|                                             |
|o7 : List                                    |
+---------------------------------------------+
|i8 : s = "goldfish swordfish catfish catdog";|
+---------------------------------------------+
|i9 : select("\\w+(?=fish)", s)               |
|                                             |
|o9 = {gold, sword, cat}                      |
|                                             |
|o9 : List                                    |
+---------------------------------------------+
|i10 : select("(?<=cat)\\w+", s)              |
|                                             |
|o10 = {fish, dog}                            |
|                                             |
|o10 : List                                   |
+---------------------------------------------+

The POSIX => true option can be used to specify the POSIX Extended flavor for
the regular expression used to match. Note that only the Perl flavor allows the
use of lookaheads and lookbehinds.

See also
========

  * regular expressions -- syntax for regular
    expressions
  * strings and nets -- an overview of strings and
    nets in Macaulay2
  * regex -- evaluate a regular expression search
  * separate -- split a string into substrings using a regular
    expression
  * replace(String,String,String),
    -- replace substrings matching a regular expression

Ways to use this method:
========================

  * "select(String,String)"
  * select(String,String,String),
    -- select and reformat substrings matching a regular expression

replace(String,String,String) -- replace substrings matching a regular expression
*********************************************************************************

Synopsis
========

  * Function: replace,
  * Usage:
        replace(re, replacement, str)
  * Inputs:
      * re, a string, a regular expression,
        describing a pattern
      * replacement, a string, following the formatting syntax,
      * str, a string, a subject string to be processed
  * Optional inputs,:
      * POSIX => a Boolean value, default value false, if true,
        interpret the re using the POSIX Extended flavor, otherwise the Perl
        flavor
  * Outputs:
      * a string, obtained from str by replacing its substrings
        matching re by copies of replacement

Description
===========

For an introduction to regular expressions, see regular expressions.

+-------------------------------------------+
|i1 : replace("[a-z]+", "x", "Dog cat cat.")|
|                                           |
|o1 = Dx x x.                               |
+-------------------------------------------+

The replacement string may contain formatting syntax,
such as backreferences $1 or \\1, which will be replaced by the
string matching the corresponding parenthesized subexpression of re.

+----------------------------------------------------+
|i2 : replace("(\\w+)\\.?", "A \\1.", "Dog cat cat.")|
|                                                    |
|o2 = A Dog. A cat. A cat.                           |
+----------------------------------------------------+

Special operators such as the lowercase operator \\L may also be used to
manipulate the replacement substring.

+------------------------------------------------------+
|i3 : replace("(\\w+)\\.?", "A \\L$1.", "Dog cat cat.")|
|                                                      |
|o3 = A dog. A cat. A cat.                             |
+------------------------------------------------------+

Lookaheads and lookbehinds can be used to precisely control the regular
expression matches.

+---------------------------------------------+
|i4 : s = "catfish cats dogs";                |
+---------------------------------------------+
|i5 : replace("cat(?!fish)s?", "\\U$&", s)    |
|                                             |
|o5 = catfish CATS dogs                       |
+---------------------------------------------+
|i6 : replace("\\w+(?=s\\b)", "\\U$&", s)     |
|                                             |
|o6 = catfish CATs DOGs                       |
+---------------------------------------------+
|i7 : s = "goldfish swordfish catfish catdog";|
+---------------------------------------------+
|i8 : replace("\\w+(?=fish)", "\\U$&", s)     |
|                                             |
|o8 = GOLDfish SWORDfish CATfish catdog       |
+---------------------------------------------+
|i9 : replace("(?<=cat)\\w+", "\\U$&", s)     |
|                                             |
|o9 = goldfish swordfish catFISH catDOG       |
+---------------------------------------------+

The POSIX => true option can be used to specify the POSIX Extended flavor for
the regular expression used to match. Note that only the Perl flavor allows the
use of lookaheads and lookbehinds.

See also
========

  * regular expressions -- syntax for regular
    expressions
  * strings and nets -- an overview of strings and
    nets in Macaulay2
  * regex -- evaluate a regular expression search
  * match -- regular expression matching
  * separate -- split a string into substrings using a regular
    expression
  * select(String,String,String),
    -- select and reformat substrings matching a regular expression

Ways to use this method:
========================

  * replace(String,String,String),
    -- replace substrings matching a regular expression

regexQuote -- escape special characters in regular expressions
**************************************************************

Synopsis
========

  * Usage:
        regexQuote s
  * Inputs:
      * s, a string,
  * Outputs:
      * a string, obtained from s by escaping all of the
        characters that have special meanings in regular expressions (\, ^, $,
        ., |, ?, *, +, (, ), [, ], {, }) with a \.

Description
===========

+------------------------+
|i1 : match("2+2", "2+2")|
|                        |
|o1 = false              |
+------------------------+
|i2 : regexQuote "2+2"   |
|                        |
|o2 = 2\+2               |
+------------------------+
|i3 : match(oo, "2+2")   |
|                        |
|o3 = true               |
+------------------------+

See also
========

  * regular expressions -- syntax for regular
    expressions
  * regex -- evaluate a regular expression search
  * match -- regular expression matching

Ways to use regexQuote:
=======================

  * "regexQuote(String)"

For the programmer
==================

The object regexQuote, is a method function with a single argument.

concatenate -- join strings
***************************

Description
===========

concatenate(s,t,...,u) yields the concatenation of the strings s,t,...,u.

The arguments may also be lists or sequences of strings and symbols, in which
case they are concatenated recursively.  Additionally, an integer may be used
to represent a number of spaces, and null, will be represented by
the empty string.
+---------------------------------------+
|i1 : concatenate {"a",("s",3,"d",),"f"}|
|                                       |
|o1 = as   df                           |
+---------------------------------------+

See also
========

  * String -- the class of all strings

Ways to use concatenate:
========================

  * "concatenate(BasicList)"
  * "concatenate(Nothing)"
  * "concatenate(String)"
  * "concatenate(Symbol)"
  * "concatenate(ZZ)"

For the programmer
==================

The object concatenate, is a compiled function.

format -- format a string or a real number
******************************************

Description
===========

Synopsis
========

  * Usage:
        format(s)
  * Inputs:
      * s
  * Outputs:
      * a string obtained from s by inserting escape sequences, thereby
        preparing it for printing in a form suitable for reading in again
+------------------+
|i1 : s = "a\"b\"c"|
|                  |
|o1 = a"b"c        |
+------------------+
|i2 : t = format s |
|                  |
|o2 = "a\"b\"c"    |
+------------------+
|i3 : u = value t  |
|                  |
|o3 = a"b"c        |
+------------------+
|i4 : u == s       |
|                  |
|o4 = true         |
+------------------+

Synopsis
========

  * Usage:
        format(s,k,l,t,e,x)
  * Inputs:
      * s, an integer, the maximum number of significant decimal
        digits (default: printingPrecision). The
        special value 0 imposes no limit.
      * k, an integer, how far to the right of the decimal point to
        go, at most (default: printingAccuracy). The
        special value -1 imposes no limit.
      * l, an integer, maximum number of leading zeroes (default:
        printingLeadLimit)
      * t, an integer, maximum number of trailing zeroes (default:
        printingTrailLimit)
      * e, a string, the separator between the mantissa and the
        exponent (default: printingSeparator)
      * x, a real number, the number to be converted to a string
  * Outputs:
      * a string, the decimal representation of the number x,
        prepared according to the parameters above
+------------------------------------+
|i5 : format(10,1/3000.)             |
|                                    |
|o5 = .0003333333333                 |
+------------------------------------+
|i6 : format(10,6,1/3000.)           |
|                                    |
|o6 = .000333                        |
+------------------------------------+
|i7 : format(10,6,2,1/3000.)         |
|                                    |
|o7 = 3.33e-4                        |
+------------------------------------+
|i8 : format(10,300000.)             |
|                                    |
|o8 = 300000                         |
+------------------------------------+
|i9 : format(10,-1,10,5,300000.)     |
|                                    |
|o9 = 300000                         |
+------------------------------------+
|i10 : format(10,-1,10,4,300000.)    |
|                                    |
|o10 = 3e5                           |
+------------------------------------+
|i11 : format(10,-1,10,4,"E",300000.)|
|                                    |
|o11 = 3E5                           |
+------------------------------------+

See also
========

  * toExternalString -- convert to a readable string

Ways to use format:
===================

  * "format(DocumentTag)" -- see DocumentTag, -- the class
    of all document tags
  * "format(CC)"
  * "format(RR)"
  * "format(String)"

For the programmer
==================

The object format, is a method function with a single argument.

lines -- split a string into lines
**********************************

Synopsis
========

  * Usage:
        lines s
        lines(nl, s)
  * Inputs:
      * s, a string,
      * nl, a string,
  * Outputs:
      * a list, an array of strings obtained from the string s by
        breaking it at the characters specified by the string nl

Description
===========

The form lines s is designed to break lines correctly when the file follows the
Unix or MS-DOS convention. In other words, it will break a line at \r\n or \n.

+------------------------------+
|i1 : lines "a\nb\nc\n"        |
|                              |
|o1 = {a, b, c}                |
|                              |
|o1 : List                     |
+------------------------------+
|i2 : peek oo                  |
|                              |
|o2 = {"a", "b", "c"}          |
+------------------------------+
|i3 : lines "a\nb\nc\nd"       |
|                              |
|o3 = {a, b, c, d}             |
|                              |
|o3 : List                     |
+------------------------------+
|i4 : peek oo                  |
|                              |
|o4 = {"a", "b", "c", "d"}     |
+------------------------------+
|i5 : lines( "\\.", "a.b.c." ) |
|                              |
|o5 = {a, b, c}                |
|                              |
|o5 : List                     |
+------------------------------+
|i6 : peek oo                  |
|                              |
|o6 = {"a", "b", "c"}          |
+------------------------------+
|i7 : lines( "\\.", "a.b.c.d" )|
|                              |
|o7 = {a, b, c, d}             |
|                              |
|o7 : List                     |
+------------------------------+
|i8 : peek oo                  |
|                              |
|o8 = {"a", "b", "c", "d"}     |
+------------------------------+

Caveat
======

For backwards compatibility, if the pattern is a single character and it is an
unescaped special character, such as +, *, or ., then it is treated as a
literal character. In future code, the pattern must be escaped.

See also
========

  * newline -- the new line character sequence
  * separate -- split a string into substrings using a regular
    expression

Ways to use lines:
==================

  * "lines(String)"
  * "lines(String,String)"

For the programmer
==================

The object lines, is a function closure.

ascii -- ASCII character conversion
***********************************

Description
===========

Synopsis
========

  * Usage:
        ascii v
  * Inputs:
      * v, containing small integers
  * Outputs:
      * the string whose characters have the ASCII (see
        https://en.wikipedia.org/wiki/ASCII ) codes listed in v

Synopsis
========

  * Usage:
        ascii s
  * Inputs:
      * s
  * Outputs:
      * the list of (small integer) ASCII (see
        https://en.wikipedia.org/wiki/ASCII ) codes of the characters of s
+--------------------------------+
|i1 : ascii "abcdef"             |
|                                |
|o1 = {97, 98, 99, 100, 101, 102}|
|                                |
|o1 : List                       |
+--------------------------------+
|i2 : ascii oo                   |
|                                |
|o2 = abcdef                     |
+--------------------------------+
|i3 : first ascii "A"            |
|                                |
|o3 = 65                         |
+--------------------------------+

Ways to use ascii:
==================

  * "ascii(BasicList)"
  * "ascii(String)"
  * "ascii(ZZ)"

For the programmer
==================

The object ascii, is a compiled function.

utf8 -- encode and decode unicode utf-8-encoded strings
*******************************************************

Description
===========

Synopsis
========

  * Usage:
        utf8 x
  * Inputs:
      * x, a list, a list of small natural numbers to serve as
        character codes
  * Outputs:
      * a string, a string obtained by encoding the character
        codes in x according to the utf-8 encoding standard
+---------------------------------------+
|i1 : s = utf8 {119, 111, 51, 32, 25105}|
|                                       |
|o1 = wo3 我                             |
+---------------------------------------+

Synopsis
========

  * Usage:
        utf8 s
  * Inputs:
      * s, a string,
  * Outputs:
      * a list, a list of the integer codes obtained by decoding
        the string s according to the utf-8 encoding standard
+------------------------------+
|i2 : utf8 s                   |
|                              |
|o2 = {119, 111, 51, 32, 25105}|
|                              |
|o2 : List                     |
+------------------------------+

The two operations described above are inverse to each other.

The function utf8check can be used to verify that a string contains a valid
uft8-encoding of a sequence of unicode characters.  It returns null,
upon success, and signals an error otherwise.

+--------------------------------------------+
|i3 : try utf8check "你好" else "invalid"      |
+--------------------------------------------+
|i4 : try utf8check "\200\200" else "invalid"|
|                                            |
|o4 = invalid                                |
+--------------------------------------------+

See also
========

  * ascii -- ASCII character conversion

For the programmer
==================

The object utf8, is a compiled function.

substring -- extract part of a string
*************************************

Synopsis
========

  * Usage:
        substring(i, s)
        substring(i, n, s)
        substring(s, i, n)
        substring(s, i)
        substring((i, n), s)
  * Inputs:
      * i, an integer, starting index of substring
      * n, an integer, length of substring
      * s, a string,
  * Outputs:
      * a string,

Description
===========

The expressions substring(i, n, s), substring(s, i, n), and substring((i, n),
s) all return the substring that starts at index i and has n characters.

In other words, if $s=s_0s_1s_2\ldots s_k$, then the substring returned is $s_i
s_{i+1}\ldots s_{i+n-1}$.

Indices begin at zero, and a negative index is counted from the end of the
string. Requests for out-of-bound character positions are silently ignored.

+---------------------------------------------------------+
|i1 : s = "I love computing Groebner bases in Macaulay2.";|
+---------------------------------------------------------+
|i2 : substring(0, 5, s)                                  |
|                                                         |
|o2 = I lov                                               |
+---------------------------------------------------------+
|i3 : substring(s, -10, 5)                                |
|                                                         |
|o3 = Macau                                               |
+---------------------------------------------------------+
|i4 : substring(s, 100, 5)                                |
|                                                         |
|o4 =                                                     |
+---------------------------------------------------------+
|i5 : substring((3, 10), s)                               |
|                                                         |
|o5 = ove comput                                          |
+---------------------------------------------------------+

The expressions substring(i, s) and substring(s, i) return the substring that
starts at index i and continues to the end of the string.

In other words, if $s=s_0s_1s_2\ldots s_k$, then the substring returned is $s_i
s_{i+1}\ldots s_k$.

+-----------------------------------------------+
|i6 : substring(3, s)                           |
|                                               |
|o6 = ove computing Groebner bases in Macaulay2.|
+-----------------------------------------------+
|i7 : substring(s, -10)                         |
|                                               |
|o7 = Macaulay2.                                |
+-----------------------------------------------+

See also
========

  * lines -- split a string into lines
  * separate -- split a string into substrings using a regular
    expression
  * strings and nets -- an overview of strings and
    nets in Macaulay2
  * regular expressions -- syntax for regular
    expressions
  * utf8substring -- extract part of a utf8 string

Ways to use substring:
======================

  * "substring(Sequence,String)"
  * "substring(String,ZZ)"
  * "substring(String,ZZ,ZZ)"
  * "substring(ZZ,String)"
  * "substring(ZZ,ZZ,String)"

For the programmer
==================

The object substring, is a compiled function.

String _ ZZ -- get element from string
**************************************

Synopsis
========

  * Operator: _,
  * Usage:
        s_i
  * Inputs:
      * s
      * i
  * Outputs:
      * the i-th character of the string s

Description
===========

The characters are numbered starting with 0.  If  i is negative, then the i-th
entry counting from the end is provided. If i is out of range, an error is
signaled.

+---------------------------------+
|i1 : s = "what are you thinking?"|
|                                 |
|o1 = what are you thinking?      |
+---------------------------------+
|i2 : #s                          |
|                                 |
|o2 = 22                          |
+---------------------------------+
|i3 : s_-1, s_19, s_0             |
|                                 |
|o3 = (?, n, w)                   |
|                                 |
|o3 : Sequence                    |
+---------------------------------+

See also
========

  * strings and nets -- an overview of strings and
    nets in Macaulay2
  * String # ZZ -- get value from list, hash table,
    database, or string

Ways to use this method:
========================

  * String _ ZZ -- get element from string

String _ Sequence -- substring
******************************

Synopsis
========

  * Operator: _,
  * Usage:
        s_(i,j)
  * Inputs:
      * s
      * (i,j), a pair of integers
  * Outputs:
      * a string, the substring of s having length j and
        starting at the i-th character

Description
===========

+-----------------------------+
|i1 : s = "I did not do that!"|
|                             |
|o1 = I did not do that!      |
+-----------------------------+
|i2 : "." | s_(6,7) | "."     |
|                             |
|o2 = .not do .               |
+-----------------------------+

See also
========

  * strings and nets -- an overview of strings and
    nets in Macaulay2
  * substring -- extract part of a string
  * String | String -- join strings or nets

Ways to use this method:
========================

  * String _ Sequence -- substring

horizontalJoin -- join nets or strings horizontally
***************************************************

Synopsis
========

  * Usage:
        horizontalJoin L
  * Inputs:
      * L, a basic list, a list or sequence containing nets
        and/or strings
  * Outputs:
      * a net, or string obtained by concatenating the elements of
        L

Description
===========

If the list L contains only strings, then horizontalJoin acts like the command
concatenate.

+-----------------------------------------------------------------+
|i1 : L = {"some", "strings", "to", "join"}                       |
|                                                                 |
|o1 = {some, strings, to, join}                                   |
|                                                                 |
|o1 : List                                                        |
+-----------------------------------------------------------------+
|i2 : horizontalJoin L                                            |
|                                                                 |
|o2 = somestringstojoin                                           |
+-----------------------------------------------------------------+
|i3 : concatenate L                                               |
|                                                                 |
|o3 = somestringstojoin                                           |
+-----------------------------------------------------------------+
|i4 : demark(" ", L) --to insert spaces when concatenating strings|
|                                                                 |
|o4 = some strings to join                                        |
+-----------------------------------------------------------------+

Unlike concatenate, horizontalJoin can also be used on Net,s.

+-----------------------------------------------------------------------------+
|i5 : M = for i from 1 to 10 list if isPrime i then netList{toString i,       |
|                                                                             |
|        +-+  +-+    +--+    +--+                                             |
|o5 = {, |2|, |3|, , |5 |, , |7 |, , , }                                      |
|        +-+  +-+    +--+    +--+                                             |
|        |4|  |9|    |25|    |49|                                             |
|        +-+  +-+    +--+    +--+                                             |
|                                                                             |
|o5 : List                                                                    |
|-----------------------------------------------------------------------------|
|toString i^2}                                                                |
+-----------------------------------------------------------------------------+
|i6 : horizontalJoin M                                                        |
|                                                                             |
|     +-++-++--++--+                                                          |
|o6 = |2||3||5 ||7 |                                                          |
|     +-++-++--++--+                                                          |
|     |4||9||25||49|                                                          |
|     +-++-++--++--+                                                          |
+-----------------------------------------------------------------------------+

As the previous example shows, null arguments are allowed and ignored.

Nets and strings can be mixed in the input list. In this case, a string is
interpreted as a net of height one, with baseline below the string. The
operator Net ^ ZZ, can be used to lower or raise the baseline
of a string or net.

+-----------------------------------------------------------------------------+
|i7 : R = QQ[x];                                                              |
+-----------------------------------------------------------------------------+
|i8 : N1 = for i from 1 to 5 list if isPrime i then netList{x^i, i*x, i:x, i} |
|                                                                             |
|         +------+  +---------+     +---------------+                         |
|         | 2    |  | 3       |     | 5             |                         |
|o8 = {1, |x     |, |x        |, 4, |x              |}                        |
|         +------+  +---------+     +---------------+                         |
|         |2x    |  |3x       |     |5x             |                         |
|         +------+  +---------+     +---------------+                         |
|         |(x, x)|  |(x, x, x)|     |(x, x, x, x, x)|                         |
|         +------+  +---------+     +---------------+                         |
|         |2     |  |3        |     |5              |                         |
|         +------+  +---------+     +---------------+                         |
|                                                                             |
|o8 : List                                                                    |
|-----------------------------------------------------------------------------|
|else toString i                                                              |
+-----------------------------------------------------------------------------+
|i9 : horizontalJoin N1                                                       |
|                                                                             |
|      +------++---------+ +---------------+                                  |
|      | 2    || 3       | | 5             |                                  |
|o9 = 1|x     ||x        |4|x              |                                  |
|      +------++---------+ +---------------+                                  |
|      |2x    ||3x       | |5x             |                                  |
|      +------++---------+ +---------------+                                  |
|      |(x, x)||(x, x, x)| |(x, x, x, x, x)|                                  |
|      +------++---------+ +---------------+                                  |
|      |2     ||3        | |5              |                                  |
|      +------++---------+ +---------------+                                  |
+-----------------------------------------------------------------------------+
|i10 : N2 = for i from 1 to 5 list if isPrime i then netList{x^i, i*x, i:x, i}|
|                                                                             |
|          +------+  +---------+     +---------------+                        |
|          | 2    |  | 3       |     | 5             |                        |
|o10 = { , |x     |, |x        |,  , |x              |}                       |
|          +------+  +---------+     +---------------+                        |
|          |2x    |  |3x       |     |5x             |                        |
|          +------+  +---------+     +---------------+                        |
|          |(x, x)|  |(x, x, x)|     |(x, x, x, x, x)|                        |
|          +------+  +---------+     +---------------+                        |
|       1  |2     |  |3        |  4  |5              |                        |
|          +------+  +---------+     +---------------+                        |
|                                                                             |
|o10 : List                                                                   |
|-----------------------------------------------------------------------------|
|else (toString i)^-6                                                         |
+-----------------------------------------------------------------------------+
|i11 : horizontalJoin N2                                                      |
|                                                                             |
|       +------++---------+ +---------------+                                 |
|       | 2    || 3       | | 5             |                                 |
|o11 =  |x     ||x        | |x              |                                 |
|       +------++---------+ +---------------+                                 |
|       |2x    ||3x       | |5x             |                                 |
|       +------++---------+ +---------------+                                 |
|       |(x, x)||(x, x, x)| |(x, x, x, x, x)|                                 |
|       +------++---------+ +---------------+                                 |
|      1|2     ||3        |4|5              |                                 |
|       +------++---------+ +---------------+                                 |
+-----------------------------------------------------------------------------+

In the next example, we use horizontalJoin to concatenate the display of two
random integer matrices. The matrices are converted to nets first with the
command net.

+-------------------------------------------------------------+
|i12 : A = net matrix apply(3, i -> apply(3, j -> random(10)))|
|                                                             |
|o12 = | 8 1 3 |                                              |
|      | 7 8 3 |                                              |
|      | 3 7 8 |                                              |
+-------------------------------------------------------------+
|i13 : B = net matrix apply(3, i -> apply(3, j -> random(10)))|
|                                                             |
|o13 = | 8 5 7 |                                              |
|      | 8 5 2 |                                              |
|      | 3 6 3 |                                              |
+-------------------------------------------------------------+
|i14 : horizontalJoin(A,B)                                    |
|                                                             |
|o14 = | 8 1 3 || 8 5 7 |                                     |
|      | 7 8 3 || 8 5 2 |                                     |
|      | 3 7 8 || 3 6 3 |                                     |
+-------------------------------------------------------------+

Nested sequences in the input are automatically spliced. For instance, in the
next example the input is interpreted as \{A, B, A, B, A\}.

+---------------------------------------------------+
|i15 : horizontalJoin {(A, B), (A, B, (A))}         |
|                                                   |
|o15 = | 8 1 3 || 8 5 7 || 8 1 3 || 8 5 7 || 8 1 3 ||
|      | 7 8 3 || 8 5 2 || 7 8 3 || 8 5 2 || 7 8 3 ||
|      | 3 7 8 || 3 6 3 || 3 7 8 || 3 6 3 || 3 7 8 ||
+---------------------------------------------------+

However, the command horizontalJoin \{\{A, B\}, \{A, B, \{A\}\}\} will throw an
error, because nested lists are not automatically flattened.

Caveat
======

This command will work with no arguments, or all null arguments. The net
returned has zero height, and zero depth, which
might be unexpected.

See also
========

  * Net -- the class of all nets and strings
  * netList -- a table of boxes
  * Net | Net -- join strings or nets
  * Net || Net -- join nets or strings vertically
  * String | String -- join strings or nets
  * Net ^ ZZ -- raise a net or string
  * stack -- join nets or string vertically
  * strings and nets -- an overview of strings and
    nets in Macaulay2

Ways to use horizontalJoin:
===========================

  * "horizontalJoin(BasicList)"

For the programmer
==================

The object horizontalJoin, is a compiled function.

pad -- pad a string or net with spaces
**************************************

Synopsis
========

  * Usage:
        pad(s,n)
        pad(n,s)
  * Inputs:
      * s, a net,
      * n, an integer,

Description
===========

pad(s,n) pads the string or net s to length n with spaces on the right.

pad(n,s) pads the string or net s to length n with spaces on the left.

+--------------------------+
|i1 : pad(6, "foo")        |
|                          |
|o1 =    foo               |
+--------------------------+
|i2 : pad("foo", 6) | "bar"|
|                          |
|o2 = foo   bar            |
+--------------------------+

Ways to use pad:
================

  * "pad(Net,ZZ)"
  * "pad(String,ZZ)"
  * "pad(ZZ,Net)"
  * "pad(ZZ,String)"

For the programmer
==================

The object pad, is a method function.

stack -- join nets or string vertically
***************************************

Description
===========

stack(m,n,...) -- joins nets or strings by concatenating them vertically.  The
baseline of the result is the baseline of the first argument.

Nested sequences among the arguments are first spliced together.

If there are no arguments, then the net returned has zero height and zero
depth.  This might be unexpected.

Tab characters in any of the strings are first expanded into spaces, assuming
tab stops at every eighth column.

Null arguments are allowed and ignored.

See also
========

  * Net || Net -- join nets or strings vertically

Ways to use stack:
==================

  * "stack(BasicList)"

For the programmer
==================

The object stack, is a compiled function.

unstack -- list the rows of a net
*********************************

Description
===========

unstack x -- produces a list of strings, each containing the characters in one
row of the Net x.

The original net, adjusted so its height is 1, may be recovered with
stack. The individual strings will have all trailing spaces removed,
unless this would make all of them narrower than the original net, in which
case the first string retains its trailing spaces.

Ways to use unstack:
====================

  * "unstack(Net)"
  * unstack(String) (missing documentation)

For the programmer
==================

The object unstack, is a compiled function.

String -- the class of all strings
**********************************

Description
===========

A string is thing that contains a sequence of characters (bytes). A string is
normally entered as a sequence of characters surrounded by quotation marks.

+-----------+
|i1 : "abcd"|
|           |
|o1 = abcd  |
+-----------+

Strings involving special characters can be entered by using the backslash as
an escape character, see ".  For an alternate method of entering
strings with fewer escape sequences, see ///.

A net is a two-dimensional array of characters, and strings are regarded as a
type of net.

Functions and methods returning a string:
=========================================

  * "ascii(BasicList)" -- see ascii, -- ASCII character conversion
  * "ascii(ZZ)" -- see ascii, -- ASCII character conversion
  * "Database # String" -- see BasicList # ZZ, -- get
    value from list, hash table, database, or string
  * "String # ZZ" -- see BasicList # ZZ, -- get value
    from list, hash table, database, or string
  * "changeBase(String,ZZ,ZZ)" -- see changeBase, -- change
    integer base
  * "changeBase(ZZ,ZZ)" -- see changeBase, -- change integer
    base
  * "concatenate(BasicList)" -- see concatenate, -- join
    strings
  * "concatenate(Nothing)" -- see concatenate, -- join
    strings
  * "concatenate(String)" -- see concatenate, -- join
    strings
  * "concatenate(Symbol)" -- see concatenate, -- join
    strings
  * "concatenate(ZZ)" -- see concatenate, -- join strings
  * disassemble(FunctionBody) (missing documentation)
  * disassemble(FunctionClosure) (missing documentation)
  * disassemble(Pseudocode) (missing documentation)
  * disassemble(PseudocodeClosure) (missing documentation)
  * format -- format a string or a real number
  * "format(CC)" -- see format, -- format a string or a real
    number
  * "format(RR)" -- see format, -- format a string or a real
    number
  * "format(String)" -- see format, -- format a string or a real
    number
  * "get(File)" -- see get, -- get the contents of a file
  * "get(String)" -- see get, -- get the contents of a file
  * "getc(File)" -- see getc, -- get a byte
  * "getenv(String)" -- see getenv, -- get value of environment
    variable
  * html -- convert to HTML format
  * info -- convert hypertext to info format
  * mathML -- convert to MathML format
  * Net # ZZ (missing documentation)
  * "String | String" -- see Net | Net, -- join strings or
    nets
  * "String | ZZ" -- see Net | Net, -- join strings or nets
  * "ZZ | String" -- see Net | Net, -- join strings or nets
  * "pad(String,ZZ)" -- see pad, -- pad a string or net with spaces
  * "pad(ZZ,String)" -- see pad, -- pad a string or net with spaces
  * read(File) -- read from a file
  * read(File,ZZ) -- read from a file
  * read(Sequence) -- read from a file
  * read(String) -- read from a file
  * regexQuote -- escape special characters in regular
    expressions
  * replace(String,String,String),
    -- replace substrings matching a regular expression
  * "reverse(String)" -- see reverse, -- reverse a list,
    sequence, or string
  * String _ Sequence -- substring
  * String _ ZZ -- get element from string
  * "substring(Sequence,String)" -- see substring, -- extract
    part of a string
  * "substring(String,ZZ)" -- see substring, -- extract part
    of a string
  * "substring(String,ZZ,ZZ)" -- see substring, -- extract
    part of a string
  * "substring(ZZ,String)" -- see substring, -- extract part
    of a string
  * "substring(ZZ,ZZ,String)" -- see substring, -- extract
    part of a string
  * tex -- convert to $\TeX$ format
  * texMath -- convert to TeX math format
  * toExternalString -- convert to a readable string
  * toString -- convert to a string

Methods that use a string:
==========================

  * "# String" -- see # BasicList, -- length or cardinality
  * "Database #? String" -- see #?, -- check existence of value in a
    list, hash table, database, or string
  * "String #? ZZ" -- see #?, -- check existence of value in a list,
    hash table, database, or string
  * "about(String)" -- see about, -- search the documentation
  * "apply(BasicList,String,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * "apply(String,BasicList,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * "apply(String,String,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * "apply(String,Function)" -- see apply(BasicList,Function),
    -- apply a function to each element of a
    list
  * "apropos(String)" -- see apropos, -- symbols matching a
    pattern
  * "arXiv(String)" -- see arXiv (SimpleDoc), -- link to an arXiv
    article
  * "arXiv(String,String)" -- see arXiv (SimpleDoc), -- link to an
    arXiv article
  * "ascii(String)" -- see ascii, -- ASCII character conversion
  * "autoload(Symbol,String)" -- see autoload, -- arrange for a
    function to be loaded automatically
  * "capture(String)" -- see capture, -- evaluate Macaulay2 code
    and capture the output
  * "changeBase(String,ZZ)" -- see changeBase, -- change
    integer base
  * "check(List,String)" -- see check, -- perform tests of a
    package
  * "check(String)" -- see check, -- perform tests of a package
  * "check(ZZ,String)" -- see check, -- perform tests of a package
  * copyDirectory(String,String)
  * copyFile(String,String)
  * "depth(String)" -- see depth, -- depth of a net
  * Dictionary # String (missing documentation)
  * Dictionary #? String (missing documentation)
  * "dismiss(String)" -- see dismiss, -- dismiss a package
  * "doc(String)" -- see doc (SimpleDoc), -- a simple documentation
    function
  * "makeDocumentTag(String)" -- see DocumentTag, -- the
    class of all document tags
  * "endPackage(String)" -- see endPackage, -- end a new
    package
  * "EXAMPLE(String)" -- see EXAMPLE, -- hypertext EXAMPLE item
  * "export(String)" -- see export, -- export symbols from a
    package
  * "exportFrom(Package,String)" -- see exportFrom, -- export
    symbols from a package's private dictionary
  * "exportFrom(String,List)" -- see exportFrom, -- export
    symbols from a package's private dictionary
  * "exportFrom(String,String)" -- see exportFrom, -- export
    symbols from a package's private dictionary
  * "exportMutable(String)" -- see exportMutable, --
    export mutable symbols from a package
  * "File << String" -- see File << Thing, -- print to a
    file
  * "String << Thing" -- see File << Thing, -- print to a
    file
  * "fileExecutable(String)" -- see fileExecutable,
  * fileMode(String) -- get file mode
  * fileMode(ZZ,String) -- set file mode
  * "fileReadable(String)" -- see fileReadable,
  * "fileWritable(String)" -- see fileWritable,
  * "findFiles(String)" -- see findFiles, -- find files
    recursively
  * "findProgram(String)" -- see findProgram, -- load
    external program
  * "findProgram(String,List)" -- see findProgram, -- load
    external program
  * "findProgram(String,String)" -- see findProgram, -- load
    external program
  * "generateAssertions(String)" -- see generateAssertions,
    -- generate assert statements from experimental input
  * "getWWW(String)" -- see getWWW, -- get a web page
  * "getWWW(String,Nothing)" -- see getWWW, -- get a web page
  * "getWWW(String,String)" -- see getWWW, -- get a web page
  * "height(String)" -- see height, -- height of a net
  * "help(String)" -- see help, -- view documentation nodes
  * httpHeaders(String) -- prepend http headers
    to a string
  * ideal(String) (Classic) -- make an ideal using
    classic Macaulay syntax
  * "importFrom(Package,String)" -- see importFrom, -- import
    symbols to the current private dictionary
  * "importFrom(String,List)" -- see importFrom, -- import
    symbols to the current private dictionary
  * "importFrom(String,String)" -- see importFrom, -- import
    symbols to the current private dictionary
  * info(String) (missing documentation)
  * "installPackage(String)" -- see installPackage, --
    load and install a package and its documentation
  * "isc(String)" -- see isc (OnlineLookup), -- ISC lookup
  * "iterator(String)" -- see iterator, -- get an iterator
  * length(String) -- length of a string
  * "lines(String)" -- see lines, -- split a string into lines
  * "lines(String,String)" -- see lines, -- split a string into
    lines
  * linkFile(String,String) -- make a new
    link to a file
  * "loadPackage(String)" -- see loadPackage, -- load a
    package
  * makeDirectory(String) -- make a directory
  * "match(List,String)" -- see match, -- regular expression
    matching
  * "match(String,String)" -- see match, -- regular expression
    matching
  * matrix(String) (Classic) -- make a matrix using
    classic Macaulay syntax
  * monomialIdeal(String) (Classic) -- make a
    monomial ideal using classic Macaulay syntax
  * "moveFile(String)" -- see moveFile(String,String),
  * moveFile(String,String)
  * "needsPackage(String)" -- see needsPackage, -- load a
    package if not already loaded
  * Net == String (missing documentation)
  * "String ^ ZZ" -- see Net ^ ZZ, -- raise a net or string
  * net(String) -- convert a string to a net
  * "NetFile << String" -- see NetFile, -- the class of all net
    files
  * "newPackage(String)" -- see newPackage, -- the preamble
    of a package
  * "oeis(String)" -- see oeis (OnlineLookup), -- OEIS lookup
  * "openDatabase(String)" -- see openDatabase, -- open a
    database file
  * "openDatabaseOut(String)" -- see openDatabaseOut, --
    open a database file for writing
  * openIn(String) -- open an input file
  * "openInOut(String)" -- see openInOut, -- open an input
    output file
  * openListener(String) -- open a port for
    listening
  * openOut(String) -- open an output file
  * openOutAppend(String) -- open an output
    file for appending
  * "pack(String,ZZ)" -- see pack, -- pack elements of a list or
    string into several shorter lists or strings
  * "pack(ZZ,String)" -- see pack, -- pack elements of a list or
    string into several shorter lists or strings
  * "package(String)" -- see package, -- get containing package
  * "packageTemplate(String)" -- see packageTemplate (SimpleDoc),
    -- a template for a package
  * poly(String) (Classic) -- make a polynomial using
    classic Macaulay syntax
  * "profile(String,Function)" -- see profile, -- profile a
    function
  * "readPackage(String)" -- see readPackage, -- read the
    package preamble
  * "regex(String,String)" -- see regex, -- evaluate a regular
    expression search
  * "regex(String,ZZ,String)" -- see regex, -- evaluate a regular
    expression search
  * "regex(String,ZZ,ZZ,String)" -- see regex, -- evaluate a
    regular expression search
  * "regexQuote(String)" -- see regexQuote, -- escape special
    characters in regular expressions
  * registerFinalizer(Thing,String) (missing documentation)
  * "remove(Database,String)" -- see remove, -- remove an entry
    from a mutable hash table, list, or database
  * "runProgram(Program,String)" -- see runProgram, -- run an
    external program
  * "runProgram(Program,String,String)" -- see runProgram, --
    run an external program
  * "runProgram(String,String)" -- see runProgram, -- run an
    external program
  * "saveSession(String)" -- see saveSession (Polyhedra), --
    save the actual Polyhedra session to a file
  * "scanLines(Function,String)" -- see scanLines, -- apply a
    function to each line of a file
  * searchPath(List,String) -- search a
    path for a file
  * "searchPath(String)" -- see searchPath(List,String),
    -- search a path for a file
  * "select(String,String)" -- see select(String,String,String),
    -- select and reformat substrings
    matching a regular expression
  * select(String,String,String),
    -- select and reformat substrings matching a regular expression
  * "separate(String)" -- see separate, -- split a string into
    substrings using a regular expression
  * "separate(String,String)" -- see separate, -- split a
    string into substrings using a regular expression
  * "separate(String,ZZ,String)" -- see separate, -- split a
    string into substrings using a regular expression
  * "setRandomSeed(String)" -- see setRandomSeed, -- set
    starting point for random number generator
  * "splitWWW(String)" -- see splitWWW, -- separate an http
    response into header and body
  * "stacksProject(String,String)" -- see stacksProject (SimpleDoc),
    -- link to a Stacks Project tag
  * String .. String -- a sequence of consecutive
    strings
  * String ..< String -- a sequence of
    consecutive strings, not including the endpoint
  * String == Net (missing documentation)
  * String == String (missing documentation)
  * String ^ Sequence -- vertically stacked copies of
    a string
  * String _ Ring -- get a ring variable by name
  * symlinkDirectory(String,String)
    -- make symbolic links for all files
    in a directory tree
  * "tally(String)" -- see tally, -- tally the elements of a list,
    sequence, array, or string
  * "tests(String)" -- see tests, -- locate a package's tests
  * "tests(ZZ,String)" -- see tests, -- locate a package's tests
  * "toList(String)" -- see toList, -- create a list
  * "toSequence(String)" -- see toSequence, -- convert to
    sequence
  * "uninstallPackage(String)" -- see uninstallPackage,
    -- uninstall a package and remove its documentation
  * unstack(String) (missing documentation)
  * "new URL from String" -- see URL, -- a type representing a URL
  * "urlEncode(String)" -- see urlEncode, -- URL encoding
  * value(String) -- evaluate a string
  * "viewHelp(String)" -- see viewHelp, -- view online
    documentation in a web browser
  * /// Command \ String /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// Function \ String /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "String / Command" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "String / Function" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "width(String)" -- see width(Net), -- width of a net
  * "wikipedia(String)" -- see wikipedia (SimpleDoc), -- link
    to a Wikipedia article
  * "wikipedia(String,String)" -- see wikipedia (SimpleDoc), --
    link to a Wikipedia article

For the programmer
==================

The object String, is a type, with ancestor classes
Net < Thing.

net(String) -- convert a string to a net
****************************************

Synopsis
========

  * Function: net,
  * Usage:
        net s
  * Inputs:
      * s, a string,
  * Outputs:
      * a net, formed by stacking the lines of the string s
        vertically

Description
===========

Tab characters are converted to spaces, with a tab stop at every 8-th column.

In the following examples we can use peek to see the exact shape of the nets
produced.

+-----------------------------------+
|i1 : net "line 1\nline 2\nline 3\n"|
|                                   |
|o1 = line 1                        |
|     line 2                        |
|     line 3                        |
+-----------------------------------+
|i2 : peek oo                       |
|                                   |
|     +------+                      |
|o2 = |line 1|                      |
|     |line 2|                      |
|     |line 3|                      |
|     |      |                      |
|     +------+                      |
+-----------------------------------+
|i3 : net ""                        |
|                                   |
|o3 =                               |
+-----------------------------------+
|i4 : peek oo                       |
|                                   |
|     ++                            |
|o4 = ||                            |
|     ++                            |
+-----------------------------------+
|i5 : net "\n"                      |
|                                   |
|o5 =                               |
+-----------------------------------+
|i6 : peek oo                       |
|                                   |
|     ++                            |
|o6 = ||                            |
|     ||                            |
|     ++                            |
+-----------------------------------+
|i7 : net "\n\n\ta"                 |
|                                   |
|o7 =                               |
|                                   |
|             a                     |
+-----------------------------------+
|i8 : peek oo                       |
|                                   |
|     +---------+                   |
|o8 = |         |                   |
|     |         |                   |
|     |        a|                   |
|     +---------+                   |
+-----------------------------------+

See also
========

  * peek -- examine contents of an object
  * stack -- join nets or string vertically
  * unstack -- list the rows of a net

Ways to use this method:
========================

  * net(String) -- convert a string to a net

toString -- convert to a string
*******************************

Synopsis
========

  * Usage:
        toString x
  * Inputs:
      * x, any Macaulay2 object
  * Outputs:
      * a string, a string representation of x

Description
===========

Sometimes the string representation is just the name. See also
toExternalString, which will try to convert x to a string
that can be read back into the program later.
+------------------------------------------+
|i1 : toString {1,4,a,f,212312,2.123243242}|
|                                          |
|o1 = {1, 4, a, f, 212312, 2.12324}        |
+------------------------------------------+
If a ring has a global name, then toString returns this name.
+------------------------------------------------+
|i2 : R = QQ[x_1..x_5];                          |
+------------------------------------------------+
|i3 : toString R                                 |
|                                                |
|o3 = R                                          |
+------------------------------------------------+
|i4 : toExternalString R                         |
|                                                |
|o4 = QQ[x_1..x_5, Degrees => {5:1}, Heft => {1}]|
+------------------------------------------------+
|i5 : toString(QQ[a])                            |
|                                                |
|o5 = QQ[a]                                      |
+------------------------------------------------+
Matrices and ring elements are linearized
+----------------------------------------------------+
|i6 : toString (x_1^3-3/4*x_5*x_3)                   |
|                                                    |
|o6 = x_1^3-(3/4)*x_3*x_5                            |
+----------------------------------------------------+
|i7 : toString vars R                                |
|                                                    |
|o7 = matrix {{x_1, x_2, x_3, x_4, x_5}}             |
+----------------------------------------------------+
|i8 : toExternalString vars R                        |
|                                                    |
|o8 = map(R^1,R^{5:{-1}},{{x_1, x_2, x_3, x_4, x_5}})|
+----------------------------------------------------+

See also
========

  * toExternalString -- convert to a readable string
  * value -- evaluate

For the programmer
==================

The object toString, is a method function with a single argument.

toExternalString -- convert to a readable string
************************************************

Synopsis
========

  * Usage:
        toExternalString x
  * Inputs:
      * x, any Macaulay2 object
  * Outputs:
      * a string, a string representation of x, which can be
        used, in conjunction with value, to read the object back
        into the program later

Description
===========

See also toString, which simply converts x to a string that can
be displayed meaningfully.
+------------------------------------------+
|i1 : toString {1,4,a,f,212312,2.123243242}|
|                                          |
|o1 = {1, 4, a, f, 212312, 2.12324}        |
+------------------------------------------+
+------------------------------------------------+
|i2 : R = QQ[x_1..x_5];                          |
+------------------------------------------------+
|i3 : toExternalString R                         |
|                                                |
|o3 = QQ[x_1..x_5, Degrees => {5:1}, Heft => {1}]|
+------------------------------------------------+
Matrices and ring elements are linearized
+------------------------+
|i4 : x_1^3-3/4*x_5*x_3  |
|                        |
|      3   3             |
|o4 = x  - -x x          |
|      1   4 3 5         |
|                        |
|o4 : R                  |
+------------------------+
|i5 : toExternalString oo|
|                        |
|o5 = x_1^3-(3/4)*x_3*x_5|
+------------------------+
|i6 : value oo           |
|                        |
|      3   3             |
|o6 = x  - -x x          |
|      1   4 3 5         |
|                        |
|o6 : R                  |
+------------------------+

Caveat
======

Not everything can be converted to a string in such a way that it can be read
back into the program later.

See also
========

  * toString -- convert to a string
  * value -- evaluate

For the programmer
==================

The object toExternalString, is a method function with a single argument.

/// -- delineate a string with slashes
**************************************

This method for entering a string involves no escape characters, so it can be
used for easily inserting large chunks of text into a string without treating
the characters \ and " specially. A series of more than 3 slashes can be
represented before the end of the string by doubling all but the last two, and
a series of 1 or more slashes can be represented at the end of the string by
doubling each of them; this allows an arbitrary string to be represented.
+--------------------------------+
|i1 : /// \ " ///                |
|                                |
|o1 =  \ "                       |
+--------------------------------+
|i2 : ascii oo                   |
|                                |
|o2 = {32, 92, 32, 34, 32}       |
|                                |
|o2 : List                       |
+--------------------------------+
|i3 : ///-- //// -- /////////    |
|                                |
|o3 = -- /// -- ///              |
+--------------------------------+
|i4 : ///-- ////// -- ///////////|
|                                |
|o4 = -- //// -- ////            |
+--------------------------------+
|i5 : //////////////             |
|                                |
|o5 = ////                       |
+--------------------------------+

See also
========

  * String -- the class of all strings
  * " -- delineate a string with quotation marks
  * ascii -- ASCII character conversion

" -- delineate a string with quotation marks
********************************************

This method for entering a string involves the use of backslashes as escape
characters.

      \n             newline
      \f             form feed
      \r             return
      \\             \
      \"             "
      \a             audible bell
      \b             backspace
      \e, \E         escape
      \t             tab
      \v             vertical tab
      \nnn           ascii character with octal value nnn
      \xnn           ascii character with hex value nn
      \unnnn         unicode character with hex value nnnn, encoded with utf-8
+-----------------------------------------------------------------------------+
|i1 : x = " \" \f \r \\ \a\b\e\E\t\v \013 \x0b \u4f60 ";                      |
+-----------------------------------------------------------------------------+
|i2 : ascii x                                                                 |
|                                                                             |
|o2 = {32, 34, 32, 12, 32, 13, 32, 92, 32, 7, 8, 27, 27, 9, 11, 32, 11, 32,   |
|     ------------------------------------------------------------------------|
|     11, 32, 228, 189, 160, 32}                                              |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : utf8 x                                                                  |
|                                                                             |
|o3 = {32, 34, 32, 12, 32, 13, 32, 92, 32, 7, 8, 27, 27, 9, 11, 32, 11, 32,   |
|     ------------------------------------------------------------------------|
|     11, 32, 20320, 32}                                                      |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * String -- the class of all strings
  * /// -- delineate a string with slashes
  * ascii -- ASCII character conversion
  * utf8 -- encode and decode unicode utf-8-encoded strings

Net -- the class of all nets and strings
****************************************

Description
===========

A net is a generalization of a string that is designed to facilitate
two-dimensional printing on ascii terminals.  It consists of a rectangular
array of characters subdivided horizontally by an imaginary baseline.

Operations on nets also accept strings by interpreting a string as a rectangle
of height one with the baseline just below it.  In fact, the parent of
String, is Net.

Multiple nets per line can be sent to an output file with <<, but
care must be taken to use endl, to end lines, for nets with new
line characters embedded in them will be displayed in an unexpected way.

Warning: if so many characters are written to a file that an internal buffer is
filled before the line ends or first net is seen, then the buffer will be
flushed, and writing a net subsequently will produce an unexpected result.

Types of net:
=============

  * String -- the class of all strings

Functions and methods returning a net:
======================================

  * generateAssertions -- generate assert statements
    from experimental input
  * "horizontalJoin(BasicList)" -- see horizontalJoin, --
    join nets or strings horizontally
  * net -- format for printing, as a net
  * Net ^ ZZ -- raise a net or string
  * "String ^ ZZ" -- see Net ^ ZZ, -- raise a net or string
  * Net | Net -- join strings or nets
  * Net || Net -- join nets or strings vertically
  * peek -- examine contents of an object
  * peek' -- examine contents of an object
  * "stack(BasicList)" -- see stack, -- join nets or string
    vertically
  * String ^ Sequence -- vertically stacked copies of
    a string

Methods that use a net:
=======================

  * # Net (missing documentation)
  * "capture(Net)" -- see capture, -- evaluate Macaulay2 code
    and capture the output
  * "depth(Net)" -- see depth, -- depth of a net
  * "File << Net" -- see File << Thing, -- print to a file
  * "height(Net)" -- see height, -- height of a net
  * Net # ZZ (missing documentation)
  * Net #? ZZ (missing documentation)
  * Net == Net (missing documentation)
  * Net == String (missing documentation)
  * "NetFile << Net" -- see NetFile, -- the class of all net
    files
  * "pad(Net,ZZ)" -- see pad, -- pad a string or net with spaces
  * "pad(ZZ,Net)" -- see pad, -- pad a string or net with spaces
  * String == Net (missing documentation)
  * "unstack(Net)" -- see unstack, -- list the rows of a net
  * width(Net) -- width of a net

For the programmer
==================

The object Net, is a type, with ancestor class
Thing.

net -- format for printing, as a net
************************************

Synopsis
========

  * Usage:
        net o
  * Inputs:
      * x, a thing,
  * Outputs:
      * a net, obtained by formatting o for printing

Description
===========

This function is the primary function called upon by <<, to format
expressions for printing. The default method provided by the system is to
convert o to an Expression, with expression,
and then to convert that to a Net.

A new method for formatting expressions of type T may be installed as follows:

+-----------------+
|                 |
|net T := x -> ...|
+-----------------+

The function provided by the user should return a Net, or a
String.

There are various such methods for formatting, but we don't document them
separately.

See also
========

  * String -- the class of all strings
  * Expression -- the class of all expressions
  * AfterPrint -- top level method applied after printing
  * toString -- convert to a string
  * toExternalString -- convert to a readable string
  * expression -- convert to an expression

Ways to use net:
================

  * "net(Thing)"
  * net(String) -- convert a string to a net

For the programmer
==================

The object net, is a method function with a single argument.

width(Net) -- width of a net
****************************

Synopsis
========

  * Function: width,

Description
===========

width n -- the width of a net n.

The width of a net is the length of its longest row, if any, else 0.
+---------------------------+
|i1 : "a c" || "-" || "adsf"|
|                           |
|o1 = a c                   |
|     -                     |
|     adsf                  |
+---------------------------+
|i2 : width oo              |
|                           |
|o2 = 4                     |
+---------------------------+

See also
========

  * depth -- depth of a net
  * height -- height of a net

Ways to use this method:
========================

  * width(Net) -- width of a net
  * "width(String)"

height -- height of a net
*************************

Description
===========

height n -- the height of a net n.

The height of a net is the number of rows of characters it has above the
baseline.  It may be a negative number, but the depth plus the height is always
the total number of rows, which is not negative.

See also
========

  * Net -- the class of all nets and strings
  * depth -- depth of a net

Ways to use height:
===================

  * "height(Net)"
  * "height(String)"
  * height(File) -- get window height

For the programmer
==================

The object height, is a method function.

depth -- depth of a net
***********************

Description
===========

depth n -- the depth of a net or string n.

The depth of a net is the number of rows of characters it has below the
baseline.  It may be a negative number, but the depth plus the height is always
the total number of rows, which is not negative.

See also
========

  * Net -- the class of all nets and strings
  * height -- height of a net

Ways to use depth:
==================

  * "depth(Net)"
  * "depth(String)"

For the programmer
==================

The object depth, is a method function.

lists and sequences -- a detailed overview of lists and sequences in Macaulay2
******************************************************************************

This page gives an overview of the use of lists of all types, including:

basic lists (of class BasicList), visible lists (of class
VisibleList), lists (of class List), sequences
(of class Sequence), arrays (of class Array),
angle bar lists (of class AngleBarList), and mutable lists
(of class MutableList).

The sections of the overview are, in order:

Creating lists; kinds of lists.  Elements and indexing.  Nested lists.  Ranges
and repetitions.  Manipulating lists and sequences.  Mapping over lists.
Conditional expressions; selecting elements matching a criterion.

Links to individual documentation pages for the functions described in this
article are collected in an alphabetized list at the very end of the page.

Creating lists; kinds of lists.

To create a list, use curly braces around a comma-separated series of elements.

+--------------------+
|i1 : L = {a,b,c,d,e}|
|                    |
|o1 = {a, b, c, d, e}|
|                    |
|o1 : List           |
+--------------------+

Sequences are created and displayed using parentheses instead of braces.

+--------------------+
|i2 : S = (a,b,c,d,e)|
|                    |
|o2 = (a, b, c, d, e)|
|                    |
|o2 : Sequence       |
+--------------------+

Sequences are implemented in a more efficient way than lists, since a sequence
is created every time a function is called with more than one argument. On the
other hand, parentheses are also used for grouping algebraic expressions. This
complicates some tasks, such as creating a sequence of length 1.

+-------------+
|i3 : ()      |
|             |
|o3 = ()      |
|             |
|o3 : Sequence|
+-------------+
|i4 : (1,2)   |
|             |
|o4 = (1, 2)  |
|             |
|o4 : Sequence|
+-------------+
|i5 : (1)     |
|             |
|o5 = 1       |
+-------------+

The functions toList, and toSequence, which
convert between lists and sequences, may be useful here.

+-------------------+
|i6 : toSequence {1}|
|                   |
|o6 = 1 : (1)       |
|                   |
|o6 : Sequence      |
+-------------------+

Lists can be used as vectors, provided their elements are the sorts of things
that can be added and multiplied.

+----------------------------+
|i7 : 10000*{3,4,5} + {1,2,3}|
|                            |
|o7 = {30001, 40002, 50003}  |
|                            |
|o7 : List                   |
+----------------------------+

An array is another type of list, created and displayed using square brackets.
Unlike lists and sequences, arrays can't be used as vectors. Their main use is
notational; for example, they appear in the construction of polynomial rings.

+-------------------+
|i8 : v = [1,2,3]   |
|                   |
|o8 = [1, 2, 3]     |
|                   |
|o8 : Array         |
+-------------------+
|i9 : ZZ[a,b,c]     |
|                   |
|o9 = ZZ[a..c]      |
|                   |
|o9 : PolynomialRing|
+-------------------+

An angle bar list is another type of list, created and displayed using angle
bars.  They are used in much the same way as arrays are.

+-------------------+
|i10 : v = <|1,2,3|>|
|                   |
|o10 = <|1, 2, 3|>  |
|                   |
|o10 : AngleBarList |
+-------------------+
|i11 : v#1          |
|                   |
|o11 = 2            |
+-------------------+

Lists, sequences, and arrays are the three examples of what we call visible
lists, which constitute the class VisibleList. Many
functions are defined to act uniformly on visible lists. There is a type of
list more general than a visible list, which we call a BasicList.
Basic lists are a secure choice for defining new datatypes, since
the many functions that act on visible lists do not act on basic lists. Here we
illustrate how to create a new type of basic list, in this case called
Container.

+---------------------------------------+
|i12 : Container = new Type of BasicList|
|                                       |
|o12 = Container                        |
|                                       |
|o12 : Type                             |
+---------------------------------------+
|i13 : t = new Container from {a,b}     |
|                                       |
|o13 = Container{a, b}                  |
|                                       |
|o13 : Container                        |
+---------------------------------------+

We can then declare a new method for the operator ++, that will join
two Containers:

+-------------------------------------+
|i14 : Container ++ Container := join;|
+-------------------------------------+
|i15 : t ++ t                         |
|                                     |
|o15 = Container{a, b, a, b}          |
|                                     |
|o15 : Container                      |
+-------------------------------------+

Basic lists are normally immutable; that is, no element can be replaced, added,
or removed. (Functions like append, and the many others
described in the Manipulating lists and sequences section, will return a new
list in Macaulay2, as a general rule, rather than modify the existing list.)

However, there is a certain type of basic list, called a mutable list (of class
MutableList), whose elements can be changed. This allows
the possibility of creating circular structures that would cause a print
routine to go into an infinite loop. To avoid such infinite loops, the contents
of mutable lists are not printed. Instead, use peek, to display the
elements in a controlled way.

+--------------------------------------+
|i16 : A = new MutableList from {a,b,c}|
|                                      |
|o16 = MutableList{...3...}            |
|                                      |
|o16 : MutableList                     |
+--------------------------------------+
|i17 : peek A                          |
|                                      |
|o17 = MutableList{a, b, c}            |
+--------------------------------------+
|i18 : A#2 = 1234;                     |
+--------------------------------------+
|i19 : A                               |
|                                      |
|o19 = MutableList{...3...}            |
|                                      |
|o19 : MutableList                     |
+--------------------------------------+
|i20 : peek A                          |
|                                      |
|o20 = MutableList{a, b, 1234}         |
+--------------------------------------+

Because the contents of mutable lists are not printed, they can be used as
containers for big things one doesn't want to print. Although any mutable list
can be used in this way, there is a a special type of mutable list called a
Bag, which is designed for this purpose. When printed, the bag
displays only a little information about its contents.

+-----------------------------------------------------------------------------+
|i21 : r = Bag {100!}; r                                                      |
|                                                                             |
|o22 = -*a bagged integer*-                                                   |
|                                                                             |
|o22 : Bag                                                                    |
+-----------------------------------------------------------------------------+
|i23 : q = Bag {1/100!}; q                                                    |
|                                                                             |
|o24 = -*a bagged rational number*-                                           |
|                                                                             |
|o24 : Bag                                                                    |
+-----------------------------------------------------------------------------+
|i25 : unbag q                                                                |
|                                                                             |
|                                                                             |
|o25 = -----------------------------------------------------------------------|
|      93326215443944152681699238856266700490715968264381621468592963895217599|
|      =======================================================================|
|              1                                                              |
|      -----------------------------------------------------------------------|
|      99322991560894146397615651828625369792082722375825118521091686400000000|
|      =======================================================================|
|      ----------------                                                       |
|      0000000000000000                                                       |
|                                                                             |
|o25 : QQ                                                                     |
+-----------------------------------------------------------------------------+

The hierarchy of types mentioned above is summarized here using
showStructure,:

+----------------------------------------------------------------------------+
|i26 : showStructure(List,Sequence,Array,Container,MutableList,Bag,BasicList)|
|                                                                            |
|o26 = Thing : BasicList : Container                                         |
|                          MutableList : Bag                                 |
|                          VisibleList : Array                               |
|                                        List                                |
|                                        Sequence                            |
|                                                                            |
|o26 : Descent                                                               |
+----------------------------------------------------------------------------+

Elements and indexing.

We retrieve the length of a list with the operator #, or with the
function length.

+----------------------------------------------------------+
|i27 : L = {926, 621, 429, 67, 594, 904, 264, 18, 35, 961};|
+----------------------------------------------------------+
|i28 : #L                                                  |
|                                                          |
|o28 = 10                                                  |
+----------------------------------------------------------+
|i29 : length L                                            |
|                                                          |
|o29 = 10                                                  |
+----------------------------------------------------------+

The expression $L\#n$ returns the $n$th element of $L$. The elements are
numbered consecutively starting with 0. Alternatively, they are numbered
consecutively ending with -1.

+----------+
|i30 : L#0 |
|          |
|o30 = 926 |
+----------+
|i31 : L#2 |
|          |
|o31 = 429 |
+----------+
|i32 : L#-1|
|          |
|o32 = 961 |
+----------+

The _, operator is similar to #, except that it can also
take a list or range of indices. However, it may only be used with visible
lists.

+---------------+
|i33 : L_1      |
|               |
|o33 = 621      |
+---------------+
|i34 : L_{3,6}  |
|               |
|o34 = {67, 264}|
|               |
|o34 : List     |
+---------------+

The functions first, and last, retrieve the first and
last elements of a list.

+-------------+
|i35 : first L|
|             |
|o35 = 926    |
+-------------+
|i36 : last L |
|             |
|o36 = 961    |
+-------------+

Omitting an element of a list causes the symbol null, to be
inserted in its place. When the value of an expression is null, like when we
ask for A#2 in the next example, the output line doesn't appear at all.

+---------------------+
|i37 : A = {3,4,,5}   |
|                     |
|o37 = {3, 4, , 5}    |
|                     |
|o37 : List           |
+---------------------+
|i38 : peek A         |
|                     |
|o38 = {3, 4, null, 5}|
+---------------------+
|i39 : A#2            |
+---------------------+

Ranges and repetitions.

The operator .., can be used to create sequences of numbers,
sequences of subscripted variables, and so on.

+--------------------------------------------------------------+
|i40 : 1 .. 5, x_1 .. x_5, a .. e                              |
|                                                              |
|o40 = ((1, 2, 3, 4, 5), (x , x , x , x , x ), (a, b, c, d, e))|
|                          1   2   3   4   5                   |
|                                                              |
|o40 : Sequence                                                |
+--------------------------------------------------------------+

The operator ZZ _colon_ Thing, creates a sequence by
replicating an element a given number of times.

+------------------------------------------+
|i41 : 12:a                                |
|                                          |
|o41 = (a, a, a, a, a, a, a, a, a, a, a, a)|
|                                          |
|o41 : Sequence                            |
+------------------------------------------+

Replicating something once is another way to create a sequence of length 1,
which cannot be entered by simply typing parentheses.

+--------------+
|i42 : 1:a     |
|              |
|o42 = 1 : (a) |
|              |
|o42 : Sequence|
+--------------+

Both .., and _colon_, produce sequences, and may not
behave as expected with respect to nesting. For instance, to create the list
\{3, 4, 5, 6, 9, 12, 12, 12\}, the following command will not work:

+-------------------------------------+
|i43 : A = {3 .. 6, 9, 3:12}          |
|                                     |
|o43 = {(3, 4, 5, 6), 9, (12, 12, 12)}|
|                                     |
|o43 : List                           |
+-------------------------------------+

Instead, we get a list of length 3, some of whose elements are sequences. This
is easily resolved with splice.

+---------------------------------+
|i44 : A = splice {3..6, 9, 3:12} |
|                                 |
|o44 = {3, 4, 5, 6, 9, 12, 12, 12}|
|                                 |
|o44 : List                       |
+---------------------------------+

However, many operators and functions will automatically splice lists for you.
Two examples are the array of variables defining a polynomial ring, and the
indices passed to the _, operator.

+---------------------------------+
|i45 : QQ[a..c,x_1..x_4]          |
|                                 |
|o45 = QQ[a..c, x ..x ]           |
|                1   4            |
|                                 |
|o45 : PolynomialRing             |
+---------------------------------+
|i46 : L_{1..3,-3..-1}            |
|                                 |
|o46 = {621, 429, 67, 18, 35, 961}|
|                                 |
|o46 : List                       |
+---------------------------------+

Nested lists.

When the elements of a list are themselves lists, we call it a nested list.

+------------------------------+
|i47 : A = {{a,b,c},{d,{e,f}}} |
|                              |
|o47 = {{a, b, c}, {d, {e, f}}}|
|                              |
|o47 : List                    |
+------------------------------+
|i48 : #A                      |
|                              |
|o48 = 2                       |
+------------------------------+
|i49 : #(first A)              |
|                              |
|o49 = 3                       |
+------------------------------+

One level of nesting may be eliminated with flatten.

+--------------------------+
|i50 : flatten A           |
|                          |
|o50 = {a, b, c, d, {e, f}}|
|                          |
|o50 : List                |
+--------------------------+

The function splice, acts analogously on sequences, removing
those pairs of parentheses that are one level inward.

+----------------------------------------------+
|i51 : splice (a, (b, c), (d, (e, f, (g, h))) )|
|                                              |
|o51 = (a, b, c, d, (e, f, (g, h)))            |
|                                              |
|o51 : Sequence                                |
+----------------------------------------------+

To remove all layers of nesting at once, use deepSplice.

+--------------------------------------------------+
|i52 : deepSplice (a, (b, c), (d, (e, f, (g, h))) )|
|                                                  |
|o52 = (a, b, c, d, e, f, g, h)                    |
|                                                  |
|o52 : Sequence                                    |
+--------------------------------------------------+

A table is a list whose elements are lists all of the same length. The inner
lists are regarded as rows when the table is displayed as a two-dimensional
array with MatrixExpression.

+------------------------------------------+
|i53 : T = {{a,1},{b,2},{c,3}}             |
|                                          |
|o53 = {{a, 1}, {b, 2}, {c, 3}}            |
|                                          |
|o53 : List                                |
+------------------------------------------+
|i54 : isTable T                           |
|                                          |
|o54 = true                                |
+------------------------------------------+
|i55 : MatrixExpression T                  |
|                                          |
|o55 = | a 1 |                             |
|      | b 2 |                             |
|      | c 3 |                             |
|                                          |
|o55 : Expression of class MatrixExpression|
+------------------------------------------+

The function table, can be used to create a table (doubly nested
list) from two lists and a function of two arguments.  It applies the function
consecutively to each element from the first list paired with each element from
the second list, so the total number of evaluations of the function is the
product of the lengths of the two lists.

+------------------------------------------------+
|i56 : table({1,2,3},{7,8},(i,j) -> 1000*i+j)    |
|                                                |
|o56 = {{1007, 1008}, {2007, 2008}, {3007, 3008}}|
|                                                |
|o56 : List                                      |
+------------------------------------------------+

The function pack,(L, n) turns the list $L$ into a nested list,
whose elements are lists containing the elements of $L$ taken $n$ at a time.

+-----------------------------------------------------------------+
|i57 : pack(1..15, 4)                                             |
|                                                                 |
|o57 = {{1, 2, 3, 4}, {5, 6, 7, 8}, {9, 10, 11, 12}, {13, 14, 15}}|
|                                                                 |
|o57 : List                                                       |
+-----------------------------------------------------------------+

On the other hand, see mingle,(L) takes the nested list $L = \{L_1,
L_2, \ldots, L_n\}$ and combines the elements of the $L_i$ into a single list
in the following way:

+-------------------------------------------------------------------+
|i58 : mingle({{1,2,3,4}, {10,20,30,40}, {100,200,300,400}, {a, b}})|
|                                                                   |
|o58 = {1, 10, 100, a, 2, 20, 200, b, 3, 30, 300, 4, 40, 400}       |
|                                                                   |
|o58 : List                                                         |
+-------------------------------------------------------------------+

Manipulating lists and sequences.

Use append,(L, x) to create a copy of $L$ with the element $x$
added to the end. Since lists are immutable in Macaulay2, $L$ itself is not
changed, unless redefined.

+----------------------------------------------------------+
|i59 :                                                     |
|                                                          |
|      L = {926, 621, 429, 67, 594, 904, 264, 18, 35, 961};|
+----------------------------------------------------------+
|i60 : append(L, -10)                                      |
|                                                          |
|o60 = {926, 621, 429, 67, 594, 904, 264, 18, 35, 961, -10}|
|                                                          |
|o60 : List                                                |
+----------------------------------------------------------+
|i61 : L                                                   |
|                                                          |
|o61 = {926, 621, 429, 67, 594, 904, 264, 18, 35, 961}     |
|                                                          |
|o61 : List                                                |
+----------------------------------------------------------+
|i62 : L = append(L, -10); L                               |
|                                                          |
|o63 = {926, 621, 429, 67, 594, 904, 264, 18, 35, 961, -10}|
|                                                          |
|o63 : List                                                |
+----------------------------------------------------------+

Use prepend,(x, L) to create a copy of $L$ with $x$ added to the
beginning of the list. Notice the order of arguments is the opposite of append!

+---------------------------------------------------------------+
|i64 : L = prepend(-20, L)                                      |
|                                                               |
|o64 = {-20, 926, 621, 429, 67, 594, 904, 264, 18, 35, 961, -10}|
|                                                               |
|o64 : List                                                     |
+---------------------------------------------------------------+

Use insert,(n, x, L) to specify that the element $x$ should be
added to the list $L$ at position $n$.

+--------------------------------------------------------------------+
|i65 : L = insert(5, -30, L)                                         |
|                                                                    |
|o65 = {-20, 926, 621, 429, 67, -30, 594, 904, 264, 18, 35, 961, -10}|
|                                                                    |
|o65 : List                                                          |
+--------------------------------------------------------------------+

Use switch,(m, n, L) to switch the elements of $L$ in indices $m$
and $n$.

+--------------------------------------------------------------------+
|i66 : L = switch(1, 2, L)                                           |
|                                                                    |
|o66 = {-20, 621, 926, 429, 67, -30, 594, 904, 264, 18, 35, 961, -10}|
|                                                                    |
|o66 : List                                                          |
+--------------------------------------------------------------------+

The function delete, removes elements that have a particular
value, NOT a particular index.

+---------------------------------------------------------------+
|i67 : L = delete(-10, L)                                       |
|                                                               |
|o67 = {-20, 621, 926, 429, 67, -30, 594, 904, 264, 18, 35, 961}|
|                                                               |
|o67 : List                                                     |
+---------------------------------------------------------------+

To remove the element at index $n$, use the command drop,(L,
\{n,n\}).

+----------------------------------------------------------+
|i68 : L = drop(L, {1,1})                                  |
|                                                          |
|o68 = {-20, 926, 429, 67, -30, 594, 904, 264, 18, 35, 961}|
|                                                          |
|o68 : List                                                |
+----------------------------------------------------------+

You can also use drop to remove a specified number of elements from the
beginning or end of $L$.

+------------------------------------------------+
|i69 : L = drop(L, 2)                            |
|                                                |
|o69 = {429, 67, -30, 594, 904, 264, 18, 35, 961}|
|                                                |
|o69 : List                                      |
+------------------------------------------------+
|i70 : L = drop(L, -2)                           |
|                                                |
|o70 = {429, 67, -30, 594, 904, 264, 18}         |
|                                                |
|o70 : List                                      |
+------------------------------------------------+

On the other hand, use take, to specify the number of elements to
keep, or a range of indices to keep:

+-----------------------------------+
|i71 : L = take(L, 6)               |
|                                   |
|o71 = {429, 67, -30, 594, 904, 264}|
|                                   |
|o71 : List                         |
+-----------------------------------+
|i72 : L = take(L, {1,4})           |
|                                   |
|o72 = {67, -30, 594, 904}          |
|                                   |
|o72 : List                         |
+-----------------------------------+

Use between,(x, L) to insert the element $x$ between every two
elements of $L$.

+-------------------------------------+
|i73 : L = between(-5, L)             |
|                                     |
|o73 = {67, -5, -30, -5, 594, -5, 904}|
|                                     |
|o73 : List                           |
+-------------------------------------+

Useful commands for reordering lists are reverse, (reverse the
current order), see sort, (put elements in ascending order), and
rsort, (put elements in descending order).

+-------------------------------------+
|i74 : L                              |
|                                     |
|o74 = {67, -5, -30, -5, 594, -5, 904}|
|                                     |
|o74 : List                           |
+-------------------------------------+
|i75 : reverse L                      |
|                                     |
|o75 = {904, -5, 594, -5, -30, -5, 67}|
|                                     |
|o75 : List                           |
+-------------------------------------+
|i76 : sort L                         |
|                                     |
|o76 = {-30, -5, -5, -5, 67, 594, 904}|
|                                     |
|o76 : List                           |
+-------------------------------------+
|i77 : rsort L                        |
|                                     |
|o77 = {904, 594, 67, -5, -5, -5, -30}|
|                                     |
|o77 : List                           |
+-------------------------------------+

Use unique, to remove duplicates from a list or sequence.

+-----------------------------+
|i78 : unique L               |
|                             |
|o78 = {67, -5, -30, 594, 904}|
|                             |
|o78 : List                   |
+-----------------------------+

Use join, to concatenate two lists or sequences. The symbol
|, is also used for concatenation.

+------------------------------------------+
|i79 : join(a..f, 1..6)                    |
|                                          |
|o79 = (a, b, c, d, e, f, 1, 2, 3, 4, 5, 6)|
|                                          |
|o79 : Sequence                            |
+------------------------------------------+
|i80 : x_1..x_3 | y_1..y_4                 |
|                                          |
|o80 = (x , x , x , y , y , y , y )        |
|        1   2   3   1   2   3   4         |
|                                          |
|o80 : Sequence                            |
+------------------------------------------+

Mapping over lists.

In programming, loops that operate on consecutive elements of a list are
common, so we offer various ways to apply functions to each of the elements of
a list, along with various ways to treat the returned values.

The most basic operation is provided by scan, which applies a
function consecutively to each element of a list, discarding the values
returned.

+--------------------------+
|i81 : scan({a,b,c}, print)|
|a                         |
|b                         |
|c                         |
+--------------------------+

The keyword break, can be used to terminate the scan prematurely,
and optionally to specify a return value for the expression.  Here we use it to
locate the first even number in a list.

+------------------------------------------------------------+
|i82 : scan({3,5,7,11,44,55,77}, i -> if even i then break i)|
|                                                            |
|o82 = 44                                                    |
+------------------------------------------------------------+

The function apply, is similar to scan, but creates a
list storing the values returned.

+--------------------------------+
|i83 : apply({1,2,3,4}, i -> i^2)|
|                                |
|o83 = {1, 4, 9, 16}             |
|                                |
|o83 : List                      |
+--------------------------------+

This operation is so common that we offer two shorthand notations for it, one
with the function on the right and one with the function on the left.

+----------------------------+
|i84 : {1,2,3,4} / (i -> i^2)|
|                            |
|o84 = {1, 4, 9, 16}         |
|                            |
|o84 : List                  |
+----------------------------+
|i85 : (i -> i^2) \ {1,2,3,4}|
|                            |
|o85 = {1, 4, 9, 16}         |
|                            |
|o85 : List                  |
+----------------------------+

The associativity of these operators during parsing is set up so the following
code works as one would wish.

+---------------------------------------------+
|i86 : {1,2,3,4} / (i -> i^2) / (j -> 1000*j) |
|                                             |
|o86 = {1000, 4000, 9000, 16000}              |
|                                             |
|o86 : List                                   |
+---------------------------------------------+
|i87 : (j -> 1000*j) \ (i -> i^2) \ {1,2,3,4} |
|                                             |
|o87 = {1000, 4000, 9000, 16000}              |
|                                             |
|o87 : List                                   |
+---------------------------------------------+
|i88 : (j -> 1000*j) @@ (i -> i^2) \ {1,2,3,4}|
|                                             |
|o88 = {1000, 4000, 9000, 16000}              |
|                                             |
|o88 : List                                   |
+---------------------------------------------+

The function apply, can also be used with two lists of the same
length, in which case it will apply the function consecutively to corresponding
elements of the two lists.

+------------------------------------------------+
|i89 : apply({1,2,3}, {7,8,9}, (i,j) -> 1000*i+j)|
|                                                |
|o89 = {1007, 2008, 3009}                        |
|                                                |
|o89 : List                                      |
+------------------------------------------------+

The function applyTable, can be used to apply a function to
each element of a table.

+--------------------------------------------+
|i90 : applyTable( {{1,2,3},{4,5}}, i -> i^2)|
|                                            |
|o90 = {{1, 4, 9}, {16, 25}}                 |
|                                            |
|o90 : List                                  |
+--------------------------------------------+

The functions fold, and accumulate, provide
various ways to iteratively apply a function of two arguments to the elements
of a list.  One of the arguments is the next element from the list, and the
other argument is the value returned by the previous application of the
function.  As an example, suppose we want to convert the list \{7,3,5,4,2\} of
digits into the corresponding number 73542.  The formula
(((7*10+3)*10+5)*10+4)+2 is a fast way to do it that doesn't involve computing
high powers of 10 separately.  We can do this with fold, and the
following code.

+----------------------------------------+
|i91 : fold((i,j) -> i*10+j, {7,3,5,4,2})|
|                                        |
|o91 = 73542                             |
+----------------------------------------+

Using accumulate, returns all the intermediate values of this
iterative calculation along with the final result.

+----------------------------------------------+
|i92 : accumulate((i,j) -> i*10+j, {7,3,5,4,2})|
|                                              |
|o92 = {73, 735, 7354, 73542}                  |
|                                              |
|o92 : List                                    |
+----------------------------------------------+

Conditional expressions; selecting elements matching a criterion.

Use select, to select those elements from a list that satisfy
some condition.

+----------------------------------------------------------+
|i93 : select({12, 3, -10, 42, 7, 6, 53}, even)            |
|                                                          |
|o93 = {12, -10, 42, 6}                                    |
|                                                          |
|o93 : List                                                |
+----------------------------------------------------------+
|i94 : select({12, 3, -10, 42, 7, 6, 53}, i -> i<0 or i>40)|
|                                                          |
|o94 = {-10, 42, 53}                                       |
|                                                          |
|o94 : List                                                |
+----------------------------------------------------------+

An optional first argument of an integer $n$ specifies to select no more than
$n$ matching elements.

+-------------------------------------------------+
|i95 : select(2, {12, 3, -10, 42, 7, 6, 53}, even)|
|                                                 |
|o95 = {12, -10}                                  |
|                                                 |
|o95 : List                                       |
+-------------------------------------------------+

Use positions, to select the indices of elements satisfying
the condition.

+-------------------------------------------------------------+
|i96 : positions({12, 3, -10, 42, 7, 6, 53}, i -> i<0 or i>40)|
|                                                             |
|o96 = {2, 3, 6}                                              |
|                                                             |
|o96 : List                                                   |
+-------------------------------------------------------------+

The singular position, returns only the first (or last, by
specifying Reverse => true) matching index.

+-----------------------------------------------------------------------------+
|i97 : position({12, 3, -10, 42, 7, 6, 53}, i -> i<0 or i>40)                 |
|                                                                             |
|o97 = 2                                                                      |
+-----------------------------------------------------------------------------+
|i98 : position({12, 3, -10, 42, 7, 6, 53}, i -> i<0 or i>40, Reverse => true)|
|                                                                             |
|o98 = 6                                                                      |
+-----------------------------------------------------------------------------+

Use number, to count how many elements satisfy the condition.

+----------------------------------------------------------+
|i99 : number({12, 3, -10, 42, 7, 6, 53}, i -> i<0 or i>40)|
|                                                          |
|o99 = 3                                                   |
+----------------------------------------------------------+

Use max, and min, to find the maximum or minimum of the
list. The functions maxPosition, and minPosition,
give the index of the maximum/minimum. Note that max and min work
with many Macaulay2 types besides numbers, for instance elements of a
polynomial ring with respect to a monomial order.

+----------------------------------------------------+
|i100 : R = QQ[x,y,z, MonomialOrder => Lex];         |
+----------------------------------------------------+
|i101 : max {x^2*y*z, x*y^3*z^2, x^3, y^3, z}        |
|                                                    |
|        3                                           |
|o101 = x                                            |
|                                                    |
|o101 : R                                            |
+----------------------------------------------------+
|i102 : maxPosition {x^2*y*z, x*y^3*z^2, x^3, y^3, z}|
|                                                    |
|o102 = 2                                            |
+----------------------------------------------------+
|i103 : min {x^2*y*z, x*y^3*z^2, x^3, y^3, z}        |
|                                                    |
|o103 = z                                            |
|                                                    |
|o103 : R                                            |
+----------------------------------------------------+
|i104 : minPosition {x^2*y*z, x*y^3*z^2, x^3, y^3, z}|
|                                                    |
|o104 = 4                                            |
+----------------------------------------------------+

We may use any, to tell whether there is at least one element of a
list satisfying a condition, and all, to tell whether all elements
satisfy it.

+------------------------------+
|i105 : any({3, 6, 7, 8}, even)|
|                              |
|o105 = true                   |
+------------------------------+
|i106 : all({3, 6, 7, 8}, even)|
|                              |
|o106 = false                  |
+------------------------------+

See also
========

  * # BasicList -- length or cardinality
  * BasicList # ZZ -- get value from list, hash table,
    database, or string
  * BasicList #? ZZ -- check existence of value in a list, hash
    table, database, or string
  * VisibleList _ ZZ -- get element from list
  * VisibleList _ List -- get some entries of a
    list
  * List | List -- join lists, sequences or arrays
  * all(BasicList,Function) -- whether
    all elements of a list satisfy a specified condition
  * any(BasicList,Function) -- whether
    any elements of a list satisfy a specified condition
  * append -- add an element to the end of a list
  * apply(BasicList,Function) -- apply
    a function to each element of a list
  * between -- insert something between elements of a list
  * deepSplice -- remove all levels of subsequences from a
    sequence or list
  * delete -- delete some elements of a list
  * drop -- drop some elements from a list or sequence.
  * first -- first element of a list
  * flatten -- flatten a nested list or a matrix
  * fold -- apply a binary operator repeatedly
  * insert -- copy a list, inserting an element
  * join -- join lists, sequences, and iterable objects
  * last -- last element of a list
  * mingle -- mingle elements of several lists
  * number -- count how many elements of a list satisfy a
    condition
  * pack -- pack elements of a list or string into several shorter
    lists or strings
  * position -- the first element of a list satisfying a
    condition
  * positions -- which elements of a list satisfy a condition
  * prepend -- add an element to the beginning of a list
  * reverse -- reverse a list, sequence, or string
  * rsort -- sort a list or matrix in reverse order
  * same -- whether everything in a list is the same
  * scan(BasicList,Function) -- apply a function to each element
    in a list or sequence
  * select -- select from a list, hash table, or string
  * sort -- sort a list or columns of a matrix
  * splice -- remove subsequences from a sequence or list
  * switch -- copy a list, switching two elements
  * table -- make a table from a binary function
  * take -- Take some elements from a list or sequence.
  * uniform -- whether all elements of a list are the same
    class
  * unique -- eliminate duplicates from a list
  * sequence -- make a sequence
  * toList -- create a list
  * toSequence -- convert to sequence
  * unsequence -- extract the single element from a sequence
    of length 1

hash tables
***********

A hash table is a data structure that can implement a function whose domain is
a finite set.  An element of the domain is called a key.  The hash table stores
the key-value pairs in such a way that when presented with a key, the
corresponding value can be quickly recovered.

A dictionary could be implemented as a hash table: the keys would be the words
in the language, and the values could be the definitions of the words.

A phone book could also be implemented as a hash table: the keys would be the
names of the subscribers, and the values could be the corresponding phone
numbers.  (We exclude the possibility of two subscribers with the same name.)

As an example we implement a phone book.
+-----------------------------------+
|i1 : book = new HashTable from {   |
|          "Joe" => "344-5567",     |
|          "Sarah" => "567-4223",   |
|          "John" => "322-1456"}    |
|                                   |
|o1 = HashTable{"Joe" => 344-5567  }|
|               "John" => 322-1456  |
|               "Sarah" => 567-4223 |
|                                   |
|o1 : HashTable                     |
+-----------------------------------+
We use the operator #, to obtain values from the phone book.
+-----------------+
|i2 : book#"Sarah"|
|                 |
|o2 = 567-4223    |
+-----------------+
The operator #?, can be used to tell us whether a given key has an
entry in the hash table.
+-----------------+
|i3 : book#?"Mary"|
|                 |
|o3 = false       |
+-----------------+
We have implemented the notion of set via hash tables in which every value is
the number 1.
+------------------------+
|i4 : x = set {a,b,c,r,t}|
|                        |
|o4 = set {c, t, a, r, b}|
|                        |
|o4 : Set                |
+------------------------+
|i5 : peek x             |
|                        |
|o5 = Set{a => 1}        |
|         b => 1         |
|         c => 1         |
|         r => 1         |
|         t => 1         |
+------------------------+
|i6 : x#?a               |
|                        |
|o6 = true               |
+------------------------+
|i7 : x#?4               |
|                        |
|o7 = false              |
+------------------------+
There is a type of hash table that is mutable, i.e., a hash table whose entries
can be changed.  They are changed with assignment statements of the form
x#key=value.
+------------------------------+
|i8 : x = new MutableHashTable;|
+------------------------------+
|i9 : x#"Joe" = "344-5567";    |
+------------------------------+
|i10 : x#3 = {a,b,c};          |
+------------------------------+
|i11 : x#{1,2} = 44;           |
+------------------------------+
|i12 : x#3                     |
|                              |
|o12 = {a, b, c}               |
|                              |
|o12 : List                    |
+------------------------------+
|i13 : x#?4                    |
|                              |
|o13 = false                   |
+------------------------------+
When a mutable hash table is printed, its contents are not displayed. This
prevents infinite loops in printing routines.
+-------------------------------+
|i14 : x                        |
|                               |
|o14 = MutableHashTable{...3...}|
|                               |
|o14 : MutableHashTable         |
+-------------------------------+
Use peek, to see the contents of a mutable hash table.
+---------------------------------------+
|i15 : peek x                           |
|                                       |
|o15 = MutableHashTable{{1, 2} => 44   }|
|                       3 => {a, b, c}  |
|                       Joe => 344-5567 |
+---------------------------------------+
A variant of #, is ..  It takes only global symbols as
keys, and ignores their values.
+----------------+
|i16 : p=4;      |
+----------------+
|i17 : x.p = 444;|
+----------------+
|i18 : x.p       |
|                |
|o18 = 444       |
+----------------+
|i19 : x#?4      |
|                |
|o19 = false     |
+----------------+

functions for manipulating hash tables

more information

copy -- copy an object
**********************

Description
===========

copy x yields a copy of x.

If x is an hash table, array, list or sequence, then the elements are placed
into a new copy. If x is a hash table, the copy is mutable if and only if x is.

It is not advisable to copy such things as modules and rings, for: (1) the
operations that have already been installed for them will return values in the
original object, rather than in the copy; and (2) the copy operation is
shallow, not copying keys and values that happen to be hash tables.

See also
========

  * newClass -- set the class and parent of an object

For the programmer
==================

The object copy, is a compiled function.

hashTable -- make a hash table
******************************

Description
===========

hashTable(h,v) -- produce a hash table from a list v of key-value pairs, with
an optional collision handler function h.

The pairs may be of the form a=>b, {a,b}, or (a,b).

Missing entries in the list, represented by null, will be silently
ignored.

+------------------------------------------+
|i1 : x = hashTable {a=>b, c=>d, }         |
|                                          |
|o1 = HashTable{a => b}                    |
|               c => d                     |
|                                          |
|o1 : HashTable                            |
+------------------------------------------+
|i2 : x#a                                  |
|                                          |
|o2 = b                                    |
|                                          |
|o2 : Symbol                               |
+------------------------------------------+
|i3 : hashTable(plus, {(a,3),(b,4),(a,10)})|
|                                          |
|o3 = HashTable{a => 13}                   |
|               b => 4                     |
|                                          |
|o3 : HashTable                            |
+------------------------------------------+

Ways to use hashTable:
======================

  * "hashTable(List)"
  * hashTable(Function,List) (missing documentation)

For the programmer
==================

The object hashTable, is a compiled function.

keys -- keys used in a hash table, dictionary, or database
**********************************************************

Synopsis
========

  * Usage:
        keys t
  * Inputs:
      * t, a hash table, a dictionary, or
        a database,
  * Outputs:
      * a list, the keys occurring in the hash table t

Description
===========

+--------------------------------------------+
|i1 : x = new HashTable from {a => 1, b => 2}|
|                                            |
|o1 = HashTable{a => 1}                      |
|               b => 2                       |
|                                            |
|o1 : HashTable                              |
+--------------------------------------------+
|i2 : keys x                                 |
|                                            |
|o2 = {a, b}                                 |
|                                            |
|o2 : List                                   |
+--------------------------------------------+

See also
========

  * hash tables
  * applyKeys -- apply a function to each key in a hash table
  * pairs -- list the pairs in a hash table, dictionary, or basic
    list
  * scanKeys -- apply a function to each key in a hash table
    or database
  * values -- values in a hash table
  * # -- length or access to elements
  * #? -- check existence of value in a list, hash table, database,
    or string

Ways to use keys:
=================

  * "keys(Database)"
  * "keys(Dictionary)"
  * "keys(HashTable)"

For the programmer
==================

The object keys, is a compiled function.

values -- values in a hash table
********************************

Synopsis
========

  * Usage:
        values t
  * Inputs:
      * t, a hash table,
  * Outputs:
      * a list, the values occurring in the hash table t

Description
===========

+--------------------------------------------+
|i1 : x = new HashTable from {a => 1, b => 2}|
|                                            |
|o1 = HashTable{a => 1}                      |
|               b => 2                       |
|                                            |
|o1 : HashTable                              |
+--------------------------------------------+
|i2 : values x                               |
|                                            |
|o2 = {1, 2}                                 |
|                                            |
|o2 : List                                   |
+--------------------------------------------+

See also
========

  * hash tables
  * applyValues -- apply a function to each value in a hash
    table
  * keys -- keys used in a hash table, dictionary, or database
  * pairs -- list the pairs in a hash table, dictionary, or basic
    list
  * scanValues -- apply a function to each value in a hash
    table or database
  * # -- length or access to elements
  * #? -- check existence of value in a list, hash table, database,
    or string

Ways to use values:
===================

  * "values(Dictionary)"
  * "values(HashTable)"

For the programmer
==================

The object values, is a compiled function.

pairs -- list the pairs in a hash table, dictionary, or basic list
******************************************************************

Synopsis
========

  * Usage:
        pairs x
  * Inputs:
      * x, a hash table, or Dictionary, or
        BasicList,
  * Outputs:
      * L, a list, of all pairs (k, x#k)

Description
===========

If x is a hash table or dictionary, the pairs consist of each key along with
its associated value.

+----------------------------------------------------+
|i1 : x = new HashTable from {a => 1, b => 2, c => 3}|
|                                                    |
|o1 = HashTable{a => 1}                              |
|               b => 2                               |
|               c => 3                               |
|                                                    |
|o1 : HashTable                                      |
+----------------------------------------------------+
|i2 : pairs x                                        |
|                                                    |
|o2 = {(c, 3), (a, 1), (b, 2)}                       |
|                                                    |
|o2 : List                                           |
+----------------------------------------------------+

A dictionary is a special hash table whose keys are strings, and whose values
are the corresponding symbols.

+-------------------------------+
|i3 : d = new Dictionary        |
|                               |
|o3 = d                         |
|                               |
|o3 : GlobalDictionary          |
+-------------------------------+
|i4 : getGlobalSymbol (d, "foo")|
|                               |
|o4 = foo                       |
|                               |
|o4 : Symbol                    |
+-------------------------------+
|i5 : getGlobalSymbol (d, "bar")|
|                               |
|o5 = bar                       |
|                               |
|o5 : Symbol                    |
+-------------------------------+
|i6 : pairs d                   |
|                               |
|o6 = {(bar, bar), (foo, foo)}  |
|                               |
|o6 : List                      |
+-------------------------------+
|i7 : first oo                  |
|                               |
|o7 = (bar, bar)                |
|                               |
|o7 : Sequence                  |
+-------------------------------+
|i8 : class \ oo                |
|                               |
|o8 = (String, Symbol)          |
|                               |
|o8 : Sequence                  |
+-------------------------------+

If x is a basic list, the pairs consist of each index along with the element at
that index in the list.

+--------------------------------------------+
|i9 : L = {3, 5, 7};                         |
+--------------------------------------------+
|i10 : pairs L                               |
|                                            |
|o10 = ((0, 3), (1, 5), (2, 7))              |
|                                            |
|o10 : Sequence                              |
+--------------------------------------------+
|i11 : pairs {apple, banana, carrot}         |
|                                            |
|o11 = ((0, apple), (1, banana), (2, carrot))|
|                                            |
|o11 : Sequence                              |
+--------------------------------------------+

Caveat
======

As the first example illustrates, pairs are not necessarily listed in any
particular order.

See also
========

  * hash tables
  * applyPairs -- apply a function to each pair in a hash
    table
  * keys -- keys used in a hash table, dictionary, or database
  * scanPairs -- apply a function to the pairs in a hash
    table
  * values -- values in a hash table
  * # -- length or access to elements
  * #? -- check existence of value in a list, hash table, database,
    or string

Ways to use pairs:
==================

  * "pairs(BasicList)"
  * "pairs(Dictionary)"
  * "pairs(HashTable)"

For the programmer
==================

The object pairs, is a compiled function.

isMutable -- whether something may be modified
**********************************************

Synopsis
========

  * Usage:
        isMutable x
  * Inputs:
      * x, a thing,
  * Outputs:
      * a Boolean value, whether x is mutable

Description
===========

If x is a hash table, list, dictionary, or database, then it is mutable if its
contents can be destructively altered.

If x is a symbol, then it's mutable if a value can be assigned to it; i.e., if
it is not protect,ed.

If x is anything else, isMutable x will return false.

+---------------------------------------+
|i1 : T = new MutableList from (a, b, c)|
|                                       |
|o1 = MutableList{...3...}              |
|                                       |
|o1 : MutableList                       |
+---------------------------------------+
|i2 : isMutable T                       |
|                                       |
|o2 = true                              |
+---------------------------------------+
|i3 : V = new List from (a, b, c)       |
|                                       |
|o3 = {a, b, c}                         |
|                                       |
|o3 : List                              |
+---------------------------------------+
|i4 : isMutable V                       |
|                                       |
|o4 = false                             |
+---------------------------------------+
|i5 : isMutable join(T, V)              |
|                                       |
|o5 = true                              |
+---------------------------------------+
|i6 : isMutable a                       |
|                                       |
|o6 = true                              |
+---------------------------------------+
|i7 : isMutable "a"                     |
|                                       |
|o7 = false                             |
+---------------------------------------+

This function may also be called using the synonym mutable.

Caveat
======

The (changeable) contents of a mutable hash table or list do not participate in
strong comparison with ===, or in hashing.

See also
========

  * MutableHashTable -- the class of all mutable hash
    tables
  * MutableList -- the class of all mutable lists
  * hash tables
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use isMutable:
======================

  * "isMutable(Thing)"

For the programmer
==================

The object isMutable, is a compiled function.

remove -- remove an entry from a mutable hash table, list, or database
**********************************************************************

Synopsis
========

  * Usage:
        remove(T, k)
  * Inputs:
      * T, a hash table, a mutable list,
        or a database,
      * k, the key to remove (must be an integer, if T is a mutable
        list or a string, if it is a database)
  * Outputs:
      * a thing, the removed value;

Description
===========

remove(T, k) removes and returns the entry of T stored under the key k.

+-------------------------------------------------------------------+
|i1 : T = new MutableHashTable from {a => 1, b => 2, c => 3}; peek T|
|                                                                   |
|o2 = MutableHashTable{a => 1}                                      |
|                      b => 2                                       |
|                      c => 3                                       |
+-------------------------------------------------------------------+
|i3 : remove(T, a)                                                  |
|                                                                   |
|o3 = 1                                                             |
+-------------------------------------------------------------------+
|i4 : peek T                                                        |
|                                                                   |
|o4 = MutableHashTable{b => 2}                                      |
|                      c => 3                                       |
+-------------------------------------------------------------------+

If T is not a mutable hash table, an error is thrown. One way to remove an
entry from an immutable hash table is with the function applyPairs,:

+--------------------------------------------------------+
|i5 : T = new HashTable from {a => 1, b => 2, c => 3}    |
|                                                        |
|o5 = HashTable{a => 1}                                  |
|               b => 2                                   |
|               c => 3                                   |
|                                                        |
|o5 : HashTable                                          |
+--------------------------------------------------------+
|i6 : T = applyPairs(T, (k, v) -> if k =!= a then (k, v))|
|                                                        |
|o6 = HashTable{b => 2}                                  |
|               c => 3                                   |
|                                                        |
|o6 : HashTable                                          |
+--------------------------------------------------------+

remove works similarly when T is a database.  See Database, for
more information.

If T is a mutable list, then k gives the index of the element to be removed.

+--------------------------------------------------+
|i7 : T = new MutableList from {1, 2, 3, 4}; peek T|
|                                                  |
|o8 = MutableList{1, 2, 3, 4}                      |
+--------------------------------------------------+
|i9 : remove(T, 0)                                 |
|                                                  |
|o9 = 1                                            |
+--------------------------------------------------+
|i10 : peek T                                      |
|                                                  |
|o10 = MutableList{2, 3, 4}                        |
+--------------------------------------------------+

If k is negative, then the index is determined by counting backwards from the
end of T.

+-----------------------+
|i11 : remove(T, -1)    |
|                       |
|o11 = 4                |
+-----------------------+
|i12 : peek T           |
|                       |
|o12 = MutableList{2, 3}|
+-----------------------+

See also
========

  * applyKeys -- apply a function to each key in a hash table
  * applyPairs -- apply a function to each pair in a hash
    table
  * applyValues -- apply a function to each value in a hash
    table
  * delete -- delete some elements of a list
  * drop -- drop some elements from a list or sequence.
  * keys -- keys used in a hash table, dictionary, or database
  * isMutable -- whether something may be modified
  * scanKeys -- apply a function to each key in a hash table
    or database
  * hash tables

Ways to use remove:
===================

  * "remove(Database,String)"
  * "remove(HashTable,Thing)"
  * "remove(MutableList,ZZ)"

For the programmer
==================

The object remove, is a compiled function.

applyKeys -- apply a function to each key in a hash table
*********************************************************

Synopsis
========

  * Usage:
        applyKeys(H, f)
        applyKeys(H, f, g)
  * Inputs:
      * H, a hash table,
      * f, a function, of one argument
      * g, a function, of two arguments, for collision
        handling
  * Outputs:
      * a hash table, obtained by applying f to each key in H

Description
===========

+-------------------------------------------------------+
|i1 : H = new HashTable from {1 => 10, 2 => 15, 3 => 20}|
|                                                       |
|o1 = HashTable{1 => 10}                                |
|               2 => 15                                 |
|               3 => 20                                 |
|                                                       |
|o1 : HashTable                                         |
+-------------------------------------------------------+
|i2 : applyKeys(H, k -> k + 100)                        |
|                                                       |
|o2 = HashTable{101 => 10}                              |
|               102 => 15                               |
|               103 => 20                               |
|                                                       |
|o2 : HashTable                                         |
+-------------------------------------------------------+
|i3 : applyKeys(H, k -> k//2, max)                      |
|                                                       |
|o3 = HashTable{0 => 10}                                |
|               1 => 20                                 |
|                                                       |
|o3 : HashTable                                         |
+-------------------------------------------------------+
|i4 : applyKeys(H, k -> k//2, plus)                     |
|                                                       |
|o4 = HashTable{0 => 10}                                |
|               1 => 35                                 |
|                                                       |
|o4 : HashTable                                         |
+-------------------------------------------------------+

Caveat
======

It is an error for the function f to return two pairs with the same key. When
this is a possibility, use the function g to specify how the two pairs should
be reconciled.

See also
========

  * hash tables
  * applyPairs -- apply a function to each pair in a hash
    table
  * applyValues -- apply a function to each value in a hash
    table
  * keys -- keys used in a hash table, dictionary, or database
  * scanKeys -- apply a function to each key in a hash table
    or database

Ways to use applyKeys:
======================

  * "applyKeys(HashTable,Function)"
  * "applyKeys(HashTable,Function,Function)"

For the programmer
==================

The object applyKeys, is a compiled function.

applyValues -- apply a function to each value in a hash table
*************************************************************

Synopsis
========

  * Usage:
        applyValues(H, f)
  * Inputs:
      * H, a hash table,
      * f, a function, of one argument
  * Outputs:
      * a hash table, obtained by applying f to each value in
        H

Description
===========

+-------------------------------------------------------+
|i1 : H = new HashTable from {1 => 10, 2 => 15, 3 => 20}|
|                                                       |
|o1 = HashTable{1 => 10}                                |
|               2 => 15                                 |
|               3 => 20                                 |
|                                                       |
|o1 : HashTable                                         |
+-------------------------------------------------------+
|i2 : applyValues(H, v -> v + 100)                      |
|                                                       |
|o2 = HashTable{1 => 110}                               |
|               2 => 115                                |
|               3 => 120                                |
|                                                       |
|o2 : HashTable                                         |
+-------------------------------------------------------+
|i3 : applyValues(H, v -> 1)                            |
|                                                       |
|o3 = HashTable{1 => 1}                                 |
|               2 => 1                                  |
|               3 => 1                                  |
|                                                       |
|o3 : HashTable                                         |
+-------------------------------------------------------+

See also
========

  * hash tables
  * applyKeys -- apply a function to each key in a hash table
  * applyPairs -- apply a function to each pair in a hash
    table
  * scanValues -- apply a function to each value in a hash
    table or database
  * values -- values in a hash table

Ways to use applyValues:
========================

  * "applyValues(HashTable,Function)"

For the programmer
==================

The object applyValues, is a compiled function.

applyPairs -- apply a function to each pair in a hash table
***********************************************************

Synopsis
========

  * Usage:
        applyPairs(H, f)
  * Inputs:
      * H, a hash table,
      * f, a function, of two arguments, returning a pair or
        null,
  * Outputs:
      * a hash table, obtained by applying f to each
        key/value pair in H

Description
===========

+-------------------------------------------------------+
|i1 : H = new HashTable from {1 => 10, 2 => 15, 3 => 20}|
|                                                       |
|o1 = HashTable{1 => 10}                                |
|               2 => 15                                 |
|               3 => 20                                 |
|                                                       |
|o1 : HashTable                                         |
+-------------------------------------------------------+
|i2 : applyPairs(H, (k,v) -> (k+1, v+10))               |
|                                                       |
|o2 = HashTable{2 => 20}                                |
|               3 => 25                                 |
|               4 => 30                                 |
|                                                       |
|o2 : HashTable                                         |
+-------------------------------------------------------+
|i3 : applyPairs(H, (k,v) -> (v,k))                     |
|                                                       |
|o3 = HashTable{10 => 1}                                |
|               15 => 2                                 |
|               20 => 3                                 |
|                                                       |
|o3 : HashTable                                         |
+-------------------------------------------------------+

Caveat
======

It is an error for the function f to return two pairs with the same key.

See also
========

  * hash tables
  * applyKeys -- apply a function to each key in a hash table
  * applyValues -- apply a function to each value in a hash
    table
  * pairs -- list the pairs in a hash table, dictionary, or basic
    list
  * scanPairs -- apply a function to the pairs in a hash
    table

Ways to use applyPairs:
=======================

  * "applyPairs(HashTable,Function)"

For the programmer
==================

The object applyPairs, is a compiled function.

merge -- merge two hash tables
******************************

Synopsis
========

  * Usage:
        z = merge(x, y, f)
  * Inputs:
      * x, a hash table,
      * y, a hash table,
      * f, a function, of two variables specifying how to
        handle duplicate keys
  * Outputs:
      * z, a hash table, a new hash table whose keys are the
        union of the keys of x and the keys of y

Description
===========

Key-value pairs whose keys appear in only one of the input tables appear
unchanged in the output table. If the key k appears in both x and y, then
f(x#k, y#k) is the value associated to k in the output hash table.

For example, we could take the max of the two values, their average, or make a
list containing both.

+-----------------------------------------------------------------+
|i1 : x = new HashTable from {1 => 203, 2 => 21, 3 => 5, 4 => 130}|
|                                                                 |
|o1 = HashTable{1 => 203}                                         |
|               2 => 21                                           |
|               3 => 5                                            |
|               4 => 130                                          |
|                                                                 |
|o1 : HashTable                                                   |
+-----------------------------------------------------------------+
|i2 : y = new HashTable from {2 => 37, 3 => 5, 4 => 56, 5 => 1}   |
|                                                                 |
|o2 = HashTable{2 => 37}                                          |
|               3 => 5                                            |
|               4 => 56                                           |
|               5 => 1                                            |
|                                                                 |
|o2 : HashTable                                                   |
+-----------------------------------------------------------------+
|i3 : merge(x, y, max)                                            |
|                                                                 |
|o3 = HashTable{1 => 203}                                         |
|               2 => 37                                           |
|               3 => 5                                            |
|               4 => 130                                          |
|               5 => 1                                            |
|                                                                 |
|o3 : HashTable                                                   |
+-----------------------------------------------------------------+
|i4 : merge(x, y, (i,j) -> (i+j)/2)                               |
|                                                                 |
|o4 = HashTable{1 => 203}                                         |
|               2 => 29                                           |
|               3 => 5                                            |
|               4 => 93                                           |
|               5 => 1                                            |
|                                                                 |
|o4 : HashTable                                                   |
+-----------------------------------------------------------------+
|i5 : merge(x, y, (i,j) -> {i,j})                                 |
|                                                                 |
|o5 = HashTable{1 => 203      }                                   |
|               2 => {21, 37}                                     |
|               3 => {5, 5}                                       |
|               4 => {130, 56}                                    |
|               5 => 1                                            |
|                                                                 |
|o5 : HashTable                                                   |
+-----------------------------------------------------------------+

If the function f(x#k, y#k) returns continue, then the key k
is omitted from the merged table.

+-------------------------------------------------------+
|i6 : merge(x, y, (i,j) -> if i==j then i else continue)|
|                                                       |
|o6 = HashTable{1 => 203}                               |
|               3 => 5                                  |
|               5 => 1                                  |
|                                                       |
|o6 : HashTable                                         |
+-------------------------------------------------------+

Here is a simple implementation of the free abelian group on four letters,
where each element is represented as a hash table that associates coefficients
to strings.

+-----------------------------------------------------------+
|i7 : Free = new Type of HashTable                          |
|                                                           |
|o7 = Free                                                  |
|                                                           |
|o7 : Type                                                  |
+-----------------------------------------------------------+
|i8 : p = new Free from { "x" => 2, "y" => 3, "z" => 5 }    |
|                                                           |
|o8 = Free{"x" => 2}                                        |
|          "y" => 3                                         |
|          "z" => 5                                         |
|                                                           |
|o8 : Free                                                  |
+-----------------------------------------------------------+
|i9 : q = new Free from { "x" => 100, "y" => 200, "w" => 7 }|
|                                                           |
|o9 = Free{"w" => 7  }                                      |
|          "x" => 100                                       |
|          "y" => 200                                       |
|                                                           |
|o9 : Free                                                  |
+-----------------------------------------------------------+
|i10 : Free + Free := (p,q) -> merge(p, q, plus);           |
+-----------------------------------------------------------+
|i11 : p+q                                                  |
|                                                           |
|o11 = Free{"w" => 7  }                                     |
|           "x" => 102                                      |
|           "y" => 203                                      |
|           "z" => 5                                        |
|                                                           |
|o11 : Free                                                 |
+-----------------------------------------------------------+

If x and y have the same class, and have the same parent,
as in the previous example, then so will z.

+----------------------------------------------------------------------+
|i12 : x = new MutableHashTable from {"alice" => 53709, "bob" => 6549};|
+----------------------------------------------------------------------+
|i13 : y = new MutableHashTable from {"bob" => 86, "charlie" => 23};   |
+----------------------------------------------------------------------+
|i14 : mutable merge(x, y, plus)                                       |
|                                                                      |
|o14 = true                                                            |
+----------------------------------------------------------------------+

The function combine, allows much greater control when combining
two hash tables: you can give functions for how to handle every key and value
of the input tables, not just the duplicates. The function mergePairs,
is similar to merge, but works on lists of pairs rather than hash
tables.

See also
========

  * applyKeys -- apply a function to each key in a hash table
  * applyPairs -- apply a function to each pair in a hash
    table
  * applyValues -- apply a function to each value in a hash
    table
  * combine -- combine hash tables
  * keys -- keys used in a hash table, dictionary, or database
  * mergePairs -- merge sorted lists of pairs
  * pairs -- list the pairs in a hash table, dictionary, or basic
    list
  * scanKeys -- apply a function to each key in a hash table
    or database
  * scanPairs -- apply a function to the pairs in a hash
    table
  * scanValues -- apply a function to each value in a hash
    table or database
  * values -- values in a hash table
  * hash tables

Ways to use merge:
==================

  * "merge(HashTable,HashTable,Function)"

For the programmer
==================

The object merge, is a compiled function.

combine -- combine hash tables
******************************

Synopsis
========

  * Usage:
        z = combine(x,y,f,g,h) or z=combine(x,y,f,t,g,h)
  * Inputs:
      * x, a hash table
      * y, a hash table of the same class as x
      * f, a function of two variables to be used for combining a key of x with
        a key of y to make a new key for z.
      * t, a function combining two keys and returning a value, twisting the
        value returned by g based on which keys were used. This argument may be
        omitted, in which case the t(p,q) term in the output below is omitted.
      * g, a function of two variables to be used for combining a value of x
        with a value of y to make a new value for z.
      * h, a function of two variables to be used for combining two values
        returned by g when the corresponding keys returned by f turn out to be
        equal.  Its first argument will be the value accumulated so far, and
        its second argument will be a value just provided by g.
  * Outputs:
      * z, a new hash table, of the same class as x and y, containing the pair
        f(p,q) => g(t(p,q),g(b,c)) whenever x contains the pair p => b and y
        contains the pair q => c, except that h is used to combine values when
        two keys coincide.  If f or g evaluates continue, then
        nothing is contributed to the resulting hash table.  If h evaluates
        continue, then, at that point, the entry stored under
        the key f(p,q) in the hash table under construction is removed.

Description
===========

The function f is applied to every pair (p,q) where p is a key of x and q is a
key of y.  The number of times f is evaluated is thus the product of the number
of keys in x and the number of keys in y.

The function h should be an associative function, for otherwise the result may
depend on internal details about the implementation of hash tables that affect
the order in which entries are encountered.  If f, t (if present), g, and h are
commutative functions as well, then the result z is a commutative function of x
and y.

The result is mutable if and only if x or y is.

This function can be used for multiplying polynomials, where it can be used in
code something like this:
     combine(x, y, monomialTimes, coeffTimes, coeffPlus)
We illustrate that with a simple-minded implementation of the free ring on the
English alphabet, representing words as string and polynomials as hash tables
that associate coefficients to words.
+------------------------------------------------------------------+
|i1 : Poly = new Type of HashTable                                 |
|                                                                  |
|o1 = Poly                                                         |
|                                                                  |
|o1 : Type                                                         |
+------------------------------------------------------------------+
|i2 : p = new Poly from { "" => 1, "x" => 2, "y" => 3, "cat" => 5 }|
|                                                                  |
|o2 = Poly{"" => 1   }                                             |
|          "cat" => 5                                              |
|          "x" => 2                                                |
|          "y" => 3                                                |
|                                                                  |
|o2 : Poly                                                         |
+------------------------------------------------------------------+
|i3 : Poly * Poly := (p,q) -> combine(p,q,concatenate,times,plus); |
+------------------------------------------------------------------+
|i4 : p*p                                                          |
|                                                                  |
|o4 = Poly{"" => 1       }                                         |
|          "cat" => 10                                             |
|          "catcat" => 25                                          |
|          "catx" => 10                                            |
|          "caty" => 15                                            |
|          "x" => 4                                                |
|          "xcat" => 10                                            |
|          "xx" => 4                                               |
|          "xy" => 6                                               |
|          "y" => 6                                                |
|          "ycat" => 15                                            |
|          "yx" => 6                                               |
|          "yy" => 9                                               |
|                                                                  |
|o4 : Poly                                                         |
+------------------------------------------------------------------+
One may also use this function for multiplying divided powers in a similar
manner:
     combine(x, y, monomialTimes, divPowCoeff, coeffTimes, coeffPlus)
For example:
+-----------------------------------------------------------------------------+
|i5 : DivPowPoly = new Type of HashTable                                      |
|                                                                             |
|o5 = DivPowPoly                                                              |
|                                                                             |
|o5 : Type                                                                    |
+-----------------------------------------------------------------------------+
|i6 : divPowCoeff = (i,j) -> binomial(i+j,i)                                  |
|                                                                             |
|o6 = divPowCoeff                                                             |
|                                                                             |
|o6 : FunctionClosure                                                         |
+-----------------------------------------------------------------------------+
|i7 : p = new DivPowPoly from { 0 => 1, 1 => 1 }                              |
|                                                                             |
|o7 = DivPowPoly{0 => 1}                                                      |
|                1 => 1                                                       |
|                                                                             |
|o7 : DivPowPoly                                                              |
+-----------------------------------------------------------------------------+
|i8 : DivPowPoly * DivPowPoly := (p,q) ->                                     |
|-----------------------------------------------------------------------------|
|combine(p,q,plus,divPowCoeff,times,plus);                                    |
+-----------------------------------------------------------------------------+
|i9 : p*p                                                                     |
|                                                                             |
|o9 = DivPowPoly{0 => 1}                                                      |
|                1 => 2                                                       |
|                2 => 2                                                       |
|                                                                             |
|o9 : DivPowPoly                                                              |
+-----------------------------------------------------------------------------+

See also
========

  * merge -- merge two hash tables

For the programmer
==================

The object combine, is a compiled function.

hashing
*******

A hash table contains a set of key-value pairs.  The access functions for hash
tables accept a key and retrieve the corresponding value.  Here are the
details, together with a discussion of how we designed the hash table system
seen in Macaulay2.

The keys and values are stored in the hash table.  The hash table consists of a
certain number of buckets, each of which can hold an arbitrary number of
key-value pairs.  The number of buckets is chosen to be large enough that
typically one may expect each bucket to hold fewer than three key-value pairs.
The key is used  as follows to determine in which bucket the key-value pair is
to be stored.  The function hash, is applied to the key to produce,
in a deterministic way, an integer called the hash code, and the remainder of
the hash code upon division by the number of buckets tells which bucket will be
used.

It is essential that the hash code of a key never change, for otherwise the
next attempt to find the key in the hash table will have an unpredictable
result - the new hash code of the key may or may not lead to the same bucket,
and the value may or may not be located.

Some hash tables and lists are isMutable, i.e., their
contents can be altered by assignment statements.  As explained above, the hash
code of a mutable thing is not permitted to change when the contents of the
thing change.  Hence, the algorithm for computing the hash code may not refer
to the contents of a mutable thing.

The strong comparison operator ===, is provided to
parrot the equality testing that occurs implicitly when accessing a key in a
hash table.  The fundamental requirement for this strong comparison operator is
that things with different hash codes must also turn out to be different when
tested with this comparison operator.

Here we come to a question of design.  As discussed above, we must assign hash
codes to mutable things in such a way that the hash codes don't depend on their
contents.  We can do this in various ways.
  * One way to assign hash codes to mutable things is to give the same hash
    code, say 1000000, to every mutable thing.  We could then implement a
    strong comparison operator for mutable things that would proceed by
    examining the contents of the things, so that two mutable things would be
    equal if and only if their contents were equal.  A disadvantage of this
    approach would be that a hash table in which many mutable things appear as
    keys would have all of those key-value pairs appearing in the same bucket,
    so that access to this hashtable would be slow.  (Each bucket is
    implemented as a linear list, and searching a long linear list is slow.)
  * Another way to assign hash codes to mutable things is to give different
    hash codes to each mutable thing; for example, the first mutable thing
    could receive hash code 1000000, the second could receive the hash code
    1000001, and so on.  (Another choice for such a hash code is the address in
    memory of the thing.  But this address can change depending on
    environmental factors not under the control of the interpreter, and thus
    its use as a hash code would lead to unpredictable behavior.)  A
    disadvantage of this approach is that the strong comparison operator could
    not examine the contents of mutable objects!  (Remember that if the hash
    codes are different, the strong comparison must declare the things to be
    different, too.)  The offsetting advantage is that a hash table in which
    many mutable things appear as keys would typically have the key-value pairs
    distributed among the buckets, so that access to this hashtable would be
    fast.

In Macaulay2, we chose the second approach listed above; we expect to have many
mutable things appearing as keys in hash tables, and we need the speed.  A
counter with initial value 1000000 is incremented each time a mutable thing is
created, and its value is taken as the hash code of the thing and stored within
it.  The strong comparison test cannot depend on the contents of mutable
things, and thus such things appear to be containers with opaque walls.  For
mutable things, the test for equality must be the same as equality of the hash
codes.

It is essential to have some hash tables for which equality amounts to equality
of the contents.  This cannot be achieved for mutable hash tables, but we do
achieve it for non-mutable hash tables -- the hash code is computed directly
from the contents of the thing in a deterministic way.  This allows us to
implement the notion of polynomial, say, as a hash table -- the keys can be the
monomials (necessarily non-mutable) and the values can be the coefficients.
The notion of monomial can be implemented as a hash table where the keys are
the variables and the values are the corresponding exponents.

One further comforting remark: the routines that compute hash codes or strong
equality do not get into infinite loops, despite the existence of circular
structures: any circular structure must come into being by means of changing
something, and so the circular loop in the structure necessarily involves a
mutable thing, whose contents are not examined by the routines. This provides
another argument in favor of taking the second approach listed above.

See also
========

  * HashTable -- the class of all hash tables

HashTable -- the class of all hash tables
*****************************************

Description
===========

A hash table consists of: a class type, a parent type, and a set of key-value
pairs.  The keys and values can be anything. The access functions below accept
a key and return the corresponding value.  For details of the mechanism
underlying this, see hashing.

One important feature of hash tables that when the keys are consecutive
integers starting at 0, the keys are scanned in the natural order.

There is a subclass of HashTable called MutableHashTable,
which consists of those hash tables whose entries can be
changed.

This node is currently in progress!!!

See also
========

  * # -- length or access to elements
  * . -- access to elements whose key is a symbol
  * #? -- check existence of value in a list, hash table, database,
    or string
  * .? -- check for presence of elements whose key is a symbol

Types of hash table:
====================

  * CoherentSheaf (Varieties) -- the class of all coherent
    sheaves
  * DocumentTag -- the class of all document tags
  * Ideal -- the class of all ideals
  * ImmutableType -- the class of immutable types
  * Matrix -- the class of all matrices
  * MonoidElement -- the class of all monoid elements
  * MutableHashTable -- the class of all mutable hash
    tables
  * MutableMatrix -- the class of all mutable matrices
  * OptionTable -- the class of hash tables for optional
    arguments
  * Program -- external program object
  * ProgramRun -- result of running an external program
  * ProjectiveHilbertPolynomial -- the
    class of all Hilbert polynomials
  * RingMap -- the class of all ring maps
  * SheafMap (missing documentation)
  * SheafOfRings (Varieties) -- the class of sheaves of
    rings
  * "TestInput" -- see tests, -- locate a package's tests
  * VirtualTally

Functions and methods returning a hash table:
=============================================

  * "applyKeys(HashTable,Function)" -- see applyKeys, -- apply
    a function to each key in a hash table
  * "applyKeys(HashTable,Function,Function)" -- see applyKeys,
    -- apply a function to each key in a hash table
  * "applyPairs(HashTable,Function)" -- see applyPairs, --
    apply a function to each pair in a hash table
  * "applyValues(HashTable,Function)" -- see applyValues, --
    apply a function to each value in a hash table
  * faces (Polyhedra) -- computes all faces of a certain
    codimension of a Cone or Polyhedron
  * "hashTable(List)" -- see hashTable, -- make a hash table
  * hashTable(Function,List) (missing documentation)
  * instances(Type)
  * "merge(HashTable,HashTable,Function)" -- see merge, -- merge
    two hash tables
  * new HashTable from List -- make a hash
    table from a list
  * parent(HashTable) (missing documentation)
  * "partition(Function,VirtualTally)" -- see partition, --
    partition a set or list by values of a function
  * "partition(Function,VirtualTally,VisibleList)" -- see partition,
    -- partition a set or list by values of a function
  * "partition(Function,VisibleList)" -- see partition, --
    partition a set or list by values of a function
  * "partition(Function,VisibleList,VisibleList)" -- see partition,
    -- partition a set or list by values of a function
  * select(HashTable,Function), --
    select part of a hash table
  * "selectValues(HashTable,Function)" -- see select(HashTable,Function),
    -- select part of a hash table
  * select(ZZ,HashTable,Function),
    -- select a limited number of pairs from a hash table
  * "selectValues(ZZ,HashTable,Function)" -- see
    select(ZZ,HashTable,Function), --
    select a limited number of pairs from a hash table
  * "selectKeys(HashTable,Function)" -- see selectKeys, --
    select a part of a hash table by keys
  * "selectKeys(ZZ,HashTable,Function)" -- see selectKeys, --
    select a part of a hash table by keys
  * "selectPairs(HashTable,Function)" -- see selectPairs, --
    select a part of a hash table by pairs
  * "selectPairs(ZZ,HashTable,Function)" -- see selectPairs,
    -- select a part of a hash table by pairs

Methods that use a hash table:
==============================

  * "# HashTable" -- see # BasicList, -- length or
    cardinality
  * "HashTable #? Thing" -- see #?, -- check existence of value in a
    list, hash table, database, or string
  * all(HashTable,Function) -- whether
    all key/value pairs in a hash table satisfy a specified condition
  * any(HashTable,Function) -- whether
    all key/value pairs in a hash table satisfy a specified condition
  * "HashTable # Thing" -- see BasicList # ZZ, -- get
    value from list, hash table, database, or string
  * "hooks(HashTable)" -- see hooks, -- list hooks attached to a
    key
  * indices(HashTable) (missing documentation)
  * "installAssignmentMethod(Symbol,HashTable,Function)" -- see
    installAssignmentMethod, -- install methods
    assignment to the value of an operator
  * "installAssignmentMethod(Symbol,HashTable,HashTable,Function)" -- see
    installAssignmentMethod, -- install methods
    assignment to the value of an operator
  * "installAssignmentMethod(Symbol,HashTable,HashTable,Option)" -- see
    installAssignmentMethod, -- install methods
    assignment to the value of an operator
  * "installAssignmentMethod(Symbol,HashTable,Option)" -- see
    installAssignmentMethod, -- install methods
    assignment to the value of an operator
  * "keys(HashTable)" -- see keys, -- keys used in a hash table,
    dictionary, or database
  * "package(HashTable)" -- see package, -- get containing
    package
  * "pairs(HashTable)" -- see pairs, -- list the pairs in a hash
    table, dictionary, or basic list
  * "remove(HashTable,Thing)" -- see remove, -- remove an entry
    from a mutable hash table, list, or database
  * "scanKeys(HashTable,Function)" -- see scanKeys, -- apply a
    function to each key in a hash table or database
  * "scanPairs(HashTable,Function)" -- see scanPairs, -- apply
    a function to the pairs in a hash table
  * "scanValues(HashTable,Function)" -- see scanValues, --
    apply a function to each value in a hash table or database
  * "values(HashTable)" -- see values, -- values in a hash table

For the programmer
==================

The object HashTable, is a type, with ancestor
class Thing.

MutableHashTable -- the class of all mutable hash tables
********************************************************

Description
===========

A mutable hash table is a type of hash table whose entries can be changed.

Normally the entries in a mutable hash table are not printed, to prevent
infinite loops in the printing routines.  To print them out, use peek.
+----------------------------------+
|i1 : x = new MutableHashTable     |
|                                  |
|o1 = MutableHashTable{}           |
|                                  |
|o1 : MutableHashTable             |
+----------------------------------+
|i2 : scan(0 .. 30, i -> x#i = i^2)|
+----------------------------------+
|i3 : x # 20                       |
|                                  |
|o3 = 400                          |
+----------------------------------+
|i4 : x #? 40                      |
|                                  |
|o4 = false                        |
+----------------------------------+

See also
========

  * HashTable -- the class of all hash tables

Types of mutable hash table:
============================

  * CacheTable -- hash tables for caching
  * Descent
  * GradedModule -- the class of all graded modules
  * GradedModuleMap -- the class of all maps between
    graded modules
  * GroebnerBasis -- the class of all Gröbner bases
  * IndexedVariableTable
  * Package -- the class of all packages
  * PolyhedralObject (Polyhedra) -- the class of all
    polyhedral objects in Polyhedra
  * Resolution -- the class of all resolution computations
  * ScriptedFunctor -- the class of all scripted
    functors
  * Type -- the class of all types
  * Variety (Varieties) -- the class of all algebraic varieties

Methods that use a mutable hash table:
======================================

  * "addHook(MutableHashTable,Thing,Function)" -- see addHook,
    -- add a hook function to an object for later processing
  * "runHooks(MutableHashTable,Thing,Thing)" -- see runHooks,
    -- run the hook functions stored in an object

For the programmer
==================

The object MutableHashTable, is a type,
with ancestor classes HashTable, < Thing.

operators
*********

Here we present all of the unary and binary operators in the language.  They
are members of the class Keyword. The binary operators are
!=, #, #?, %, %=, &,
&=, *, **, **=, *=,
see +, ++, ++=, +=, ,,
-, -=, ->, ., ..,
..<, ..<=, ..=, .?,
/, //, //=, /=, _colon_,
_colon_=, ;, <, <-, <<, <<=,
see <=, <==, <===, <==>,
<==>=, =, =!=, ==, ===,
see ===>, ===>=, ==>, ==>=,
=>, >, >=, >>, >>=, ?,
see ??, ??=, @, @=, @@,
@@=, \, \=, \\, \\=, ^,
^**, ^**=, ^<, ^<=,
^=, ^>, ^>=, ^^, ^^=, _,
see _<, _<=, _=, _>,
_>=, |, |-, |-=, |=, |_,
see |_=, ||, ||=, and, or,
see SPACE, xor, , the unary prefix operators are
#, *, +, ,, -, <, <<,
see <=, <==, <===, >, >=,
?, ??, |-, not, , and the unary postfix
operators are !, (*), ,, ;,
^!, ^*, ^~, _!, _*,
_~, ~, .

Of those, the ones for which users may install new methods are the binary
operators %, %=, &, &=, *,
**, **=, *=, +, ++,
++=, +=, -, -=, ..,
..<, ..<=, ..=, /, //,
see //=, /=, _colon_, <<, <<=,
see <==, <===, <==>, <==>=,
==, ===>, ===>=, ==>, ==>=,
see >>, >>=, ?, ??, ??=,
@, @=, @@, @@=, \, \=,
see \\, \\=, ^, ^**, ^**=,
see ^<, ^<=, ^=, ^>, ^>=,
see ^^, ^^=, _, _<, _<=,
see _=, _>, _>=, |, |-,
see |-=, |=, |_, |_=, ||,
see ||=, and, or, SPACE,
xor, , the unary prefix operators *, +, -,
<, <<, <=, <==, <===,
>, >=, ?, ??, |-, not, ,
and the unary postfix operators !, (*), ^!,
^*, ^~, _!, _*, _~,
~, .

assignment

equality testing

comparison of objects

predicates

functions

subscripting and object access

arithmetic operators

miscellaneous operators

built in operators

augmented assignment

further information

= -- assignment
***************

Description
===========

In this section we'll discuss simple assignment to variables, multiple
assignment, assignment to parts of objects, assignment covered by various other
methods, and briefly touch on the possibility of custom installation of
assignment methods.  See also the operator _colon_=, which handles
assignment and declaration of local variables and assignment of methods to
operators, as well as the operator <-, which is an assignment
operator that evaluates its left hand side and can have assignment methods
installed for it by the user.

simple assignment
=================

  * Usage:
        x = e
  * Inputs:
      * x, a symbol,  (unevaluated)
      * e, a thing,
  * Outputs:
      * a thing, the value of the expression is e
  * Consequences:
      * e is assigned to x, so future references to the value of x yield e
      * if x is a global variable, then the global assignment hook for the
        class of e, if any, is run (see GlobalAssignHook),
        and the global assignment hook for the symbol
        itself (see globalAssignmentHooks), if
        any, is run.
+-----------+
|i1 : x     |
|           |
|o1 = x     |
|           |
|o1 : Symbol|
+-----------+
|i2 : x = 4 |
|           |
|o2 = 4     |
+-----------+
|i3 : x     |
|           |
|o3 = 4     |
+-----------+

Since the value of the entire expression is e, and since the operator =,
is right-associative (see precedence of operators),
e can be easily assigned to more than one variable, as in the
following example.

+---------------+
|i4 : x = y = 44|
|               |
|o4 = 44        |
+---------------+
|i5 : x         |
|               |
|o5 = 44        |
+---------------+
|i6 : y         |
|               |
|o6 = 44        |
+---------------+

multiple assignment
===================

  * Usage:
        (x,y,z,...) = (c,d,e,...)
  * Inputs:
      * (x,y,z,...) a sequence, of symbols,
        (unevaluated)
      * (c,d,e,...) a sequence, of things,
  * Outputs:
      * the value of the expression is (c,d,e,...)
  * Consequences:
      * the expressions c,d,e,... are assigned to the variables x,y,z,...,
        respectively, as above.  Global assignment hooks may be run, as above.
        The number of expressions must match the number of variables.

Multiple assignment makes it easy to switch the values of two variables, or to
permute the values of several.

+------------------+
|i7 : x = 444      |
|                  |
|o7 = 444          |
+------------------+
|i8 : y = foo      |
|                  |
|o8 = foo          |
|                  |
|o8 : Symbol       |
+------------------+
|i9 : (y,x) = (x,y)|
|                  |
|o9 = (444, foo)   |
|                  |
|o9 : Sequence     |
+------------------+
|i10 : x           |
|                  |
|o10 = foo         |
|                  |
|o10 : Symbol      |
+------------------+
|i11 : y           |
|                  |
|o11 = 444         |
+------------------+

Multiple assignment enables functions to return multiple values usefully.  See
making functions with multiple return values.

+----------------------+
|i12 : f = i -> (i,i^2)|
|                      |
|o12 = f               |
|                      |
|o12 : FunctionClosure |
+----------------------+
|i13 : (x,y) = f 9     |
|                      |
|o13 = (9, 81)         |
|                      |
|o13 : Sequence        |
+----------------------+
|i14 : x               |
|                      |
|o14 = 9               |
+----------------------+
|i15 : y               |
|                      |
|o15 = 81              |
+----------------------+

assignment to an element of a mutable list
==========================================

  * Usage:
        x#i = e
  * Inputs:
      * x, a mutable list,
      * i, an integer,
      * e, a thing,
  * Outputs:
      * the value of the expression is e
  * Consequences:
      * the i-th element of the list x is replaced by e, so that future
        references to the value of x#i yield e
+-------------------------------------+
|i16 : x = new MutableList from a .. e|
|                                     |
|o16 = MutableList{...5...}           |
|                                     |
|o16 : MutableList                    |
+-------------------------------------+
|i17 : peek x                         |
|                                     |
|o17 = MutableList{a, b, c, d, e}     |
+-------------------------------------+
|i18 : x#3                            |
|                                     |
|o18 = d                              |
|                                     |
|o18 : Symbol                         |
+-------------------------------------+
|i19 : x#3 = "foo"                    |
|                                     |
|o19 = foo                            |
+-------------------------------------+
|i20 : x#3                            |
|                                     |
|o20 = foo                            |
+-------------------------------------+
|i21 : peek x                         |
|                                     |
|o21 = MutableList{a, b, c, foo, e}   |
+-------------------------------------+

assignment to an element of a mutable hash table
================================================

  * Usage:
        x#i = e
  * Inputs:
      * x, a mutable list,
      * i, a thing,
      * e, a thing,
  * Outputs:
      * the value of the expression is e
  * Consequences:
      * e is stored in the hash table x under the key i, so that future
        references to the value of x#i yield e
      * future references to the value of x#?i will yield the value true,
        indicating that something has been stored in x under the key i.
        See #?.
+----------------------------------------------------------+
|i22 : x = new MutableHashTable from { "a" => 2, "b" => 3 }|
|                                                          |
|o22 = MutableHashTable{...2...}                           |
|                                                          |
|o22 : MutableHashTable                                    |
+----------------------------------------------------------+
|i23 : peek x                                              |
|                                                          |
|o23 = MutableHashTable{a => 2}                            |
|                       b => 3                             |
+----------------------------------------------------------+
|i24 : x#?"foo"                                            |
|                                                          |
|o24 = false                                               |
+----------------------------------------------------------+
|i25 : x#"foo" = "bar"                                     |
|                                                          |
|o25 = bar                                                 |
+----------------------------------------------------------+
|i26 : x#?"foo"                                            |
|                                                          |
|o26 = true                                                |
+----------------------------------------------------------+
|i27 : x#"foo"                                             |
|                                                          |
|o27 = bar                                                 |
+----------------------------------------------------------+
|i28 : peek x                                              |
|                                                          |
|o28 = MutableHashTable{a => 2    }                        |
|                       b => 3                             |
|                       foo => bar                         |
+----------------------------------------------------------+

installing assignment methods for binary operators
==================================================

  * Usage:
        X OP Y = (x,y,e) -> ...
  * Inputs:
      * X, a type,
      * OP, one of the binary operators for which users may install methods,
        namely: %, %=, &, &=, *,
        see **, **=, *=, +,
        ++, ++=, +=, -, -=,
        .., ..<, ..<=, ..=,
        see /, //, //=, /=,
        _colon_, <<, <<=, <==, <===,
        see <==>, <==>=, ==, ===>,
        see ===>=, ==>, ==>=, >>,
        see >>=, ?, ??, ??=, @,
        see @=, @@, @@=, \, \=,
        see \\, \\=, ^, ^**,
        ^**=, ^<, ^<=, ^=, ^>,
        see ^>=, ^^, ^^=, _,
        _<, _<=, _=, _>, _>=,
        see |, |-, |-=, |=,
        |_, |_=, ||, ||=, and,
        see or, SPACE, xor, .  The operator
        SPACE, indicating adjacency, may be omitted from the usage above.
      * Y, a type,
      * (x,y,e) -> ..., a function,
  * Outputs:
      * the value of the expression is the same as the function on the right
        hand side
  * Consequences:
      * the function on the right hand side is installed as the method for
        assignment to X OP Y.  See the next subsection below for using it
The first line of the following example illustrates the syntax above.
+--------------------------------+
|i29 :                           |
|      String * String = peek;   |
+--------------------------------+
|i30 : "left" * "right" = "value"|
|                                |
|o30 = ("left", "right", "value")|
+--------------------------------+
|i31 : String * String = peek;   |
+--------------------------------+

Warning: the installation of new methods may supplant old ones, changing the
behavior of Macaulay2.

using assignment methods for binary operators
=============================================

  * Usage:
        x OP y = e
  * Inputs:
      * x, an object of type X
      * OP, one of the binary operators for which users may install methods,
        listed above. The operator SPACE, indicating adjacency, may be omitted
        from the usage above.
      * y, an object of type Y
      * e, a thing,
  * Outputs:
      * the previously installed method for assignment to X OP Y is called with
        arguments (x,y,e), and its return value is returned.  If no such method
        has been installed, then Macaulay2 searches for a method for assignment
        to X' OP Y', where X' is an ancestor of X and Y' is an ancestor of Y
        (see inheritance, for details).

The return value and the consequences depend on the code of the installed
assignment method. References to currently installed assignment methods are
given below.

The second line of the following example illustrates the syntax above.
+--------------------------------+
|i32 : "left" * "right" = "value"|
|                                |
|o32 = ("left", "right", "value")|
+--------------------------------+
|i33 : s                         |
|                                |
|o33 = s                         |
|                                |
|o33 : Symbol                    |
+--------------------------------+

assignment to indexed variables
===============================

  * Usage:
        x_i = e
  * Inputs:
      * x, a symbol,  (evaluated)
      * i, a thing,
      * e, a thing,
  * Outputs:
      * e
  * Consequences:
      * The indexed variable, x  is created (if
                                                      i
        necessary) and is assigned the value e so that future references to x_i
        yield the value e. Moreover, the value of the symbol x is set to an
        object of type IndexedVariableTable, which
        contains the values of the expressions x_i.

The method for assignment to indexed variables is pre-installed.

+----------------------+
|i34 : s_2             |
|                      |
|o34 = s               |
|       2              |
|                      |
|o34 : IndexedVariable |
+----------------------+
|i35 : s_2 = 44        |
|                      |
|o35 = 44              |
+----------------------+
|i36 : s_2             |
|                      |
|o36 = 44              |
+----------------------+
|i37 : s_(i,j)         |
|                      |
|o37 = s               |
|       i,j            |
|                      |
|o37 : IndexedVariable |
+----------------------+
|i38 : symbol s_2      |
|                      |
|o38 = s               |
|       2              |
|                      |
|o38 : IndexedVariable |
+----------------------+
|i39 : value oo        |
|                      |
|o39 = 44              |
+----------------------+
|i40 : - String = peek;|
+----------------------+

installing assignment methods for unary prefix operators
========================================================

  * Usage:
        OP X = (x,e) -> ...
  * Inputs:
      * OP, one of the unary prefix operators for which users may install
        methods, namely: *, +, -, <,
        <<, <=, <==, <===, >,
        see >=, ?, ??, |-, not,
      * X, a type,
      * (x,e) -> ..., a function,
  * Outputs:
      * the value of the expression is the same as the function on the right
        hand side
  * Consequences:
      * the function on the right hand side is installed as the method for
        assignment to OP X.  See the next subsection below for using it.
The first line of the following example illustrates the syntax above.
+-----------------------+
|i41 : - "foo" = "value"|
|                       |
|o41 = ("foo", "value") |
+-----------------------+
|i42 : - String = peek; |
+-----------------------+

Warning: the installation of new methods may supplant old ones, changing the
behavior of Macaulay2.

using assignment methods for unary prefix operators
===================================================

  * Usage:
        OP x = e
  * Inputs:
      * OP, one of the unary prefix operators for which users may install
        methods, listed above.
      * x, an object of type X
      * e, a thing,
  * Outputs:
      * the previously installed method for assignment to OP X is called with
        arguments (x,e), and its return value is returned.

The return value and the consequences depend on the code of the installed
assignment method. References to currently installed assignment methods are
given below.

The second line of the following example illustrates the syntax above.
+-----------------------+
|i43 : - "foo" = "value"|
|                       |
|o43 = ("foo", "value") |
+-----------------------+
|i44 : String ~ = peek; |
+-----------------------+

installing assignment methods for unary postfix operators
=========================================================

  * Usage:
        X OP = (x,e) -> ...
  * Inputs:
      * OP, one of the unary postfix operators for which users may install
        methods, namely: !, (*), ^!,
        ^*, ^~, _!, _*, _~,
        see ~,
      * X, a type,
      * (x,e) -> ..., a function,
  * Outputs:
      * the value of the expression is the same as the function on the right
        hand side
  * Consequences:
      * the function on the right hand side is installed as the method for
        assignment to OP X.  See the next subsection below for using it.
The first line of the following example illustrates the syntax above.
+-----------------------+
|i45 : "foo" ~ = "value"|
|                       |
|o45 = ("foo", "value") |
+-----------------------+
|i46 : String ~ = peek; |
+-----------------------+

Warning: the installation of new methods may supplant old ones, changing the
behavior of Macaulay2.

using assignment methods for unary postfix operators
====================================================

  * Usage:
        x OP = e
  * Inputs:
      * x, an object of type X
      * OP, one of the unary postfix operators for which users may install
        methods, listed above.
      * e, a thing,
  * Outputs:
      * the previously installed method for assignment to X OP is called with
        arguments (x,e), and its return value is returned.

The return value and the consequences depend on the code of the installed
assignment method. References to currently installed assignment methods are
given below.

The second line of the following example illustrates the syntax above.
+-----------------------+
|i47 : "foo" ~ = "value"|
|                       |
|o47 = ("foo", "value") |
+-----------------------+
|i48 :                  |
+-----------------------+

See also
========

  * _colon_= -- assignment of method or new local variable
  * <- -- assignment with left side evaluated
  * globalAssignmentHooks -- assignment hooks for
    global symbols

Ways to use symbol =:
=====================

  * ChainComplex _ ZZ = Thing -- install
    component of chain complex
  * ChainComplexMap _ ZZ = Thing, --
    install component of chain complex map
  * "IndexedVariableTable _ Thing = Thing" -- see IndexedVariableTable,
  * MutableMatrix _ Sequence = Thing,
    -- assignment to an element of a mutable matrix
  * Symbol _ Thing = Thing -- assignment to an
    indexed variable

For the programmer
==================

The object =, is a keyword.

:= -- assignment of method or new local variable
************************************************

Description
===========

In this section we'll discuss simple local assignment to variables, multiple
local assignment, and installation and use of method functions. See also the
operator =, which handles other forms of assignment, as well as the
operator <-, which is an assignment operator that evaluates its left
hand side and can have assignment methods installed for it by the user.

simple local assignment
=======================

  * Usage:
        x := e
  * Inputs:
      * x, a symbol,  (unevaluated)
      * e, a thing,
  * Outputs:
      * a thing, the value of the expression is e
  * Consequences:
      * a new local variable x is created.  The scope of x is the innermost
        current function body or for, loop, or the current file.
      * e is assigned to x, so future references to the value of x yield e
      * a warning message is issued if a local variable with the same name has
        already been created
+-----------+
|i1 : x     |
|           |
|o1 = x     |
|           |
|o1 : Symbol|
+-----------+
|i2 : x := 4|
|           |
|o2 = 4     |
+-----------+
|i3 : x     |
|           |
|o3 = 4     |
+-----------+

In the next example, we see that the scope of the local variable p is limited
to the body of the function.

+------------------------------+
|i4 : g = () -> ( p := 444; p )|
|                              |
|o4 = g                        |
|                              |
|o4 : FunctionClosure          |
+------------------------------+
|i5 : g()                      |
|                              |
|o5 = 444                      |
+------------------------------+
|i6 : p                        |
|                              |
|o6 = p                        |
|                              |
|o6 : Symbol                   |
+------------------------------+

In this example, we see that the scope of the local variable j is limited to
the body of a for, loop.

+-----------------------------+
|i7 : i="a b c";              |
+-----------------------------+
|i8 : for i to 3 list j := i+1|
|                             |
|o8 = {1, 2, 3, 4}            |
|                             |
|o8 : List                    |
+-----------------------------+
|i9 : i                       |
|                             |
|o9 = a b c                   |
+-----------------------------+
|i10 : j                      |
|                             |
|o10 = j                      |
|                             |
|o10 : Symbol                 |
+-----------------------------+

In this example, we see that a function returned by another function retains
access to the values of local variables in its scope.

+----------------------------------------+
|i11 : g = () -> ( p := 444; () -> p )   |
|                                        |
|o11 = g                                 |
|                                        |
|o11 : FunctionClosure                   |
+----------------------------------------+
|i12 : g()                               |
|                                        |
|o12 = FunctionClosure[stdio:11:22-11:29]|
|                                        |
|o12 : FunctionClosure                   |
+----------------------------------------+
|i13 : oo ()                             |
|                                        |
|o13 = 444                               |
+----------------------------------------+

Functions returned by a function can also modify local variables within their
scope, thereby communicating with each other.

+--------------------------------------------------+
|i14 : g = () -> ( p := 444; (() -> p, i -> p = i))|
|                                                  |
|o14 = g                                           |
|                                                  |
|o14 : FunctionClosure                             |
+--------------------------------------------------+
|i15 : (b,c) = g()                                 |
|                                                  |
|o15 = (b, c)                                      |
|                                                  |
|o15 : Sequence                                    |
+--------------------------------------------------+
|i16 : b()                                         |
|                                                  |
|o16 = 444                                         |
+--------------------------------------------------+
|i17 : c 555                                       |
|                                                  |
|o17 = 555                                         |
+--------------------------------------------------+
|i18 : b()                                         |
|                                                  |
|o18 = 555                                         |
+--------------------------------------------------+

Since the value of the entire expression is e, and since the operator =,
is right-associative (see precedence of operators),
e can be easily assigned to more than one variable, as in the
following example.

+------------------+
|i19 : a := b := 44|
|                  |
|o19 = 44          |
+------------------+
|i20 : a           |
|                  |
|o20 = 44          |
+------------------+
|i21 : b           |
|                  |
|o21 = 44          |
+------------------+

By the way, there is a difference between a variable (to which values can be
assigned) and a symbol (which can be used as an indeterminate in making a
polynomial ring).  If you want a local variable to which is assigned the
corresponding local symbol, then combine the use of _colon_=, with
the use of local, as in the following example, which illustrates
a good way to do a computation in a temporary ring without disturbing the
values of any global variables.

+-----------------------------------------------------------------------------+
|i22 : g = () -> (                                                            |
|           x := local x;                                                     |
|           R := QQ[x];                                                       |
|           (x+2)^10);                                                        |
+-----------------------------------------------------------------------------+
|i23 : g()                                                                    |
|                                                                             |
|       10      9       8       7        6        5         4         3       |
|o23 = x   + 20x  + 180x  + 960x  + 3360x  + 8064x  + 13440x  + 15360x  +     |
|      -----------------------------------------------------------------------|
|            2                                                                |
|      11520x  + 5120x + 1024                                                 |
|                                                                             |
|o23 : QQ[x]                                                                  |
+-----------------------------------------------------------------------------+

multiple local assignment
=========================

  * Usage:
        (x,y,z,...) := (c,d,e,...)
  * Inputs:
      * (x,y,z,...) a sequence, of symbols,
        (unevaluated)
      * (c,d,e,...) a sequence, of things,
  * Outputs:
      * the value of the expression is (c,d,e,...)
  * Consequences:
      * new local variables x, y, z, ... are created
      * the expressions c,d,e,... are assigned to the variables x,y,z,...,
        respectively, as above.
      * If the left hand side has more elements than the right hand side, then
        the extra symbols on the left side are given the value null.
      * If the left hand side has fewer elements than the right hand side, then
        the last symbol on the left hand side is given as value a sequence
        containing the trailing elements of the right hand side.
      * If the right hand side is not a sequence, then it is assigned to the
        first symbol on the left, and the remaining symbols are assigned the
        value null.

Multiple assignment effectively means that functions can return multiple values
usefully.

+----------------------+
|i24 : f = i -> (i,i^2)|
|                      |
|o24 = f               |
|                      |
|o24 : FunctionClosure |
+----------------------+
|i25 : (r,s) := f 9    |
|                      |
|o25 = (9, 81)         |
|                      |
|o25 : Sequence        |
+----------------------+
|i26 : r               |
|                      |
|o26 = 9               |
+----------------------+
|i27 : s               |
|                      |
|o27 = 81              |
+----------------------+

installing methods for binary operators
=======================================

  * Usage:
        X OP Y := (x,y) -> ...
  * Inputs:
      * X, a type,
      * OP, one of the binary operators for which users may install methods,
        namely: %, %=, &, &=, *,
        see **, **=, *=, +,
        ++, ++=, +=, -, -=,
        .., ..<, ..<=, ..=,
        see /, //, //=, /=,
        _colon_, <<, <<=, <==, <===,
        see <==>, <==>=, ==, ===>,
        see ===>=, ==>, ==>=, >>,
        see >>=, ?, ??, ??=, @,
        see @=, @@, @@=, \, \=,
        see \\, \\=, ^, ^**,
        ^**=, ^<, ^<=, ^=, ^>,
        see ^>=, ^^, ^^=, _,
        _<, _<=, _=, _>, _>=,
        see |, |-, |-=, |=,
        |_, |_=, ||, ||=, and,
        see or, SPACE, xor, .  The operator
        SPACE, indicating adjacency, may be omitted from the usage above.
      * Y, a type,
      * (x,y) -> ..., a function,
  * Outputs:
      * the value of the expression is the same as the function on the right
        hand side
  * Consequences:
      * the function on the right hand side is installed as the method for X OP
        Y.  See the next subsection below for using it.
The first line of the following example illustrates the syntax above.
+------------------------------+
|i28 :                         |
|      String * String := peek;|
+------------------------------+
|i29 : "left" * "right"        |
|                              |
|o29 = ("left", "right")       |
+------------------------------+
|i30 : String * Number := peek;|
+------------------------------+

Warning: the installation of new methods may supplant old ones, changing the
behavior of Macaulay2.

using methods for binary operators
==================================

  * Usage:
        x OP y
  * Inputs:
      * x, an object of type X
      * OP, one of the binary operators for which users may install methods,
        listed above. The operator SPACE, indicating adjacency, may be omitted
        from the usage above.
      * y, an object of type Y
  * Outputs:
      * the previously installed method for X OP Y is called with arguments
        (x,y), and its return value is returned. If no such method has been
        installed, then Macaulay2 searches for a method for X' OP Y', where X'
        is an ancestor of X and Y' is an ancestor of Y (see inheritance,
        for details).
The second line of the following example illustrates the syntax above.
+----------------------------------------+
|i31 : "left" * 33                       |
|                                        |
|o31 = ("left", 33)                      |
+----------------------------------------+
|i32 : "left" * 3.3                      |
|                                        |
|o32 = ("left", 3.3)                     |
+----------------------------------------+
|i33 : ZZ + ZZ := (x,y) -> x+y+100       |
|                                        |
|o33 = FunctionClosure[stdio:37:11-37:27]|
|                                        |
|o33 : FunctionClosure                   |
+----------------------------------------+

Some methods for operators are

internal, and cannot be successfully overridden by the user, as we illustrate
in the next example, where we try (and fail) to override the definition of the
sum of two integers.
+-----------------------------------------------------------------------------+
|i34 : 3 + 4                                                                  |
|                                                                             |
|o34 = 7                                                                      |
+-----------------------------------------------------------------------------+
|i35 : QQ // QQ := (w,z) -> (numerator w + numerator z)/(denominator w +      |
|                                                                             |
|o35 = FunctionClosure[stdio:39:12-39:80]                                     |
|                                                                             |
|o35 : FunctionClosure                                                        |
|-----------------------------------------------------------------------------|
|denominator z)                                                               |
+-----------------------------------------------------------------------------+
By contrast, division with remainder of rational numbers is not internal, and
can be overridden.
+-----------------------+
|i36 : (3/5) // (6/7)   |
|                       |
|      3                |
|o36 = -                |
|      4                |
|                       |
|o36 : QQ               |
+-----------------------+
|i37 : - String := peek;|
+-----------------------+

installing methods for unary prefix operators
=============================================

  * Usage:
        OP X = (x) -> ...
  * Inputs:
      * OP, one of the unary prefix operators for which users may install
        methods, namely: *, +, -, <,
        <<, <=, <==, <===, >,
        see >=, ?, ??, |-, not,
      * X, a type,
      * (x) -> ..., a function,
  * Outputs:
      * the value of the expression is the same as the function on the right
        hand side
  * Consequences:
      * the function on the right hand side is installed as the method for OP
        X.  See the next subsection below for using it.
The first line of the following example illustrates the syntax above.
+-----------------------+
|i38 : - "foo"          |
|                       |
|o38 = "foo"            |
+-----------------------+
|i39 : - String := peek;|
+-----------------------+

Warning: the installation of new methods may supplant old ones, changing the
behavior of Macaulay2.

using methods for unary prefix operators
========================================

  * Usage:
        OP x
  * Inputs:
      * OP, one of the unary prefix operators for which users may install
        methods, listed above.
      * x, an object of type X
  * Outputs:
      * the previously installed method for OP X is called with argument x, and
        its return value is returned. If no such method has been installed,
        then Macaulay2 searches for a method for OP X', where X' is an ancestor
        of X (see inheritance, for details).
The second line of the following example illustrates the syntax above.
+-----------------------+
|i40 : - "foo"          |
|                       |
|o40 = "foo"            |
+-----------------------+
|i41 : String ~ := peek;|
+-----------------------+

installing methods for unary postfix operators
==============================================

  * Usage:
        X OP = (x) -> ...
  * Inputs:
      * OP, one of the unary postfix operators for which users may install
        methods, namely: !, (*), ^!,
        ^*, ^~, _!, _*, _~,
        see ~,
      * X, a type,
      * (x) -> ..., a function,
  * Outputs:
      * the value of the expression is the same as the function on the right
        hand side
  * Consequences:
      * the function on the right hand side is installed as the method for OP
        X.  See the next subsection below for using it.
The first line of the following example illustrates the syntax above.
+-----------------------+
|i42 : "foo" ~          |
|                       |
|o42 = "foo"            |
+-----------------------+
|i43 : String ~ := peek;|
+-----------------------+

Warning: the installation of new methods may supplant old ones, changing the
behavior of Macaulay2.

using methods for unary postfix operators
=========================================

  * Usage:
        x OP
  * Inputs:
      * x, an object of type X
      * OP, one of the unary postfix operators for which users may install
        methods, listed above.
  * Outputs:
      * the previously installed method for X OP is called with argument= x,
        and its return value is returned. If no such method has been installed,
        then Macaulay2 searches for a method for to X' OP, where X' is an
        ancestor of X (see inheritance, for details).
The second line of the following example illustrates the syntax above.
+----------------------------+
|i44 : "foo" ~               |
|                            |
|o44 = "foo"                 |
+----------------------------+
|i45 : source String := peek;|
+----------------------------+

installing unary methods for method functions
=============================================

  * Usage:
        f X := (x) -> ...
        f(X) := (x) -> ...
  * Inputs:
      * f, a previously defined method function.  A method function may be
        created with the function method.
      * X, a type,
      * (x) -> ..., a function,
  * Consequences:
      * the function on the right hand side is installed as the method for
        assignment to f X.  See the next subsection below for using it.
The first line of the following example illustrates the syntax above, using
source, which happens to be a method function.
+----------------------------+
|i46 : source "foo"          |
|                            |
|o46 = "foo"                 |
+----------------------------+
|i47 : source String := peek;|
+----------------------------+

Warning: the installation of new methods may supplant old ones, changing the
behavior of Macaulay2.

using unary methods for method functions
========================================

  * Usage:
        f x
  * Inputs:
      * f, a method function
      * x, an object of type X
  * Outputs:
      * the previously installed method for f X is called with argument x, and
        its return value is returned
The second line of the following example illustrates the syntax above, using
source, which happens to be a method function.
+------------------------------------+
|i48 : source "foo"                  |
|                                    |
|o48 = "foo"                         |
+------------------------------------+
|i49 : source(String,Number) := peek;|
+------------------------------------+

installing binary methods for method functions
==============================================

  * Usage:
        f(X,Y) := (x,y) -> ...
  * Inputs:
      * f, a previously defined method function.  A method function may be
        created with the function method.
      * X, a type,
      * Y, a type,
      * (x,y) -> ..., a function,
  * Consequences:
      * the function on the right hand side is installed as the method for
        f(X,Y).  See the next subsection below for using it.
The first line of the following example illustrates the syntax above, using
source, which happens to be a method function.
+------------------------------------+
|i50 : source("foo",33)              |
|                                    |
|o50 = ("foo", 33)                   |
+------------------------------------+
|i51 : source("foo",3.3)             |
|                                    |
|o51 = ("foo", 3.3)                  |
+------------------------------------+
|i52 : source(String,String) := peek;|
+------------------------------------+

Warning: the installation of new methods may supplant old ones, changing the
behavior of Macaulay2.

The same syntax works for 3 or 4 arguments.

using binary methods for method functions
=========================================

  * Usage:
        f(x,y)
  * Inputs:
      * f, a method function
      * x, an object of type X
      * y, an object of type Y
  * Outputs:
      * the previously installed method for f(X,Y) is called with arguments
        (x,y), and the return value is returned. If no such method has been
        installed, then Macaulay2 searches for a method for f(X',Y'), where X'
        is an ancestor of X and Y' is an ancestor of Y (see inheritance,
        for details).
The second line of the following example illustrates the syntax above, using
source, which happens to be a method function.
+-------------------------+
|i53 : source("foo","bar")|
|                         |
|o53 = ("foo", "bar")     |
+-------------------------+
|i54 :                    |
+-------------------------+

The same syntax works for 3 or 4 arguments.

Another use of the operator _colon_=, is for installing methods for
creation of new objects.  For details, see new.

See also
========

  * = -- assignment
  * <- -- assignment with left side evaluated
  * new -- new objects and new types

For the programmer
==================

The object _colon_=, is a keyword.

<- -- assignment with left side evaluated
*****************************************

Description
===========

assignment to symbols
=====================

  * Usage:
        x <- e
  * Inputs:
      * x, a symbol,  (evaluated)
      * e, a thing,
  * Outputs:
      * the value of the expression is the value of e
  * Consequences:
      * assuming the value of x is a symbol, t, say, the value of e is assigned
        to t so that future references to the value of t yield e.
+-----------+
|i1 : x = t |
|           |
|o1 = t     |
|           |
|o1 : Symbol|
+-----------+
|i2 : x <- 4|
|           |
|o2 = 4     |
+-----------+
|i3 : x     |
|           |
|o3 = t     |
|           |
|o3 : Symbol|
+-----------+
|i4 : t     |
|           |
|o4 = 4     |
+-----------+

Initially, the value of a symbol y is y itself, and then y = e and y <- e do
the same thing.

+------------+
|i5 : y <- 44|
|            |
|o5 = 44     |
+------------+
|i6 : y      |
|            |
|o6 = 44     |
+------------+

The code to the left of the arrow can be any expression whose value is a
symbol.

+-----------------------+
|i7 : f = () -> symbol z|
|                       |
|o7 = f                 |
|                       |
|o7 : FunctionClosure   |
+-----------------------+
|i8 : (f()) <- 44       |
|                       |
|o8 = 44                |
+-----------------------+
|i9 : z                 |
|                       |
|o9 = 44                |
+-----------------------+

installing new assignment methods
=================================

  * Usage:
        installMethod(symbol <-, X, (x,e) -> ...)
  * Inputs:
      * X, a type,
      * (x,e) -> ..., a function, of two arguments
  * Outputs:
      * the value returned is the function provided
  * Consequences:
      * the function (x,e) -> ... is installed as the method for assignment to
        objects of type X.  See the next subsection below for using it.
+--------------------------------------------+
|i10 : installMethod(symbol <-, String, peek)|
|                                            |
|o10 = peek                                  |
|                                            |
|o10 : FunctionClosure                       |
+--------------------------------------------+

using installed assignment methods
==================================

  * Usage:
        x <- e
  * Inputs:
      * x, an object of type X
      * e, a thing,
  * Outputs:
      * the value of the expression is the value returned by the previously
        installed method
  * Consequences:
      * the previously installed method for assignment to objects of type X is
        called with arguments (x,e), unless x is a symbol, in which case the
        internal assignment method applies, as described above. If there is no
        method for X, then the ancestors of X are consulted, starting with the
        parent of X and ending with Thing, (see inheritance).

The following example used the method for assignment to strings installed
above.

+--------------------+
|i11 : "foo" <- "bar"|
|                    |
|o11 = ("foo", "bar")|
+--------------------+

As before, the left hand side is evaluated, and in this case, it can be any
expression whose value is a string.

+----------------------------+
|i12 : "foo" | "foo" <- "bar"|
|                            |
|o12 = ("foofoo", "bar")     |
+----------------------------+

assignment to an indexed variable
=================================

  * Usage:
        x <- e
  * Inputs:
      * x, an indexed variable,
      * e, a thing,
  * Outputs:
      * the value of the expression is the value returned by the previously
        installed method
  * Consequences:
      * assuming the value of x is an indexed variable,
        the value of e is assigned to it, so that future references to value x
        or to s_i, if that's what the value of x is, yield e. Moreover, the
        value of s is set to s.

This assignment method is pre-installed.

+-----------------------------------------------------------------------------+
|i13 : u = s_4                                                                |
|                                                                             |
|o13 = s                                                                      |
|       4                                                                     |
|                                                                             |
|o13 : IndexedVariable                                                        |
+-----------------------------------------------------------------------------+
|i14 : s = 3                                                                  |
|                                                                             |
|o14 = 3                                                                      |
+-----------------------------------------------------------------------------+
|i15 : u <- 555                                                               |
|warning: clearing value of symbol s to allow access to subscripted           |
|       : debug with expression   debug 6001   or with command line           |
|                                                                             |
|o15 = 555                                                                    |
|-----------------------------------------------------------------------------|
|variables based on it                                                        |
|option   --debug 6001                                                        |
+-----------------------------------------------------------------------------+
|i16 : s                                                                      |
|                                                                             |
|o16 = s                                                                      |
|                                                                             |
|o16 : IndexedVariableTable                                                   |
+-----------------------------------------------------------------------------+
|i17 : s_4                                                                    |
|                                                                             |
|o17 = 555                                                                    |
+-----------------------------------------------------------------------------+
|i18 : u                                                                      |
|                                                                             |
|o18 = s                                                                      |
|       4                                                                     |
|                                                                             |
|o18 : IndexedVariable                                                        |
+-----------------------------------------------------------------------------+
|i19 : value u                                                                |
|                                                                             |
|o19 = 555                                                                    |
+-----------------------------------------------------------------------------+

parallel assignment
===================

  * Usage:
        x <- e
  * Inputs:
      * x, a sequence,
      * e, a sequence,
  * Outputs:
      * the value of the expression is the value of e
  * Consequences:
      * assuming the values of x and of e are a sequence, with
        the same length, each member of e is assigned to the corresponding
        member of x

This assignment method is pre-installed.

+-------------------------------------------+
|i20 : (symbol a, symbol b) <- (3,4)        |
|                                           |
|o20 = (3, 4)                               |
|                                           |
|o20 : Sequence                             |
+-------------------------------------------+
|i21 : a                                    |
|                                           |
|o21 = 3                                    |
+-------------------------------------------+
|i22 : (symbol r_1 .. symbol r_3) <- (5,6,7)|
|                                           |
|o22 = (5, 6, 7)                            |
|                                           |
|o22 : Sequence                             |
+-------------------------------------------+
|i23 : r_2                                  |
|                                           |
|o23 = 6                                    |
+-------------------------------------------+

See also
========

  * = -- assignment
  * _colon_= -- assignment of method or new local variable
  * IndexedVariable <- Thing -- assignment with left side evaluated

Ways to use symbol <-:
======================

  * "IndexedVariable <- Thing"
  * "Sequence <- Thing"

For the programmer
==================

The object <-, is a keyword.

== -- equality
**************

Synopsis
========

  * Usage:
        x == y

Description
===========

Returns true or false, depending on whether the objects x and y are
(mathematically) equal.  The objects x and y are typically numbers, elements of
rings, matrices, modules, ideals, chain complexes, and so on.

A test for mathematical equality will typically involve doing a computation to
see whether two representations of the same mathematical object are being
compared.  For example, an ideal in a ring is represented by giving its
generators, and checking whether two sets of generators produce the same ideal
involves a computation with Gröbner bases.  The ideals must be defined in the
same ring.

Ideals
------

+-----------------------------------------------+
|i1 : R = QQ[a,b,c];                            |
+-----------------------------------------------+
|i2 : ideal(a^2-b,a^3) == ideal(b^2, a*b, a^2-b)|
|                                               |
|o2 = true                                      |
+-----------------------------------------------+

Often mathematical objects can be tested to see if they are 0 or 1.

+-----------------------------------+
|i3 : L = ideal(a^2-a-1,a^3+a+3)    |
|                                   |
|             2           3         |
|o3 = ideal (a  - a - 1, a  + a + 3)|
|                                   |
|o3 : Ideal of R                    |
+-----------------------------------+
|i4 : L == 1                        |
|                                   |
|o4 = true                          |
+-----------------------------------+
|i5 : L == 0                        |
|                                   |
|o5 = false                         |
+-----------------------------------+

Matrices
--------

Two matrices, are equal if their entries are equal, the source
and target are the same (including degrees), and the degree of the matrices are
the same.  In this example, m and n have different source free modules.

+----------------------------+
|i6 : m = matrix{{a,b},{c,a}}|
|                            |
|o6 = | a b |                |
|     | c a |                |
|                            |
|             2      2       |
|o6 : Matrix R  <-- R        |
+----------------------------+
|i7 : n = map(R^2,R^2,m)     |
|                            |
|o7 = | a b |                |
|     | c a |                |
|                            |
|             2      2       |
|o7 : Matrix R  <-- R        |
+----------------------------+
|i8 : m == n                 |
|                            |
|o8 = false                  |
+----------------------------+
|i9 : source m == source n   |
|                            |
|o9 = false                  |
+----------------------------+

If you only want to know if they have the same entries, test the difference
against zero.

+--------------+
|i10 : m-n == 0|
|              |
|o10 = true    |
+--------------+

Rings
-----

Modules
-------

Two modules, are equal if they are isomorphic as subquotients of
the same ambient free module.

+---------------------------------------+
|i11 : image matrix {{2,a},{1,5}} == R^2|
|                                       |
|o11 = false                            |
+---------------------------------------+
|i12 : image matrix {{2,a},{0,5}} == R^2|
|                                       |
|o12 = true                             |
+---------------------------------------+

Intervals
---------

If either side of the equality is an RRi, the equality is an
equality of sets.

+------------------------------------+
|i13 : interval(1,3) == interval(1,3)|
|                                    |
|o13 = true                          |
+------------------------------------+
|i14 : interval(1/2) == 1/2          |
|                                    |
|o14 = true                          |
+------------------------------------+
|i15 : interval(1/3) == 1/3          |
|                                    |
|o15 = false                         |
+------------------------------------+

It may happen that for certain types of objects, there is no method installed
(yet) for testing mathematical equality, in which case an error message will be
printed.  A good alternative may be to test for strict equality with the
operator ===.

Since various sorts of mathematical objects are implemented as types, i.e., as
instances of Type, there is no generic method for checking
equality of types, so that new mathematical comparison code can be provided in
the future without breaking code that works.

Caveat
======

Warning: whether this comparison operator returns true is not necessarily
related to whether the comparison operator ?, returns symbol ==.

See also
========

  * != -- inequality
  * === -- strict equality
  * =!= -- strict inequality
  * operators

Ways to use symbol ==:
======================

  * BettiTally == BettiTally (missing documentation)
  * Boolean == Boolean (missing documentation)
  * CC == CC (missing documentation)
  * CC == QQ (missing documentation)
  * CC == RR (missing documentation)
  * CC == ZZ (missing documentation)
  * ChainComplex == ChainComplex (missing documentation)
  * ChainComplex == ZZ (missing documentation)
  * ChainComplexMap == ChainComplexMap (missing documentation)
  * ChainComplexMap == RingElement (missing documentation)
  * ChainComplexMap == ZZ (missing documentation)
  * CoherentSheaf == CoherentSheaf (missing documentation)
  * CoherentSheaf == ZZ (missing documentation)
  * Cone == Cone (Polyhedra) -- equality
  * Constant == Constant (missing documentation)
  * Constant == InexactNumber (missing documentation)
  * Constant == Number (missing documentation)
  * Constant == RingElement (missing documentation)
  * Fan == Fan (Polyhedra) -- equality
  * GradedModule == GradedModule (missing documentation)
  * GradedModuleMap == GradedModuleMap (missing documentation)
  * GradedModuleMap == RingElement (missing documentation)
  * GradedModuleMap == ZZ (missing documentation)
  * GroebnerBasis == GroebnerBasis (missing documentation)
  * Ideal == Ideal (missing documentation)
  * Ideal == Module (missing documentation)
  * Ideal == Ring (missing documentation)
  * Ideal == ZZ (missing documentation)
  * InexactNumber == Constant (missing documentation)
  * InexactNumber == RingElement (missing documentation)
  * InfiniteNumber == InfiniteNumber (missing documentation)
  * InfiniteNumber == Number (missing documentation)
  * InfiniteNumber == RR (missing documentation)
  * Matrix == Matrix (missing documentation)
  * Matrix == Number (missing documentation)
  * Matrix == RingElement (missing documentation)
  * Matrix == ZZ (missing documentation)
  * Module == Ideal (missing documentation)
  * Module == Module (missing documentation)
  * Module == ZZ (missing documentation)
  * MonoidElement == MonoidElement (missing documentation)
  * MonoidElement == ZZ (missing documentation)
  * MonomialIdeal == MonomialIdeal (missing documentation)
  * MonomialIdeal == ZZ (missing documentation)
  * MutableMatrix == MutableMatrix (missing documentation)
  * MutableMatrix == ZZ (missing documentation)
  * Net == Net (missing documentation)
  * Net == String (missing documentation)
  * Nothing == Nothing (missing documentation)
  * Number == Constant (missing documentation)
  * Number == InfiniteNumber (missing documentation)
  * Number == Matrix (missing documentation)
  * Number == RingElement (missing documentation)
  * Polyhedron == Polyhedron (Polyhedra), --
    equality
  * ProjectiveHilbertPolynomial == ProjectiveHilbertPolynomial (missing
    documentation)
  * ProjectiveHilbertPolynomial == ZZ (missing documentation)
  * QQ == CC (missing documentation)
  * QQ == QQ (missing documentation)
  * QQ == RR (missing documentation)
  * QQ == RRi (missing documentation)
  * QQ == ZZ (missing documentation)
  * Ring == Ideal (missing documentation)
  * Ring == ZZ (missing documentation)
  * RingElement == ChainComplexMap (missing documentation)
  * RingElement == Constant (missing documentation)
  * RingElement == GradedModuleMap (missing documentation)
  * RingElement == InexactNumber (missing documentation)
  * RingElement == Matrix (missing documentation)
  * RingElement == Number (missing documentation)
  * RingElement == RingElement (missing documentation)
  * RingElement == ZZ (missing documentation)
  * RingMap == ZZ (missing documentation)
  * RR == CC (missing documentation)
  * RR == InfiniteNumber (missing documentation)
  * RR == QQ (missing documentation)
  * RR == RR (missing documentation)
  * RR == RRi (missing documentation)
  * RR == ZZ (missing documentation)
  * RRi == QQ (missing documentation)
  * RRi == RR (missing documentation)
  * RRi == RRi (missing documentation)
  * RRi == ZZ (missing documentation)
  * Sequence == Sequence (missing documentation)
  * SheafMap == ZZ (missing documentation)
  * String == Net (missing documentation)
  * String == String (missing documentation)
  * Symbol == Symbol (missing documentation)
  * Vector == Vector (missing documentation)
  * VirtualTally == VirtualTally (missing documentation)
  * VirtualTally == ZZ (missing documentation)
  * VisibleList == VisibleList (missing documentation)
  * ZZ == CC (missing documentation)
  * ZZ == ChainComplex (missing documentation)
  * ZZ == ChainComplexMap (missing documentation)
  * ZZ == CoherentSheaf (missing documentation)
  * ZZ == GradedModuleMap (missing documentation)
  * ZZ == Ideal (missing documentation)
  * ZZ == Module (missing documentation)
  * ZZ == MonoidElement (missing documentation)
  * ZZ == MonomialIdeal (missing documentation)
  * ZZ == MutableMatrix (missing documentation)
  * ZZ == ProjectiveHilbertPolynomial (missing documentation)
  * ZZ == QQ (missing documentation)
  * ZZ == Ring (missing documentation)
  * ZZ == RingElement (missing documentation)
  * ZZ == RingMap (missing documentation)
  * ZZ == RR (missing documentation)
  * ZZ == RRi (missing documentation)
  * ZZ == SheafMap (missing documentation)
  * ZZ == VirtualTally (missing documentation)
  * ZZ == ZZ (missing documentation)

For the programmer
==================

The object ==, is a keyword.

This operator may be used as a binary operator in an expression like x==y. The
user may install binary methods, for handling such
expressions with code such as

         X == Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

!= -- inequality
****************

Description
===========

x != y -- the negation of x == y.

See also
========

  * == -- equality
  * operators

For the programmer
==================

The object !=, is a keyword.

Thing === Thing -- strict equality
**********************************

Synopsis
========

  * Operator: ===,
  * Usage:
        x === y
  * Inputs:
      * x
      * y
  * Outputs:
      * a Boolean value, whether the expressions x and y are
        strictly equal

Description
===========

Strictly equal expressions have the same type, so 0===0. and 0===0/1 are false;
the three types involved here are ZZ, RR, and QQ.

If x and y are isMutable, then they are strictly equal only if
they are identical (i.e., at the same address in memory).  For details about
why strict equality cannot depend on the contents of mutable hash tables, see
hashing.  On the other hand, if x and y are non-mutable, then
they are strictly equal if and only if all their contents are strictly equal.

+------------------------+
|i1 : {1,2,3} === {1,2,3}|
|                        |
|o1 = true               |
+------------------------+
|i2 : {1,2,3} === {2,1,3}|
|                        |
|o2 = false              |
+------------------------+

For some types, such as ring elements and matrices, strict equality is the same
as mathematical equality. This tends to be the case for objects for which not
much computation is not required to test equality. For certain other types,
such as Ideal, or Module, where extensive
computations may be required, the operator ==, implements the desired
comparison.

+------------------------------------------------------+
|i3 : R = QQ[a..d];                                    |
+------------------------------------------------------+
|i4 : a^2+b === b+a^2                                  |
|                                                      |
|o4 = true                                             |
+------------------------------------------------------+
|i5 : ideal(a^2+b,c*d) === ideal(b+a^2,c*d+b+a^2)      |
|                                                      |
|o5 = false                                            |
+------------------------------------------------------+
|i6 : matrix{{a,b,c}} === matrix{{a,b,c}}              |
|                                                      |
|o6 = true                                             |
+------------------------------------------------------+
|i7 : matrix{{a,b,c}} === transpose matrix{{a},{b},{c}}|
|                                                      |
|o7 = false                                            |
+------------------------------------------------------+

As it happens, polynomial rings are mutable objects, and new ones are easily
created, which are distinct from each other. For example, the rings A and B
below are not strictly equal.

+--------------------------+
|i8 : A = QQ[x]; B = QQ[x];|
+--------------------------+
|i10 : A === B             |
|                          |
|o10 = false               |
+--------------------------+

See also
========

  * == -- equality
  * =!= -- strict inequality
  * operators

Ways to use this method:
========================

  * Thing === Thing -- strict equality

=!= -- strict inequality
************************

Description
===========

x =!= y -- returns true or false depending on whether the expressions x and y
are strictly unequal.

See ===, for details.

Ways to use symbol =!=:
=======================

  * "Thing =!= Thing"

For the programmer
==================

The object =!=, is a keyword.

< -- less than
**************

Description
===========

x < y yields true, or false, depending on whether x <
y.

Calls upon ?, to perform the comparison, if necessary.

For the programmer
==================

The object <, is a keyword.

This operator may be used as a prefix unary operator in an expression like <y.
The user may install a method, for handling such
expressions with code such as

           < Y := (y) -> ...

where Y is the class of y.

<= -- less than or equal
************************

Description
===========

x <= y yields true, or false, depending on whether x
<= y.

Calls upon ?, to perform the comparison, if necessary.

For the programmer
==================

The object <=, is a keyword.

This operator may be used as a prefix unary operator in an expression like <=y.
The user may install a method, for handling such
expressions with code such as

           <= Y := (y) -> ...

where Y is the class of y.

> -- greater than
*****************

Description
===========

x > y yields true, or false, depending on whether x >
y.

Calls upon ?, to perform the comparison, if necessary.

Ways to use symbol >:
=====================

  * "> InfiniteNumber" -- see > ZZ (Varieties),
  * > ZZ (Varieties)

For the programmer
==================

The object >, is a keyword.

This operator may be used as a prefix unary operator in an expression like >y.
The user may install a method, for handling such
expressions with code such as

           > Y := (y) -> ...

where Y is the class of y.

>= -- greater than or equal
***************************

Synopsis
========

  * Usage:
        x >= y
  * Inputs:
      * x
      * y
  * Outputs:
      * a Boolean value, depending on whether x >= y

Description
===========

Calls upon ?, to perform the comparison, if necessary.

Ways to use symbol >=:
======================

  * >= List (missing documentation)
  * ">= InfiniteNumber" -- see >= ZZ (Varieties),
  * >= ZZ (Varieties)

For the programmer
==================

The object >=, is a keyword.

This operator may be used as a prefix unary operator in an expression like >=y.
The user may install a method, for handling such
expressions with code such as

           >= Y := (y) -> ...

where Y is the class of y.

? -- comparison operator
************************

Synopsis
========

  * Usage:
        x ? y
  * Inputs:
      * x
      * y
  * Outputs:
      * One of the symbols symbol <, symbol >, symbol ==, or incomparable,
        depending (respectively) on whether x < y, x > y, x == y, or x and y
        are not comparable.

Description
===========

Many types of objects may be compared.  Numbers are handled as one would
expect, and strings, lists and sequences are generally compared
lexicographically.
+-----------------------+
|i1 : 3 ? 4             |
|                       |
|o1 = <                 |
|                       |
|o1 : Keyword           |
+-----------------------+
|i2 : "book" ? "boolean"|
|                       |
|o2 = <                 |
|                       |
|o2 : Keyword           |
+-----------------------+
|i3 : 3 ? 3.            |
|                       |
|o3 = ==                |
|                       |
|o3 : Keyword           |
+-----------------------+
|i4 : {1,2,3} ? {4,5}   |
|                       |
|o4 = <                 |
|                       |
|o4 : Keyword           |
+-----------------------+

Polynomials from the same ring may also be compared.  The order depends on the
monomial order in the ring.
+-------------------+
|i5 : R = ZZ[a,b,c] |
|                   |
|o5 = R             |
|                   |
|o5 : PolynomialRing|
+-------------------+
|i6 : a*c ? b^2     |
|                   |
|o6 = <             |
|                   |
|o6 : Keyword       |
+-------------------+
A set is smaller than another if it is a subset; for tallies, corresponding
counts should all be smaller.
+-------------------------------------+
|i7 : set {1,2} ? set {2,3}           |
|                                     |
|o7 = incomparable                    |
|                                     |
|o7 : Symbol                          |
+-------------------------------------+
|i8 : set {1,2} ? set {1,2,3}         |
|                                     |
|o8 = <                               |
|                                     |
|o8 : Keyword                         |
+-------------------------------------+
|i9 : tally {1,1,2} ? tally {1,2,3}   |
|                                     |
|o9 = incomparable                    |
|                                     |
|o9 : Symbol                          |
+-------------------------------------+
|i10 : tally {1,1,2} ? tally {1,1,2,3}|
|                                     |
|o10 = <                              |
|                                     |
|o10 : Keyword                        |
+-------------------------------------+

See also
========

  * sort -- sort a list or columns of a matrix
  * rsort -- sort a list or matrix in reverse order
  * ? Symbol -- view brief documentation of a symbol

Ways to use symbol ?:
=====================

  * "IndexedVariable ? IndexedVariable"
  * "List ? List"
  * "Symbol ? IndexedVariable"
  * "VirtualTally ? VirtualTally"
  * ? Command (missing documentation)
  * "? Function" -- see ? Symbol, -- view brief documentation
    of a symbol
  * "? Keyword" -- see ? Symbol, -- view brief documentation of
    a symbol
  * "? Package" -- see ? Symbol, -- view brief documentation of
    a symbol
  * "? ScriptedFunctor" -- see ? Symbol, -- view brief
    documentation of a symbol
  * ? Symbol -- view brief documentation of a symbol
  * "? Type" -- see ? Symbol, -- view brief documentation of a
    symbol
  * "Bag ? Bag" -- see Bag, -- the class of all bags
  * CC ? InfiniteNumber (missing documentation)
  * Cone ? Cone (Polyhedra) -- compares the Cones
  * Constant ? Constant (missing documentation)
  * Constant ? Number (missing documentation)
  * InexactNumber ? Constant (missing documentation)
  * InfiniteNumber ? CC (missing documentation)
  * InfiniteNumber ? RR (missing documentation)
  * Module ? Module (missing documentation)
  * MonoidElement ? MonoidElement (missing documentation)
  * Number ? Constant (missing documentation)
  * Option ? Option (missing documentation)
  * RR ? InfiniteNumber (missing documentation)
  * VirtualTally ? ZZ (missing documentation)
  * ZZ ? VirtualTally (missing documentation)

For the programmer
==================

The object ?, is a keyword.

This operator may be used as a binary operator in an expression like x?y. The
user may install binary methods, for handling such
expressions with code such as

         X ? Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

This operator may be used as a prefix unary operator in an expression like ?y.
The user may install a method, for handling such
expressions with code such as

           ? Y := (y) -> ...

where Y is the class of y.

and -- conjunction
******************

Description
===========

t and u -- returns true if t is true and u is true.

If t is false, then the code in u is not evaluated.

See also
========

  * or -- disjunction
  * not -- negation
  * xor -- exclusive disjunction

For the programmer
==================

The object and, is a keyword.

This operator may be used as a binary operator in an expression like x and y.
The user may install binary methods, for handling such
expressions with code such as

         X  and  Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

or -- disjunction
*****************

Description
===========

t or u -- returns true if t is true or u is true.

If t is true, then the code in u is not evaluated.

See also
========

  * and -- conjunction
  * not -- negation
  * xor -- exclusive disjunction

For the programmer
==================

The object or, is a keyword.

This operator may be used as a binary operator in an expression like x or y.
The user may install binary methods, for handling such
expressions with code such as

         X  or  Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

not -- negation
***************

Description
===========

not x -- yields the negation of x, which must be true or false.

See also
========

  * and -- conjunction
  * or -- disjunction

For the programmer
==================

The object not, is a keyword.

This operator may be used as a prefix unary operator in an expression like  not
y. The user may install a method, for handling such
expressions with code such as

            not  Y := (y) -> ...

where Y is the class of y.

SPACE -- blank operator; often used for function application, making polynomial rings
*************************************************************************************

See also
========

  * Function Thing -- function application

Ways to use symbol SPACE:
=========================

  * "BettiTally Array" -- see BettiTally, -- the class of all
    Betti tallies
  * "BettiTally ZZ" -- see BettiTally, -- the class of all
    Betti tallies
  * ChainComplex Array -- degree shift
  * ChainComplexMap Array -- degree shift
  * CoherentSheaf Sequence (missing documentation)
  * CoherentSheaf ZZ (Varieties) -- canonical twist of
    a coherent sheaf
  * "SheafOfRings ZZ" -- see CoherentSheaf ZZ (Varieties),
    -- canonical twist of a coherent sheaf
  * "Command Thing" -- see Command, -- the class of all commands
  * Function Thing -- function application
  * GradedModule Array -- degree shift
  * "HeaderType List" -- see HeaderType, -- a class of lists
    with abbreviated constructors
  * "HeaderType Sequence" -- see HeaderType, -- a class of
    lists with abbreviated constructors
  * "CoherentSheaf LowerBound" -- see LowerBound (Varieties),
    -- the class of lower bound objects
  * "SheafOfRings LowerBound" -- see LowerBound (Varieties),
    -- the class of lower bound objects
  * "Manipulator Database" -- see Manipulator, -- the class
    of all file manipulators
  * "Manipulator File" -- see Manipulator, -- the class of
    all file manipulators
  * "Manipulator Nothing" -- see Manipulator, -- the class
    of all file manipulators
  * Matrix Vector (missing documentation)
  * Module Array -- make a chain complex from a module
  * MonoidElement Array (missing documentation)
  * "MultigradedBettiTally Sequence" -- see MultigradedBettiTally,
    -- the class of all multigraded Betti tallies
  * MultigradedBettiTally List (missing documentation)
  * "Manipulator NetFile" -- see NetFile, -- the class of all
    net files
  * ProjectiveHilbertPolynomial ZZ, --
    value of polynomial
  * Ring AngleBarList (missing documentation)
  * "InexactFieldFamily Array" -- see Ring Array, -- the
    standard way to make a polynomial ring
  * Ring Array -- the standard way to make a polynomial ring
  * "InexactFieldFamily List" -- see Ring List, -- make a
    local polynomial ring
  * Ring List -- make a local polynomial ring
  * "InexactFieldFamily Monoid" -- see Ring Monoid, -- make
    a polynomial ring
  * Ring Monoid -- make a polynomial ring
  * "RingElement Number" -- see RingElement Sequence,
    -- evaluation of polynomials
  * "RingElement RingElement" -- see RingElement Sequence,
    -- evaluation of polynomials
  * RingElement Sequence -- evaluation of
    polynomials
  * RingMap ChainComplexMap (missing documentation)
  * RingMap MutableMatrix (missing documentation)
  * RingMap Power (missing documentation)
  * RingMap Product (missing documentation)
  * "RingMap ChainComplex" -- see RingMap RingElement,
    -- apply a ring map
  * "RingMap Ideal" -- see RingMap RingElement, --
    apply a ring map
  * "RingMap Matrix" -- see RingMap RingElement, --
    apply a ring map
  * "RingMap Module" -- see RingMap RingElement, --
    apply a ring map
  * RingMap RingElement -- apply a ring map
  * "RingMap Vector" -- see RingMap RingElement, --
    apply a ring map
  * RingMap Sum (missing documentation)
  * "ScriptedFunctor Thing" -- see ScriptedFunctor, --
    the class of all scripted functors
  * "SelfInitializingType Thing" -- see SelfInitializingType,
    -- the class of all self initializing types
  * SheafMap ZZ (missing documentation)
  * SheafOfRings Sequence (missing documentation)
  * "WrapperType List" -- see WrapperType, -- a class of
    lists with abbreviated constructors
  * "WrapperType Sequence" -- see WrapperType, -- a class of
    lists with abbreviated constructors
  * "WrapperType Thing" -- see WrapperType, -- a class of
    lists with abbreviated constructors

For the programmer
==================

The object SPACE, is a keyword.

This operator may be used as a binary operator in an expression like x SPACE y.
The user may install binary methods, for handling such
expressions with code such as

         X Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

-> -- make a function
*********************

Description
===========

x -> e -- denotes a function.  When the function is called, the initial value
of the variable x is the argument if there is just one, or else is the sequence
of arguments.
(x) -> e -- denotes a function of one argument.  When the function is applied
to an expression w three things may happen:
  * if w is not a sequence, then the initial value of x is w;
  * if w is a sequence of length one, then the initial value of x is the unique
    element of w; or
  * if w is a sequence of length other than one, then it is an error.

(x,y) -> e -- denotes a function of two arguments.

Similarly for more arguments.

These operations create what is usually called a closure, which signifies that
the function remembers the values of local variables in effect at the time of
its creation, can change those values, and share the changes with other
functions created at the same time.
+--------------------+
|i1 : f = x -> 2*x+1 |
|                    |
|o1 = f              |
|                    |
|o1 : FunctionClosure|
+--------------------+
|i2 : f 100          |
|                    |
|o2 = 201            |
+--------------------+
The class of all functions is Function.

For the programmer
==================

The object ->, is a keyword.

@@ -- a binary operator
***********************

Ways to use symbol @@:
======================

  * Function @@ Function -- composition of
    functions

For the programmer
==================

The object @@, is a keyword.

This operator may be used as a binary operator in an expression like x@@y. The
user may install binary methods, for handling such
expressions with code such as

         X @@ Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

\\ -- a binary operator
***********************

Ways to use symbol \\:
======================

  * Matrix \\ Matrix (missing documentation)
  * Matrix \\ Number (missing documentation)
  * Matrix \\ RingElement (missing documentation)
  * Number \\ Matrix (missing documentation)
  * RingElement \\ Matrix (missing documentation)
  * /// Command \\ Thing /// -- see Thing // Function,
    -- apply a function
  * /// Function \\ Thing /// -- see Thing // Function,
    -- apply a function
  * /// SelfInitializingType \\ Thing /// -- see Thing // Function,
    -- apply a function

For the programmer
==================

The object \\, is a keyword.

This operator may be used as a binary operator in an expression like x\\y. The
user may install binary methods, for handling such
expressions with code such as

         X \\ Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

\ -- a binary operator
**********************

Ways to use symbol \:
=====================

  * Command \ Set (missing documentation)
  * Function \ Set (missing documentation)
  * /// Function \ Ideal /// -- see Ideal / Function,
    -- apply a function to generators of an ideal
  * /// Command \ String /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// Command \ VirtualTally /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// Command \ VisibleList /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// Function \ String /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// Function \ VirtualTally /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// Function \ VisibleList /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// RingMap \ VisibleList /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// SelfInitializingType \ VisibleList /// -- see VisibleList / Function,
    -- apply a function to elements of a list

For the programmer
==================

The object \, is a keyword.

This operator may be used as a binary operator in an expression like x\y. The
user may install binary methods, for handling such
expressions with code such as

         X \ Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

_ -- a binary operator, used for subscripting and access to elements
********************************************************************

Ways to use symbol _:
=====================

  * ChainComplex _ ZZ -- component
  * "GradedModule _ ZZ" -- see ChainComplex _ ZZ, --
    component
  * ChainComplex _ ZZ = Thing -- install
    component of chain complex
  * ChainComplexMap _ ZZ -- component map
  * "GradedModuleMap _ ZZ" -- see ChainComplexMap _ ZZ,
    -- component map
  * ChainComplexMap _ ZZ = Thing, --
    install component of chain complex map
  * CoherentSheaf _ Array (missing documentation)
  * Function _ Thing -- attach the first argument to
    a function of two or more arguments
  * "Ideal _ ZZ" -- see generators of ideals and modules,
  * "Matrix _ ZZ" -- see generators of ideals and modules,
  * "Module _ ZZ" -- see generators of ideals and modules,
  * IndexedVariable _ Ring -- get a ring
    variable by name
  * "IndexedVariableTable _ Thing" -- see IndexedVariableTable,
  * "IndexedVariableTable _ Thing = Thing" -- see IndexedVariableTable,
  * "ChainComplexMap _ Array" -- see Matrix _ Array, --
    component of map corresponding to summand of source
  * "GradedModuleMap _ Array" -- see Matrix _ Array, --
    component of map corresponding to summand of source
  * Matrix _ Array -- component of map corresponding
    to summand of source
  * Matrix _ List -- select columns
  * Matrix _ Sequence -- get entry of matrix
  * "MutableMatrix _ Sequence" -- see Matrix _ Sequence,
    -- get entry of matrix
  * "ChainComplex _ Array" -- see Module _ Array, --
    inclusion from summand
  * Module _ Array -- inclusion from summand
  * "Ideal _ List" -- see Module _ List, -- map from
    free module to some generators
  * Module _ List -- map from free module to some
    generators
  * MonoidElement _ Ring (missing documentation)
  * MonoidElement _ Thing (missing documentation)
  * MutableMatrix _ List (missing documentation)
  * MutableMatrix _ Sequence = Thing,
    -- assignment to an element of a mutable matrix
  * Partition _ ZZ -- get element
  * "Number _ Ring" -- see promote, -- promote to another ring
  * "RingElement _ Ring" -- see promote, -- promote to another
    ring
  * Pseudocode _ ZZ (missing documentation)
  * Ring _ List -- make a monomial from a list of
    exponents
  * Ring _ ZZ -- get a ring variable by index
  * RingElement _ Monoid (missing documentation)
  * RingElement _ Thing (missing documentation)
  * "ScriptedFunctor _ Thing" -- see ScriptedFunctor, --
    the class of all scripted functors
  * String _ Ring -- get a ring variable by name
  * String _ Sequence -- substring
  * String _ ZZ -- get element from string
  * Symbol _ Ring -- get a ring variable by name
  * Symbol _ Thing -- index variable
  * Symbol _ Thing = Thing -- assignment to an
    indexed variable
  * VirtualTally _ Thing -- get a count from a
    tally
  * VisibleList _ List -- get some entries of a
    list
  * VisibleList _ ZZ -- get element from list
  * ZZ _ Module -- integers or zero element

For the programmer
==================

The object _, is a keyword.

This operator may be used as a binary operator in an expression like x_y. The
user may install binary methods, for handling such
expressions with code such as

         X _ Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

. -- access to elements whose key is a symbol
*********************************************

Description
===========

x.k -- the same as x#(global k), i.e., treat k as a global symbol and provide
the value stored in the hash table x under the key k.

May also be used in an assignment.

+-------------------------------+
|i1 : x = new MutableHashTable; |
+-------------------------------+
|i2 : x.k = 444                 |
|                               |
|o2 = 444                       |
+-------------------------------+
|i3 : x.k                       |
|                               |
|o3 = 444                       |
+-------------------------------+
|i4 : peek x                    |
|                               |
|o4 = MutableHashTable{k => 444}|
+-------------------------------+

See also
========

  * # -- length or access to elements
  * .? -- check for presence of elements whose key is a symbol
  * global -- get a global symbol

For the programmer
==================

The object ., is a keyword.

.? -- check for presence of elements whose key is a symbol
**********************************************************

Description
===========

x.?k -- the same as x#?(global k), tells whether a value is available with x.k.

See also
========

  * . -- access to elements whose key is a symbol
  * #? -- check existence of value in a list, hash table, database,
    or string

For the programmer
==================

The object .?, is a keyword.

# -- length or access to elements
*********************************

Description
===========

# is used as both a unary and a binary operator.

As a unary operator: #x returns the length or cardinality of a list, set, hash
table, or string x.

As a binary operator: x#i returns the ith element of a list, hash table,
database, or string x.

+------------------------------+
|i1 : L = {23, 42, 107, 2, 50};|
+------------------------------+
|i2 : #L                       |
|                              |
|o2 = 5                        |
+------------------------------+
|i3 : L#2                      |
|                              |
|o3 = 107                      |
+------------------------------+

Caveat
======

The precedence of # when used as a binary operator is high, as high as .,
but when used as a unary operator the precedence is much lower.

See also
========

  * #? -- check existence of value in a list, hash table, database,
    or string
  * # BasicList -- length or cardinality
  * BasicList # ZZ -- get value from list, hash table,
    database, or string
  * hash tables
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use symbol #:
=====================

  * # BasicList -- length or cardinality
  * "# HashTable" -- see # BasicList, -- length or
    cardinality
  * "# Set" -- see # BasicList, -- length or cardinality
  * "# String" -- see # BasicList, -- length or cardinality
  * # Dictionary (missing documentation)
  * # List (missing documentation)
  * # Net (missing documentation)
  * # Sequence (missing documentation)
  * BasicList # ZZ -- get value from list, hash table,
    database, or string
  * "Database # String" -- see BasicList # ZZ, -- get
    value from list, hash table, database, or string
  * "HashTable # Thing" -- see BasicList # ZZ, -- get
    value from list, hash table, database, or string
  * "String # ZZ" -- see BasicList # ZZ, -- get value
    from list, hash table, database, or string
  * Dictionary # String (missing documentation)
  * List # ZZ (missing documentation)
  * Net # ZZ (missing documentation)
  * Sequence # ZZ (missing documentation)

For the programmer
==================

The object #, is a keyword.

#? -- check existence of value in a list, hash table, database, or string
*************************************************************************

Synopsis
========

  * Usage:
        x#?i
  * Inputs:
      * x, a list, hash table, or string
      * i, an index or key
  * Outputs:
      * a Boolean value, whether or not x contains an element
        with index or key i

Description
===========

If x is a list, x#?i tells whether there is an ith element of x. The entries of
the list are numbered starting with 0. If i is negative, then the entries are
numbered ending with -1.

+-------------------------+
|i1 : L = {a, b, c, b, a};|
+-------------------------+
|i2 : L#?2                |
|                         |
|o2 = true                |
+-------------------------+
|i3 : L#?12               |
|                         |
|o3 = false               |
+-------------------------+

If x is a hash table or database, x#?i tells whether there is a value
associated with the key i.

+-----------------------------------------------------------+
|i4 : T = new HashTable from {a => 103, b => 89.4, c => 92};|
+-----------------------------------------------------------+
|i5 : T#?a                                                  |
|                                                           |
|o5 = true                                                  |
+-----------------------------------------------------------+
|i6 : T#?A                                                  |
|                                                           |
|o6 = false                                                 |
+-----------------------------------------------------------+

If x is a string, x#?i tells if x has an ith character.

+----------------------------------------------------+
|i7 : s = "a perfectly adequate example of a string";|
+----------------------------------------------------+
|i8 : s#?2                                           |
|                                                    |
|o8 = true                                           |
+----------------------------------------------------+
|i9 : s#?52                                          |
|                                                    |
|o9 = false                                          |
+----------------------------------------------------+

#? can be very useful in avoiding errors from attempting to access nonexistent
elements of lists or hash tables.

See also
========

  * # -- length or access to elements
  * # BasicList -- length or cardinality
  * VisibleList _ ZZ -- get element from list
  * hash tables
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use symbol #?:
======================

  * "BasicList #? ZZ"
  * "Database #? String"
  * "HashTable #? Thing"
  * "String #? ZZ"
  * Dictionary #? String (missing documentation)
  * List #? ZZ (missing documentation)
  * Net #? ZZ (missing documentation)
  * Nothing #? Thing (missing documentation)
  * Sequence #? ZZ (missing documentation)
  * Set #? Thing -- test set membership

For the programmer
==================

The object #?, is a keyword.

! -- factorial
**************

Synopsis
========

  * Usage:
        n!
  * Inputs:
      * n, an integer,
  * Outputs:
      * an integer, n factorial, 1*2*3*...*n.

Description
===========

+--------------------------------------+
|i1 : 30!                              |
|                                      |
|o1 = 265252859812191058636308480000000|
+--------------------------------------+
|i2 : 30.!                             |
|                                      |
|o2 = 2.652528598121911e32             |
|                                      |
|o2 : RR (of precision 53)             |
+--------------------------------------+
|i3 : 30.01!                           |
|                                      |
|o3 = 2.744757494732821e32             |
|                                      |
|o3 : RR (of precision 53)             |
+--------------------------------------+

Ways to use symbol !:
=====================

  * "Constant !"
  * "QQ !"
  * "RR !"
  * "ZZ !"

For the programmer
==================

The object !, is a keyword.

This operator may be used as a postfix unary operator in an expression like x!.
The user may install a method, for handling such expressions with
code such as

         X !   := (x) -> ...

where X is the class of x.

+ -- a unary or binary operator, usually used for addition
**********************************************************

Synopsis
========

  * Usage:
        +y
        x+y

Description
===========

In most cases, this operator refers to standard addition.

In many cases, the integer 1 can be used as the identity, and scalars function
as multiples of the identity. For example, the 1 below refers to the identity
matrix and the 2 to twice the identity matrix.
+----------------------------------------+
|i1 : M = matrix{{1,2,3},{2,3,4},{3,4,6}}|
|                                        |
|o1 = | 1 2 3 |                          |
|     | 2 3 4 |                          |
|     | 3 4 6 |                          |
|                                        |
|              3       3                 |
|o1 : Matrix ZZ  <-- ZZ                  |
+----------------------------------------+
|i2 : M+1, M+2                           |
|                                        |
|o2 = (| 2 2 3 |, | 3 2 3 |)             |
|      | 2 4 4 |  | 2 5 4 |              |
|      | 3 4 7 |  | 3 4 8 |              |
|                                        |
|o2 : Sequence                           |
+----------------------------------------+

Intervals
---------

If one of the addends is an RRi, the output is an interval
containing all sums of pairs in the addends.

+----------------------------------+
|i3 : 2+interval(1,3)              |
|                                  |
|o3 = [3,5]                        |
|                                  |
|o3 : RRi (of precision 53)        |
+----------------------------------+
|i4 : interval(1,3)+interval(-1,2) |
|                                  |
|o4 = [0,5]                        |
|                                  |
|o4 : RRi (of precision 53)        |
+----------------------------------+
|i5 : interval(-1,1)+interval(-1,1)|
|                                  |
|o5 = [-2,2]                       |
|                                  |
|o5 : RRi (of precision 53)        |
+----------------------------------+

See also
========

  * plus -- addition
  * sum -- compute the sum

Ways to use symbol +:
=====================

  * "+ CC"
  * "+ Constant"
  * "+ QQ"
  * "+ RR"
  * "+ RRi"
  * "+ Vector"
  * "+ ZZ"
  * "CC + CC"
  * "CC + QQ"
  * "CC + RR"
  * "CC + ZZ"
  * "ChainComplexMap + ChainComplexMap"
  * "ChainComplexMap + RingElement"
  * "ChainComplexMap + ZZ"
  * "Constant + Constant"
  * "Constant + InexactNumber"
  * "Constant + Number"
  * "GradedModuleMap + GradedModuleMap"
  * "GradedModuleMap + RingElement"
  * "Ideal + RingElement"
  * "InexactNumber + Constant"
  * "InfiniteNumber + InfiniteNumber"
  * "InfiniteNumber + Number"
  * "Matrix + Matrix"
  * "Matrix + Number"
  * "Matrix + RingElement"
  * "MonomialIdeal + MonomialIdeal"
  * "MutableMatrix + MutableMatrix"
  * "Number + Constant"
  * "Number + InfiniteNumber"
  * "Number + Matrix"
  * "ProjectiveHilbertPolynomial + ProjectiveHilbertPolynomial"
  * "ProjectiveHilbertPolynomial + ZZ"
  * "QQ + CC"
  * "QQ + QQ"
  * "QQ + RR"
  * "QQ + RRi"
  * "QQ + ZZ"
  * "RingElement + ChainComplexMap"
  * "RingElement + GradedModuleMap"
  * "RingElement + Matrix"
  * "RingElement + RingElement"
  * "RR + CC"
  * "RR + QQ"
  * "RR + RR"
  * "RR + RRi"
  * "RR + ZZ"
  * "RRi + QQ"
  * "RRi + RR"
  * "RRi + RRi"
  * "RRi + ZZ"
  * "Vector + Vector"
  * "ZZ + CC"
  * "ZZ + ChainComplexMap"
  * "ZZ + ProjectiveHilbertPolynomial"
  * "ZZ + QQ"
  * "ZZ + RR"
  * "ZZ + RRi"
  * "ZZ + ZZ"
  * + RingElement (missing documentation)
  * CC + InfiniteNumber (missing documentation)
  * Cone + Cone (Polyhedra) -- computes the Minkowski sum of
    two cones
  * Cone + Polyhedron (Polyhedra) -- computes the
    Minkowski sum of a cone and a polyhedron
  * "Constant + RingElement" -- see Constant,
  * "RingElement + Constant" -- see Constant,
  * Ideal + Ideal -- sum of ideals
  * Ideal + Number (missing documentation)
  * InexactNumber + RingElement (missing documentation)
  * InfiniteNumber + CC (missing documentation)
  * List + List -- sum of two vectors
  * Module + Module -- sum of submodules
  * Number + Ideal (missing documentation)
  * Polyhedron + Cone (Polyhedra) -- computes the
    Minkowski sum of a polyhedron and a cone
  * Polyhedron + Polyhedron (Polyhedra), --
    computes the Minkowski sum of two polyhedra
  * RingElement + Ideal (missing documentation)
  * RingElement + InexactNumber (missing documentation)
  * Tally + Tally -- union of tallies
  * "Set + Set" -- see union(Set,Set), -- set union
  * VirtualTally + VirtualTally -- union of
    tallies

For the programmer
==================

The object +, is a keyword.

This operator may be used as a binary operator in an expression like x+y. The
user may install binary methods, for handling such
expressions with code such as

         X + Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

This operator may be used as a prefix unary operator in an expression like +y.
The user may install a method, for handling such
expressions with code such as

           + Y := (y) -> ...

where Y is the class of y.

- -- a unary or binary operator, usually used for negation or subtraction
*************************************************************************

Synopsis
========

  * Usage:
        -y
        x-y

Description
===========

In most cases, this operator refers to standard negation or subtraction.

In many cases, the integer 1 can be used as the identity, and scalars function
as multiples of the identity. For example, the 1 below refers to the identity
matrix and the 2 to twice the identity matrix.
+----------------------------------------+
|i1 : M = matrix{{1,2,3},{2,3,4},{3,4,6}}|
|                                        |
|o1 = | 1 2 3 |                          |
|     | 2 3 4 |                          |
|     | 3 4 6 |                          |
|                                        |
|              3       3                 |
|o1 : Matrix ZZ  <-- ZZ                  |
+----------------------------------------+
|i2 : M-1, M-2                           |
|                                        |
|o2 = (| 0 2 3 |, | -1 2 3 |)            |
|      | 2 2 4 |  | 2  1 4 |             |
|      | 3 4 5 |  | 3  4 4 |             |
|                                        |
|o2 : Sequence                           |
+----------------------------------------+

Intervals
---------

If one of the inputs is an RRi, the output is an interval
containing all differences of pairs in the inputs.

+----------------------------------+
|i3 : 2-interval(1,3)              |
|                                  |
|o3 = [-1,1]                       |
|                                  |
|o3 : RRi (of precision 53)        |
+----------------------------------+
|i4 : interval(1,3)-interval(-1,2) |
|                                  |
|o4 = [-1,4]                       |
|                                  |
|o4 : RRi (of precision 53)        |
+----------------------------------+
|i5 : interval(-1,1)-interval(-1,1)|
|                                  |
|o5 = [-2,2]                       |
|                                  |
|o5 : RRi (of precision 53)        |
+----------------------------------+

See also
========

  * difference -- difference
  * minus -- additive inverse

Ways to use symbol -:
=====================

  * "- CC"
  * "- ChainComplexMap"
  * "- Constant"
  * "- GradedModuleMap"
  * "- InfiniteNumber"
  * "- Matrix"
  * "- MutableMatrix"
  * "- ProjectiveHilbertPolynomial"
  * "- QQ"
  * "- RingElement"
  * "- RR"
  * "- RRi"
  * "- ZZ"
  * "CC - CC"
  * "CC - QQ"
  * "CC - RR"
  * "CC - ZZ"
  * "ChainComplexMap - ChainComplexMap"
  * "ChainComplexMap - RingElement"
  * "Constant - Constant"
  * "Constant - InexactNumber"
  * "Constant - Number"
  * "GradedModuleMap - GradedModuleMap"
  * "GradedModuleMap - RingElement"
  * "InexactNumber - Constant"
  * "InfiniteNumber - InfiniteNumber"
  * "InfiniteNumber - Number"
  * "Matrix - Matrix"
  * "Matrix - Number"
  * "Matrix - RingElement"
  * "MutableMatrix - MutableMatrix"
  * "Number - Constant"
  * "Number - InfiniteNumber"
  * "Number - Matrix"
  * "ProjectiveHilbertPolynomial - ProjectiveHilbertPolynomial"
  * "ProjectiveHilbertPolynomial - ZZ"
  * "QQ - CC"
  * "QQ - QQ"
  * "QQ - RR"
  * "QQ - RRi"
  * "QQ - ZZ"
  * "RingElement - ChainComplexMap"
  * "RingElement - GradedModuleMap"
  * "RingElement - Matrix"
  * "RingElement - RingElement"
  * "RR - CC"
  * "RR - QQ"
  * "RR - RR"
  * "RR - RRi"
  * "RR - ZZ"
  * "RRi - QQ"
  * "RRi - RR"
  * "RRi - RRi"
  * "RRi - ZZ"
  * "Vector - Vector"
  * "ZZ - CC"
  * "ZZ - ProjectiveHilbertPolynomial"
  * "ZZ - QQ"
  * "ZZ - RR"
  * "ZZ - RRi"
  * "ZZ - ZZ"
  * - List -- negation of a vector
  * - SheafMap (missing documentation)
  * - Tally (missing documentation)
  * - Vector -- negation of a Vector
  * - VirtualTally -- negation of a VirtualTally
  * CC - InfiniteNumber (missing documentation)
  * "Constant - RingElement" -- see Constant,
  * "RingElement - Constant" -- see Constant,
  * InexactNumber - RingElement (missing documentation)
  * InfiniteNumber - CC (missing documentation)
  * List - List -- difference of two vectors
  * MonomialIdeal - MonomialIdeal, --
    monomial ideal difference
  * RingElement - InexactNumber (missing documentation)
  * "List - Set" -- see Set - Set, -- set difference
  * "Set - List" -- see Set - Set, -- set difference
  * Set - Set -- set difference
  * Tally - Tally -- difference of tallies
  * "VirtualTally - VirtualTally" -- see VirtualTally,

For the programmer
==================

The object -, is a keyword.

This operator may be used as a binary operator in an expression like x-y. The
user may install binary methods, for handling such
expressions with code such as

         X - Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

This operator may be used as a prefix unary operator in an expression like -y.
The user may install a method, for handling such
expressions with code such as

           - Y := (y) -> ...

where Y is the class of y.

* -- a binary operator, usually used for multiplication
*******************************************************

Synopsis
========

  * Usage:
        x * y

Description
===========

The return type depends on the types of x and y.  If they have the same type,
then usually the return type is the common type of x and y.

Multiplication involving ring elements (including integers, rational numbers,
real and complex numbers), ideals, vectors, matrices, modules is generally the
usual multiplication, or composition of functions.

The intersection of sets is given by multiplication.  See Set * Set.
+--------------------------------------------+
|i1 : set{hi,you,there} * set{hi,us,here,you}|
|                                            |
|o1 = set {you, hi}                          |
|                                            |
|o1 : Set                                    |
+--------------------------------------------+

Multiplication involving a list attempts to multiply each element of the list.
+--------------------+
|i2 : R = QQ[a..d];  |
+--------------------+
|i3 : a * {b,c,d}    |
|                    |
|o3 = {a*b, a*c, a*d}|
|                    |
|o3 : List           |
+--------------------+

Multiplication of matrices (see Matrix * Matrix) or ring
maps is the same as composition.
+---------------------------------------------+
|i4 : f = map(R,R,{b,c,a,d})                  |
|                                             |
|o4 = map (R, R, {b, c, a, d})                |
|                                             |
|o4 : RingMap R <-- R                         |
+---------------------------------------------+
|i5 : g = map(R,R,{(a+b)^2,b^2,c^2,d^2})      |
|                                             |
|                  2           2   2   2   2  |
|o5 = map (R, R, {a  + 2a*b + b , b , c , d })|
|                                             |
|o5 : RingMap R <-- R                         |
+---------------------------------------------+
|i6 : f*g                                     |
|                                             |
|                  2           2   2   2   2  |
|o6 = map (R, R, {b  + 2b*c + c , c , a , d })|
|                                             |
|o6 : RingMap R <-- R                         |
+---------------------------------------------+
|i7 : (f*g)(a) == f(g(a))                     |
|                                             |
|o7 = true                                    |
+---------------------------------------------+

Submodules of modules may be produced using multiplication and addition.
+-------------------------------+
|i8 : M = R^2; I = ideal(a+b,c);|
|                               |
|o9 : Ideal of R                |
+-------------------------------+
|i10 : N = I*M + a*R^2          |
|                               |
|o10 = image | a+b 0   c 0 a 0 ||
|            | 0   a+b 0 c 0 a ||
|                               |
|                              2|
|o10 : R-module, submodule of R |
+-------------------------------+
|i11 : isHomogeneous N          |
|                               |
|o11 = true                     |
+-------------------------------+

Intervals
---------

If one of the factors is an RRi, the output is an interval
containing all products of pairs in the factors.

+-----------------------------------+
|i12 : 2*interval(1,3)              |
|                                   |
|o12 = [2,6]                        |
|                                   |
|o12 : RRi (of precision 53)        |
+-----------------------------------+
|i13 : interval(1,3)*interval(-1,2) |
|                                   |
|o13 = [-3,6]                       |
|                                   |
|o13 : RRi (of precision 53)        |
+-----------------------------------+
|i14 : interval(-1,1)*interval(-1,1)|
|                                   |
|o14 = [-1,1]                       |
|                                   |
|o14 : RRi (of precision 53)        |
+-----------------------------------+

See also
========

  * times -- multiplication
  * product

Ways to use symbol *:
=====================

  * "CC * CC"
  * "CC * QQ"
  * "CC * RR"
  * "CC * ZZ"
  * "ChainComplexMap * ChainComplexMap"
  * "Constant * Constant"
  * "Constant * InexactNumber"
  * "Constant * Number"
  * "GradedModuleMap * GradedModuleMap"
  * "Ideal * Module"
  * "Ideal * Ring"
  * "Ideal * Vector"
  * "InexactNumber * Constant"
  * "List * Thing"
  * "Matrix * Number"
  * "Matrix * RingElement"
  * "Matrix * Vector"
  * "MonomialIdeal * MonomialIdeal"
  * "MonomialIdeal * Ring"
  * "MutableMatrix * MutableMatrix"
  * "Number * Constant"
  * "Number * Matrix"
  * "Number * Vector"
  * "ProjectiveHilbertPolynomial * ZZ"
  * "QQ * CC"
  * "QQ * QQ"
  * "QQ * RR"
  * "QQ * RRi"
  * "QQ * ZZ"
  * "Ring * Ideal"
  * "Ring * MonomialIdeal"
  * "Ring * RingElement"
  * "Ring * Vector"
  * "RingElement * ChainComplexMap"
  * "RingElement * GradedModuleMap"
  * "RingElement * Ideal"
  * "RingElement * Matrix"
  * "RingElement * Module"
  * "RingElement * MonomialIdeal"
  * "RingElement * MutableMatrix"
  * "RingElement * RingElement"
  * "RingElement * Vector"
  * "RingMap * RingMap"
  * "RR * CC"
  * "RR * QQ"
  * "RR * RR"
  * "RR * RRi"
  * "RR * ZZ"
  * "RRi * QQ"
  * "RRi * RR"
  * "RRi * RRi"
  * "RRi * ZZ"
  * "Thing * List"
  * "Vector * Number"
  * "Vector * RingElement"
  * "ZZ * CC"
  * "ZZ * ProjectiveHilbertPolynomial"
  * "ZZ * QQ"
  * "ZZ * RR"
  * "ZZ * RRi"
  * "ZZ * ZZ"
  * "QQ * BettiTally" -- see BettiTally, -- the class of all
    Betti tallies
  * "ZZ * BettiTally" -- see BettiTally, -- the class of all
    Betti tallies
  * Cone * Cone (Polyhedra) -- computes the direct product
    of two cones
  * Cone * Polyhedron (Polyhedra) -- computes the
    direct product of a cone and a polyhedron
  * "Constant * RingElement" -- see Constant,
  * "RingElement * Constant" -- see Constant,
  * Fan * Fan (Polyhedra) -- computes the direct product
  * Ideal * CoherentSheaf (missing documentation)
  * Ideal * Ideal -- product of ideals
  * Ideal * RingElement (missing documentation)
  * Ideal * ZZ (missing documentation)
  * InexactNumber * RingElement (missing documentation)
  * InfiniteNumber * CC (missing documentation)
  * InfiniteNumber * Matrix (missing documentation)
  * "Set * Set" -- see intersection(Set,Set),
    -- set intersection
  * Matrix * InfiniteNumber (missing documentation)
  * Matrix * Matrix -- matrix multiplication
  * Module * RingElement (missing documentation)
  * Module * ZZ (missing documentation)
  * MonoidElement * MonoidElement (missing documentation)
  * MonoidElement * ZZ (missing documentation)
  * MutableMatrix * RingElement (missing documentation)
  * MutableMatrix * RR (missing documentation)
  * MutableMatrix * ZZ (missing documentation)
  * Number * Tally (missing documentation)
  * Number * VirtualTally (missing documentation)
  * Polyhedron * Cone (Polyhedra) -- computes the
    direct product of a polyhedron and a cone
  * Polyhedron * Polyhedron (Polyhedra), --
    computes the direct product of two polyhedra
  * QQ * Polyhedron (Polyhedra) -- rescales a
    polyhedron by a given positive factor
  * "ZZ * Polyhedron" -- see QQ * Polyhedron (Polyhedra),
    -- rescales a polyhedron by a given positive factor
  * RingElement * InexactNumber (missing documentation)
  * RingElement * Tally (missing documentation)
  * RingElement * VirtualTally (missing documentation)
  * RR * MutableMatrix (missing documentation)
  * SheafMap * SheafMap (missing documentation)
  * ZZ * MonoidElement (missing documentation)
  * ZZ * MutableMatrix (missing documentation)

For the programmer
==================

The object *, is a keyword.

This operator may be used as a binary operator in an expression like x*y. The
user may install binary methods, for handling such
expressions with code such as

         X * Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

This operator may be used as a prefix unary operator in an expression like *y.
The user may install a method, for handling such
expressions with code such as

           * Y := (y) -> ...

where Y is the class of y.

/ -- a binary operator, usually used for division
*************************************************

Synopsis
========

  * Usage:
        x / y

Description
===========

This operator is currently used in several ways in Macaulay2.
  * division in a ring, yielding a fraction
  * division in unevaluated expressions
  * quotient rings, modules and sheaves
  * applying a function or ring map to every element of a list or set
+-------------------------+
|i1 : 2/3                 |
|                         |
|     2                   |
|o1 = -                   |
|     3                   |
|                         |
|o1 : QQ                  |
+-------------------------+
|i2 : 2./3                |
|                         |
|o2 = .6666666666666666   |
|                         |
|o2 : RR (of precision 53)|
+-------------------------+

Intervals
---------

If one of the inputs is an RRi, the output is an interval
containing all quotients of pairs in the inputs.

+---------------------------------+
|i3 : 2/interval(1,3)             |
|                                 |
|o3 = [.6666666666666666,2]       |
|                                 |
|o3 : RRi (of precision 53)       |
+---------------------------------+
|i4 : interval(-1,2)/interval(1,3)|
|                                 |
|o4 = [-1,2]                      |
|                                 |
|o4 : RRi (of precision 53)       |
+---------------------------------+
|i5 : interval(1,2)/interval(1,2) |
|                                 |
|o5 = [.5,2]                      |
|                                 |
|o5 : RRi (of precision 53)       |
+---------------------------------+

See also
========

  * // -- a binary operator, usually used for quotient

Ways to use symbol /:
=====================

  * "CC / CC"
  * "CC / QQ"
  * "CC / RR"
  * "CC / ZZ"
  * "QQ / CC"
  * "QQ / QQ"
  * "QQ / RR"
  * "QQ / RRi"
  * "QQ / ZZ"
  * "RR / CC"
  * "RR / QQ"
  * "RR / RR"
  * "RR / RRi"
  * "RR / ZZ"
  * "RRi / QQ"
  * "RRi / RR"
  * "RRi / RRi"
  * "RRi / ZZ"
  * "ZZ / CC"
  * "ZZ / QQ"
  * "ZZ / RR"
  * "ZZ / RRi"
  * "ZZ / ZZ"
  * CoherentSheaf / CoherentSheaf (Varieties)
    -- quotient of coherent sheaves
  * "CoherentSheaf / Ideal" -- see CoherentSheaf / CoherentSheaf (Varieties),
    -- quotient of coherent sheaves
  * "Constant / Constant" -- see Constant,
  * "Constant / InexactNumber" -- see Constant,
  * "Constant / Number" -- see Constant,
  * "Constant / RingElement" -- see Constant,
  * "InexactNumber / Constant" -- see Constant,
  * "Number / Constant" -- see Constant,
  * "RingElement / Constant" -- see Constant,
  * Ideal / Function -- apply a function to generators
    of an ideal
  * Ideal / Ideal -- quotient module
  * InexactNumber / RingElement (missing documentation)
  * InfiniteNumber / CC (missing documentation)
  * "List / Number" -- see List / RingElement, --
    vector division
  * List / RingElement -- vector division
  * Matrix / Number -- scalar division
  * "Matrix / RingElement" -- see Matrix / Number, --
    scalar division
  * "Vector / Number" -- see Matrix / Number, -- scalar
    division
  * "Vector / RingElement" -- see Matrix / Number, --
    scalar division
  * "Module / Ideal" -- see Module / Module, -- quotient
    module
  * "Module / List" -- see Module / Module, -- quotient
    module
  * Module / Module -- quotient module
  * "Module / RingElement" -- see Module / Module, --
    quotient module
  * "Module / Sequence" -- see Module / Module, --
    quotient module
  * "Module / Vector" -- see Module / Module, --
    quotient module
  * MonoidElement / MonoidElement (missing documentation)
  * Ring / Ideal -- make a quotient ring
  * "Ring / List" -- see Ring / Ideal, -- make a quotient
    ring
  * "Ring / Module" -- see Ring / Ideal, -- make a quotient
    ring
  * "Ring / RingElement" -- see Ring / Ideal, -- make a
    quotient ring
  * "Ring / Sequence" -- see Ring / Ideal, -- make a
    quotient ring
  * "Ring / ZZ" -- see Ring / Ideal, -- make a quotient
    ring
  * RingElement / InexactNumber (missing documentation)
  * RingElement / RingElement -- fraction
  * Set / Command (missing documentation)
  * Set / Function (missing documentation)
  * "List / Command" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "List / Function" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "String / Command" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "String / Function" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "VirtualTally / Command" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "VirtualTally / Function" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "VisibleList / Command" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * VisibleList / Function -- apply a function
    to elements of a list
  * "VisibleList / RingMap" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "VisibleList / SelfInitializingType" -- see VisibleList / Function,
    -- apply a function to elements of a list

For the programmer
==================

The object /, is a keyword.

This operator may be used as a binary operator in an expression like x/y. The
user may install binary methods, for handling such
expressions with code such as

         X / Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

// -- a binary operator, usually used for quotient
**************************************************

Synopsis
========

  * Usage:
        x // y

Description
===========

For ring elements in the integers, polynomial rings, and other rings, there are
two types of division:  exact division, whose result is often in a larger
field, such as the rationals or a function field, and division with remainder,
whose result is in the same ring.  In Macaulay2, '/' denotes the first kind of
division, while '//' denotes the latter kind. The following example shows the
difference between //, and /.
+---------+
|i1 : 4/2 |
|         |
|o1 = 2   |
|         |
|o1 : QQ  |
+---------+
|i2 : 4//2|
|         |
|o2 = 2   |
+---------+
+-------------------+
|i3 : R = QQ[x];    |
+-------------------+
|i4 : (x^2-3)//(x-1)|
|                   |
|o4 = x + 1         |
|                   |
|o4 : R             |
+-------------------+
|i5 : (x^2-3)%(x-1) |
|                   |
|o5 = -2            |
|                   |
|o5 : R             |
+-------------------+
|i6 : (x^2-3)/(x-1) |
|                   |
|      2            |
|     x  - 3        |
|o6 = ------        |
|      x - 1        |
|                   |
|o6 : frac R        |
+-------------------+

See also
========

  * / -- a binary operator, usually used for division
  * % -- a binary operator, usually used for remainder and reduction

Ways to use symbol //:
======================

  * "CC // CC"
  * "CC // QQ"
  * "CC // RR"
  * "CC // ZZ"
  * "InfiniteNumber // Number"
  * "InfiniteNumber // RR"
  * "Matrix // Number"
  * "Number // InfiniteNumber"
  * "Number // Matrix"
  * "Number // RingElement"
  * "QQ // QQ"
  * "QQ // ZZ"
  * "RingElement // Number"
  * "RR // QQ"
  * "RR // RR"
  * "RR // ZZ"
  * "ZZ // MonomialIdeal"
  * "ZZ // ZZ"
  * InexactNumber // RingElement (missing documentation)
  * InfiniteNumber // CC (missing documentation)
  * InfiniteNumber // InfiniteNumber (missing documentation)
  * List // Number (missing documentation)
  * List // RingElement (missing documentation)
  * "Matrix // GroebnerBasis" -- see Matrix // Matrix,
    -- factor a map through another
  * Matrix // Matrix -- factor a map through another
  * "Matrix // MonomialIdeal" -- see Matrix // Matrix,
    -- factor a map through another
  * "Matrix // RingElement" -- see Matrix // Matrix, --
    factor a map through another
  * "RingElement // GroebnerBasis" -- see Matrix // Matrix,
    -- factor a map through another
  * "RingElement // Matrix" -- see Matrix // Matrix, --
    factor a map through another
  * "RingElement // MonomialIdeal" -- see Matrix // Matrix,
    -- factor a map through another
  * "RingElement // RingElement" -- see Matrix // Matrix,
    -- factor a map through another
  * RingElement // InexactNumber (missing documentation)
  * "Thing // Command" -- see Thing // Function, --
    apply a function
  * Thing // Function -- apply a function
  * "Thing // SelfInitializingType" -- see Thing // Function,
    -- apply a function

For the programmer
==================

The object //, is a keyword.

This operator may be used as a binary operator in an expression like x//y. The
user may install binary methods, for handling such
expressions with code such as

         X // Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

% -- a binary operator, usually used for remainder and reduction
****************************************************************

Synopsis
========

  * Usage:
        x % y

Description
===========

The usual meaning for this operator is remainder, or normal form with respect
to a Gröbner basis.

For integers, the remainder is non-negative.
+-------------------------------+
|i1 : 1232132141242345 % 1000000|
|                               |
|o1 = 242345                    |
+-------------------------------+
|i2 : (-4)%5                    |
|                               |
|o2 = 1                         |
+-------------------------------+

In polynomial rings, the division algorithm is used.
+----------------------------------------+
|i3 : A = ZZ[a,b]                        |
|                                        |
|o3 = A                                  |
|                                        |
|o3 : PolynomialRing                     |
+----------------------------------------+
|i4 : (3*a^3-a*b-4) % (5*a-b)            |
|                                        |
|         3    2                         |
|o4 = - 2a  + a b - a*b - 4              |
|                                        |
|o4 : A                                  |
+----------------------------------------+
|i5 : pseudoRemainder(3*a^3-a*b-4, 5*a-b)|
|                                        |
|       3      2                         |
|o5 = 3b  - 25b  - 500                   |
|                                        |
|o5 : A                                  |
+----------------------------------------+
|i6 : B = QQ[a,b]                        |
|                                        |
|o6 = B                                  |
|                                        |
|o6 : PolynomialRing                     |
+----------------------------------------+
|i7 : (3*a^3-a*b-4) % (5*a-b)            |
|                                        |
|      3  3   1 2                        |
|o7 = ---b  - -b  - 4                    |
|     125     5                          |
|                                        |
|o7 : B                                  |
+----------------------------------------+
In more complicated situations, Gröbner bases are usually needed.  See
methods for normal forms and remainder.

See also
========

  * remainder -- matrix remainder
  * remainder' -- matrix quotient and remainder (opposite)
  * pseudoRemainder -- compute the pseudo-remainder
  * // -- a binary operator, usually used for quotient

Ways to use symbol %:
=====================

  * "CC % CC"
  * "CC % QQ"
  * "CC % RR"
  * "CC % ZZ"
  * "Number % GroebnerBasis"
  * "Number % Ideal"
  * "Number % RingElement"
  * "QQ % QQ"
  * "QQ % ZZ"
  * "RingElement % Number"
  * "RR % QQ"
  * "RR % RR"
  * "RR % ZZ"
  * "ZZ % MonomialIdeal"
  * "ZZ % ZZ"
  * InexactNumber % RingElement (missing documentation)
  * List % Number (missing documentation)
  * List % RingElement (missing documentation)
  * Matrix % GroebnerBasis -- calculate the
    normal form of ring elements and matrices using a (partially computed)
    Gröbner basis
  * "RingElement % GroebnerBasis" -- see Matrix % GroebnerBasis,
    -- calculate the normal form of ring elements and matrices
    using a (partially computed) Gröbner basis
  * "Matrix % Ideal" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "Matrix % Matrix" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "Matrix % Module" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "Matrix % MonomialIdeal" -- see methods for normal forms and remainder,
    -- normal form of ring
    elements and matrices
  * "Matrix % RingElement" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "RingElement % Ideal" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "RingElement % Matrix" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "RingElement % MonomialIdeal" -- see methods for normal forms and remainder,
    -- normal form of ring
    elements and matrices
  * "RingElement % RingElement" -- see methods for normal forms and remainder,
    -- normal form of ring
    elements and matrices
  * RingElement % InexactNumber (missing documentation)
  * Vector % Ideal (missing documentation)

For the programmer
==================

The object %, is a keyword.

This operator may be used as a binary operator in an expression like x%y. The
user may install binary methods, for handling such
expressions with code such as

         X % Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

^ -- a binary operator, usually used for powers
***********************************************

Synopsis
========

  * Usage:
        x ^ y

Description
===========

This operator is used for exponentiation, making free modules and sheaves, for
shifting complexes left or right, for projection maps involving direct sums,
and for making nets.

Ways to use symbol ^:
=====================

  * "Ring ^ BettiTally" -- see BettiTally, -- the class of
    all Betti tallies
  * ChainComplex ^ ZZ -- access member, cohomological
    degree
  * ChainComplexMap ^ ZZ -- iterated composition
  * "GradedModuleMap ^ ZZ" -- see ChainComplexMap ^ ZZ,
    -- iterated composition
  * CoherentSheaf ^ Array (missing documentation)
  * CoherentSheaf ^ List (missing documentation)
  * CoherentSheaf ^ ZZ (Varieties) -- direct sum
  * "SheafOfRings ^ ZZ" -- see CoherentSheaf ^ ZZ (Varieties),
    -- direct sum
  * "Constant ^ Constant" -- see Constant,
  * "Constant ^ InexactNumber" -- see Constant,
  * "Constant ^ Number" -- see Constant,
  * "InexactNumber ^ Constant" -- see Constant,
  * "Number ^ Constant" -- see Constant,
  * Constant ^ RingFamily (missing documentation)
  * Ideal ^ Array -- bracket power of an ideal
  * "MonomialIdeal ^ Array" -- see Ideal ^ Array, --
    bracket power of an ideal
  * Ideal ^ ZZ -- power of an ideal
  * "MonomialIdeal ^ ZZ" -- see Ideal ^ ZZ, -- power of an
    ideal
  * InfiniteNumber ^ InfiniteNumber (missing documentation)
  * "Number ^ Ring" -- see lift, -- lift to another ring
  * "Number ^ RingFamily" -- see lift, -- lift to another ring
  * List ^ List (missing documentation)
  * "ChainComplexMap ^ Array" -- see Matrix ^ Array, --
    component of map corresponding to summand of target
  * "GradedModuleMap ^ Array" -- see Matrix ^ Array, --
    component of map corresponding to summand of target
  * Matrix ^ Array -- component of map corresponding to
    summand of target
  * Matrix ^ List -- select rows
  * Matrix ^ ZZ -- power
  * "ChainComplex ^ Array" -- see Module ^ Array, --
    projection onto summand
  * Module ^ Array -- projection onto summand
  * Module ^ List -- projection onto summand
  * Module ^ ZZ -- direct sum
  * MonoidElement ^ ZZ (missing documentation)
  * MutableMatrix ^ List (missing documentation)
  * MutableMatrix ^ ZZ (missing documentation)
  * Net ^ ZZ -- raise a net or string
  * "String ^ ZZ" -- see Net ^ ZZ, -- raise a net or string
  * "RingMap ^ ZZ" -- see powers,
  * Ring ^ List -- make a free module
  * "RingFamily ^ List" -- see Ring ^ List, -- make a free
    module
  * Ring ^ ZZ -- make a free module
  * "RingFamily ^ ZZ" -- see Ring ^ ZZ, -- make a free module
  * RingElement ^ ZZ -- power
  * "ScriptedFunctor ^ Thing" -- see ScriptedFunctor, --
    the class of all scripted functors
  * SheafMap ^ ZZ (missing documentation)
  * SheafOfRings ^ List (Varieties) -- make a graded
    free coherent sheaf
  * String ^ Sequence -- vertically stacked copies of
    a string
  * Vector ^ List (missing documentation)

For the programmer
==================

The object ^, is a keyword.

This operator may be used as a binary operator in an expression like x^y. The
user may install binary methods, for handling such
expressions with code such as

         X ^ Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

& -- a binary operator
**********************

Ways to use symbol &:
=====================

  * ZZ & ZZ -- logical and

For the programmer
==================

The object &, is a keyword.

This operator may be used as a binary operator in an expression like x&y. The
user may install binary methods, for handling such
expressions with code such as

         X & Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

++ -- a binary operator, usually used for direct sum
****************************************************

Ways to use symbol ++:
======================

  * "BettiTally ++ BettiTally" -- see BettiTally, -- the
    class of all Betti tallies
  * ChainComplex ++ ChainComplex -- direct
    sum
  * "ChainComplexMap ++ ChainComplexMap" -- see ChainComplex ++ ChainComplex,
    -- direct sum
  * "GradedModule ++ GradedModule" -- see ChainComplex ++ ChainComplex,
    -- direct sum
  * CoherentSheaf ++ CoherentSheaf (Varieties)
    -- direct sum of coherent sheaves
  * "Option ++ Option" -- see directSum, -- direct sum of
    modules or maps
  * "GradedModuleMap ++ GradedModuleMap" -- see Matrix ++ Matrix,
    -- direct sum of maps
  * Matrix ++ Matrix -- direct sum of maps
  * "Matrix ++ RingElement" -- see Matrix ++ Matrix, --
    direct sum of maps
  * "RingElement ++ Matrix" -- see Matrix ++ Matrix, --
    direct sum of maps
  * "RingElement ++ RingElement" -- see Matrix ++ Matrix,
    -- direct sum of maps
  * "GradedModule ++ Module" -- see Module ++ Module,
    -- direct sum of modules
  * "Module ++ GradedModule" -- see Module ++ Module,
    -- direct sum of modules
  * Module ++ Module -- direct sum of modules
  * "OptionTable ++ List" -- see OptionTable ++ OptionTable,
    -- a binary operator, usually used for direct sum
  * OptionTable ++ OptionTable -- a binary
    operator, usually used for direct sum
  * SheafMap ++ SheafMap (missing documentation)

For the programmer
==================

The object ++, is a keyword.

This operator may be used as a binary operator in an expression like x++y. The
user may install binary methods, for handling such
expressions with code such as

         X ++ Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

** -- a binary operator, usually used for tensor product or Cartesian product
*****************************************************************************

See also
========

  * ^** -- a binary operator, usually used for tensor or
    Cartesian power

Ways to use symbol **:
======================

  * AffineVariety ** AffineVariety (missing documentation)
  * AffineVariety ** Ring (Varieties)
  * "BettiTally ** BettiTally" -- see BettiTally, -- the
    class of all Betti tallies
  * ChainComplex ** ChainComplex, --
    tensor product
  * "ChainComplex ** Module" -- see ChainComplex ** ChainComplex,
    -- tensor product
  * "Module ** ChainComplex" -- see ChainComplex ** ChainComplex,
    -- tensor product
  * ChainComplex ** ChainComplexMap,
    -- tensor product
  * "Module ** ChainComplexMap" -- see ChainComplex ** ChainComplexMap,
    -- tensor product
  * ChainComplex ** GradedModule, --
    tensor product
  * ChainComplex ** Ring -- a binary operator,
    usually used for tensor product or Cartesian product
  * ChainComplexMap ** ChainComplex,
    -- tensor product
  * "ChainComplexMap ** Module" -- see ChainComplexMap ** ChainComplex,
    -- tensor product
  * ChainComplexMap ** ChainComplexMap
    -- tensor product
  * CoherentSheaf ** CoherentSheaf (Varieties)
    -- tensor produce of coherent sheaves
  * CoherentSheaf ** SheafMap (missing documentation)
  * GradedModule ** ChainComplex, --
    tensor product
  * GradedModule ** GradedModule -- a
    binary operator, usually used for tensor product or Cartesian product
  * GradedModule ** Module -- a binary
    operator, usually used for tensor product or Cartesian product
  * "Module ** GradedModule" -- see GradedModule ** Module,
    -- a binary operator, usually used for tensor product or
    Cartesian product
  * List ** List -- Cartesian product of two lists
  * Matrix ** Ring -- tensor product
  * "Ring ** Matrix" -- see Matrix ** Ring, -- tensor
    product
  * Matrix ** RingElement -- a binary
    operator, usually used for tensor product or Cartesian product
  * "Ideal ** Ring" -- see Module ** Ring, -- tensor
    product
  * Module ** Ring -- tensor product
  * "Ring ** Ideal" -- see Module ** Ring, -- tensor
    product
  * "Ring ** Module" -- see Module ** Ring, -- tensor
    product
  * Option ** Option (missing documentation)
  * Set ** Set -- Cartesian product
  * SheafMap ** CoherentSheaf (missing documentation)
  * SheafMap ** SheafMap (missing documentation)
  * SheafMap ** SheafOfRings (missing documentation)
  * SheafOfRings ** SheafMap (missing documentation)
  * "Matrix ** Matrix" -- see tensor(Matrix,Matrix),
    -- tensor product
  * "Matrix ** Module" -- see tensor(Matrix,Module),
    -- tensor product
  * "Module ** Matrix" -- see tensor(Matrix,Module),
    -- tensor product
  * "Module ** Module" -- see tensor(Module,Module),
    -- tensor product of modules
  * "Monoid ** Monoid" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "Ring ** Ring" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "RingMap ** Matrix" -- see tensor(RingMap,Matrix),
    -- tensor product via a ring map
  * "RingMap ** Module" -- see tensor(RingMap,Matrix),
    -- tensor product via a ring map
  * Vector ** Vector -- tensor product
  * VirtualTally ** VirtualTally, --
    Cartesian product of tallies

For the programmer
==================

The object **, is a keyword.

This operator may be used as a binary operator in an expression like x**y. The
user may install binary methods, for handling such
expressions with code such as

         X ** Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

^** -- a binary operator, usually used for tensor or Cartesian power
********************************************************************

Ways to use symbol ^**:
=======================

  * CoherentSheaf ^** ZZ (Varieties) -- tensor
    power
  * Module ^** ZZ -- tensor power
  * "Monoid ^** ZZ" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "Ring ^** ZZ" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * VirtualTally ^** ZZ -- Cartesian power of
    sets and tallies

For the programmer
==================

The object ^**, is a keyword.

This operator may be used as a binary operator in an expression like x^**y. The
user may install binary methods, for handling such
expressions with code such as

         X ^** Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

~ -- a unary postfix operator
*****************************

Ways to use symbol ~:
=====================

  * "Module ~" -- see sheaf(Module) (Varieties), --
    make a coherent sheaf
  * "Ring ~" -- see sheaf(Ring) (Varieties), -- make a
    coherent sheaf of rings
  * ZZ ~ -- logical not

For the programmer
==================

The object ~, is a keyword.

This operator may be used as a postfix unary operator in an expression like x~.
The user may install a method, for handling such expressions with
code such as

         X ~   := (x) -> ...

where X is the class of x.

(*) -- a unary postfix operator, used for indicating a graded object
********************************************************************

Ways to use symbol (*):
=======================

  * CoherentSheaf (*) (Varieties) -- sum of
    twists
  * "SheafOfRings (*)" -- see CoherentSheaf (*) (Varieties),
    -- sum of twists

For the programmer
==================

The object (*), is a keyword.

This operator may be used as a postfix unary operator in an expression like
x(*). The user may install a method, for handling such expressions
with code such as

         X (*)   := (x) -> ...

where X is the class of x.

: -- a binary operator, uses include repetition; ideal quotients
****************************************************************

Ways to use symbol ::
=====================

  * MonoidElement : MonoidElement (missing documentation)
  * "Ideal : Ideal" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "Ideal : RingElement" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "Module : Ideal" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "Module : Module" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "Module : RingElement" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "MonomialIdeal : RingElement" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * ZZ _colon_ Thing -- repeat an item

For the programmer
==================

The object _colon_, is a keyword.

This operator may be used as a binary operator in an expression like x:y. The
user may install binary methods, for handling such
expressions with code such as

         X : Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

.. -- a binary operator, used for sequences of consecutive items
****************************************************************

Description
===========

The most confusing thing about this operator, in all its guises, is that it is
not a syntactic construction, and so the resulting sequences do not splice
themselves into enclosing lists, as in each of the following examples.

+----------------------------+
|i1 : {10..10}               |
|                            |
|o1 = {1 : (10)}             |
|                            |
|o1 : List                   |
+----------------------------+
|i2 : {10..8}                |
|                            |
|o2 = {()}                   |
|                            |
|o2 : List                   |
+----------------------------+
|i3 : {3..5,8..10}           |
|                            |
|o3 = {(3, 4, 5), (8, 9, 10)}|
|                            |
|o3 : List                   |
+----------------------------+

  Use splice, to fix that.

+------------------------+
|i4 : splice {3..5,8..10}|
|                        |
|o4 = {3, 4, 5, 8, 9, 10}|
|                        |
|o4 : List               |
+------------------------+

If a type of list, instead of a sequence, is desired, use toList,
or the operator new.

+----------------------------+
|i5 : 0..5                   |
|                            |
|o5 = (0, 1, 2, 3, 4, 5)     |
|                            |
|o5 : Sequence               |
+----------------------------+
|i6 : toList (0..5)          |
|                            |
|o6 = {0, 1, 2, 3, 4, 5}     |
|                            |
|o6 : List                   |
+----------------------------+
|i7 : new Array from 0..5    |
|                            |
|o7 = [0, 1, 2, 3, 4, 5]     |
|                            |
|o7 : Array                  |
+----------------------------+
|i8 : new Sum from 0..5      |
|                            |
|o8 = 0 + 1 + 2 + 3 + 4 + 5  |
|                            |
|o8 : Expression of class Sum|
+----------------------------+

The operator can be used with sequences or lists, whose elements are of various
types, to produce rectangular intervals.

+---------------------------------------------------------------------+
|i9 : (0,0)..(1,3)                                                    |
|                                                                     |
|o9 = ((0, 0), (0, 1), (0, 2), (0, 3), (1, 0), (1, 1), (1, 2), (1, 3))|
|                                                                     |
|o9 : Sequence                                                        |
+---------------------------------------------------------------------+
|i10 : p_(0,a) .. p_(1,c)                                             |
|                                                                     |
|o10 = (p   , p   , p   , p   , p   , p   )                           |
|        0,a   0,b   0,c   1,a   1,b   1,c                            |
|                                                                     |
|o10 : Sequence                                                       |
+---------------------------------------------------------------------+
|i11 : p_(1,1) .. q_(2,2)                                             |
|                                                                     |
|o11 = (p   , p   , p   , p   , q   , q   , q   , q   )               |
|        1,1   1,2   2,1   2,2   1,1   1,2   2,1   2,2                |
|                                                                     |
|o11 : Sequence                                                       |
+---------------------------------------------------------------------+

Use ..<, instead to get a sequence that stops short of the
endpoint.

See also
========

  * polynomial rings
  * subscripted variables
  * ..< -- a binary operator, used for sequences of consecutive
    items, not including the endpoint

Ways to use symbol ..:
======================

  * IndexedVariable .. IndexedVariable
    -- sequences of consecutive indexed variables
  * IndexedVariableTable .. IndexedVariableTable (missing documentation)
  * IndexedVariableTable .. Thing (missing documentation)
  * List .. List -- rectangular sequences of
    consecutive lists and sequences
  * "Sequence .. Sequence" -- see List .. List, --
    rectangular sequences of consecutive lists and sequences
  * MonoidElement .. MonoidElement (missing documentation)
  * MonoidElement .. Thing (missing documentation)
  * RingElement .. RingElement -- a
    sequence of consecutive generators of a polynomial ring
  * RingElement .. Thing (missing documentation)
  * String .. String -- a sequence of consecutive
    strings
  * Symbol .. Symbol -- sequences of consecutive
    symbols
  * Thing .. IndexedVariableTable (missing documentation)
  * Thing .. MonoidElement (missing documentation)
  * Thing .. RingElement (missing documentation)
  * ZZ .. ZZ -- sequences of consecutive integers

For the programmer
==================

The object .., is a keyword.

This operator may be used as a binary operator in an expression like x..y. The
user may install binary methods, for handling such
expressions with code such as

         X .. Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

..< -- a binary operator, used for sequences of consecutive items, not including the endpoint
*********************************************************************************************

Description
===========

The most confusing thing about this operator, in all its guises, is that it is
not a syntactic construction, and so the resulting sequences do not splice
themselves into enclosing lists, as in each of the following examples.

+---------------------+
|i1 : {10..<11}       |
|                     |
|o1 = {1 : (10)}      |
|                     |
|o1 : List            |
+---------------------+
|i2 : {10..<8}        |
|                     |
|o2 = {()}            |
|                     |
|o2 : List            |
+---------------------+
|i3 : {3..<5,8..<10}  |
|                     |
|o3 = {(3, 4), (8, 9)}|
|                     |
|o3 : List            |
+---------------------+

  Use splice, to fix that.

+--------------------------+
|i4 : splice {3..<5,8..<10}|
|                          |
|o4 = {3, 4, 8, 9}         |
|                          |
|o4 : List                 |
+--------------------------+

If a type of list, instead of a sequence, is desired, use toList,
or the operator new.

+----------------------------+
|i5 : 0..<5                  |
|                            |
|o5 = (0, 1, 2, 3, 4)        |
|                            |
|o5 : Sequence               |
+----------------------------+
|i6 : toList (0..<5)         |
|                            |
|o6 = {0, 1, 2, 3, 4}        |
|                            |
|o6 : List                   |
+----------------------------+
|i7 : new Array from 0..<5   |
|                            |
|o7 = [0, 1, 2, 3, 4]        |
|                            |
|o7 : Array                  |
+----------------------------+
|i8 : new Sum from 0..<5     |
|                            |
|o8 = 0 + 1 + 2 + 3 + 4      |
|                            |
|o8 : Expression of class Sum|
+----------------------------+

The operator can be used with sequences or lists, whose elements are of various
types, to produce rectangular intervals.

+------------------------------------------------------+
|i9 : (0,0)..<(2,3)                                    |
|                                                      |
|o9 = ((0, 0), (0, 1), (0, 2), (1, 0), (1, 1), (1, 2)) |
|                                                      |
|o9 : Sequence                                         |
+------------------------------------------------------+
|i10 : p_(0,a) ..< r_(2,c)                             |
|                                                      |
|o10 = (p   , p   , p   , p   , q   , q   , q   , q   )|
|        0,a   0,b   1,a   1,b   0,a   0,b   1,a   1,b |
|                                                      |
|o10 : Sequence                                        |
+------------------------------------------------------+

Use .., instead to get a sequence that does not stop short of the
endpoint.

See also
========

  * polynomial rings
  * subscripted variables
  * .. -- a binary operator, used for sequences of consecutive
    items

Ways to use symbol ..<:
=======================

  * IndexedVariable ..< IndexedVariable
    -- sequences of consecutive indexed variables
  * IndexedVariableTable ..< IndexedVariableTable (missing documentation)
  * IndexedVariableTable ..< Thing (missing documentation)
  * List ..< List -- rectangular sequences of
    consecutive lists and sequences
  * "Sequence ..< Sequence" -- see List ..< List, --
    rectangular sequences of consecutive lists and sequences
  * MonoidElement ..< MonoidElement (missing documentation)
  * MonoidElement ..< Thing (missing documentation)
  * RingElement ..< RingElement -- a
    sequence of consecutive generators of a polynomial ring
  * RingElement ..< Thing (missing documentation)
  * String ..< String -- a sequence of
    consecutive strings, not including the endpoint
  * Symbol ..< Symbol -- sequences of consecutive
    symbols
  * Thing ..< IndexedVariableTable (missing documentation)
  * Thing ..< MonoidElement (missing documentation)
  * Thing ..< RingElement (missing documentation)
  * ZZ ..< ZZ -- sequences of consecutive integers

For the programmer
==================

The object ..<, is a keyword.

This operator may be used as a binary operator in an expression like x..<y. The
user may install binary methods, for handling such
expressions with code such as

         X ..< Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

<< -- a binary operator (file output, ...)
******************************************

Ways to use symbol <<:
======================

  * "<< Thing" -- see File << Thing, -- print to a file
  * "File << Manipulator" -- see File << Thing, -- print
    to a file
  * "File << Net" -- see File << Thing, -- print to a file
  * "File << String" -- see File << Thing, -- print to a
    file
  * "File << Symbol" -- see File << Thing, -- print to a
    file
  * File << Thing -- print to a file
  * "Nothing << Manipulator" -- see File << Thing, --
    print to a file
  * "Nothing << Thing" -- see File << Thing, -- print to a
    file
  * "String << Thing" -- see File << Thing, -- print to a
    file
  * "CC << ZZ" -- see left shift,
  * "RR << ZZ" -- see left shift,
  * "RRi << ZZ" -- see left shift,
  * "ZZ << ZZ" -- see left shift,
  * List << List -- component-wise comparison of lists
  * "NetFile << Manipulator" -- see NetFile, -- the class of all
    net files
  * "NetFile << Net" -- see NetFile, -- the class of all net
    files
  * "NetFile << String" -- see NetFile, -- the class of all net
    files
  * Program << Thing -- run program with input
    redirection

For the programmer
==================

The object <<, is a keyword.

This operator may be used as a binary operator in an expression like x<<y. The
user may install binary methods, for handling such
expressions with code such as

         X << Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

This operator may be used as a prefix unary operator in an expression like <<y.
The user may install a method, for handling such
expressions with code such as

           << Y := (y) -> ...

where Y is the class of y.

>> -- a binary operator, uses include bit shifting, or attaching optional inputs to functions
*********************************************************************************************

Ways to use symbol >>:
======================

  * "Boolean >> Function" -- see OptionTable >> Function,
    -- attaching options to a function
  * "List >> Function" -- see OptionTable >> Function,
    -- attaching options to a function
  * OptionTable >> Function -- attaching
    options to a function
  * "CC >> ZZ" -- see right shift,
  * "RR >> ZZ" -- see right shift,
  * "RRi >> ZZ" -- see right shift,
  * "ZZ >> ZZ" -- see right shift,

For the programmer
==================

The object >>, is a keyword.

This operator may be used as a binary operator in an expression like x>>y. The
user may install binary methods, for handling such
expressions with code such as

         X >> Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

| -- a binary operator, often used for horizontal concatenation
***************************************************************

See also
========

  * || -- a binary operator, often used for vertical concatenation

Ways to use symbol |:
=====================

  * GradedModuleMap | GradedModuleMap,
    -- a binary operator, often used for horizontal concatenation
  * Iterator | Iterator (missing documentation)
  * "Array | Array" -- see List | List, -- join lists,
    sequences or arrays
  * List | List -- join lists, sequences or arrays
  * "Sequence | Sequence" -- see List | List, -- join lists,
    sequences or arrays
  * Matrix | Matrix -- join matrices horizontally
  * "Matrix | Number" -- see Matrix | Matrix, -- join
    matrices horizontally
  * "Matrix | RingElement" -- see Matrix | Matrix, --
    join matrices horizontally
  * "Number | Matrix" -- see Matrix | Matrix, -- join
    matrices horizontally
  * "RingElement | Matrix" -- see Matrix | Matrix, --
    join matrices horizontally
  * "RingElement | RingElement" -- see Matrix | Matrix,
    -- join matrices horizontally
  * Net | Net -- join strings or nets
  * "String | String" -- see Net | Net, -- join strings or
    nets
  * "String | ZZ" -- see Net | Net, -- join strings or nets
  * "ZZ | String" -- see Net | Net, -- join strings or nets
  * ZZ | ZZ -- logical or

For the programmer
==================

The object |, is a keyword.

This operator may be used as a binary operator in an expression like x|y. The
user may install binary methods, for handling such
expressions with code such as

         X | Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

|| -- a binary operator, often used for vertical concatenation
**************************************************************

Ways to use symbol ||:
======================

  * GradedModuleMap || GradedModuleMap
    -- a binary operator, often used for vertical
    concatenation
  * Matrix || Matrix -- join matrices vertically
  * "Matrix || Number" -- see Matrix || Matrix, -- join
    matrices vertically
  * "Matrix || RingElement" -- see Matrix || Matrix, --
    join matrices vertically
  * "Number || Matrix" -- see Matrix || Matrix, -- join
    matrices vertically
  * "RingElement || Matrix" -- see Matrix || Matrix, --
    join matrices vertically
  * "RingElement || RingElement" -- see Matrix || Matrix,
    -- join matrices vertically
  * Net || Net -- join nets or strings vertically
  * Vector || Vector -- join Vectors

For the programmer
==================

The object ||, is a keyword.

This operator may be used as a binary operator in an expression like x||y. The
user may install binary methods, for handling such
expressions with code such as

         X || Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

@ -- a binary operator
**********************

Description
===========

This operator is right associative.

For the programmer
==================

The object @, is a keyword.

This operator may be used as a binary operator in an expression like x@y. The
user may install binary methods, for handling such
expressions with code such as

         X @ Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

^^ -- logical exclusive-or
**************************

Synopsis
========

  * Usage:
        m ^^ n
  * Inputs:
      * m
      * n
  * Outputs:
      * an integer, the bitwise logical exclusive-or of the integers
        m and n

Description
===========

+-------------+
|i1 : 10 ^^ 12|
|             |
|o1 = 6       |
+-------------+

See also
========

  * ZZ | ZZ -- logical or
  * ZZ & ZZ -- logical and
  * ZZ ~ -- logical not

Ways to use symbol ^^:
======================

  * "ZZ ^^ ZZ"

For the programmer
==================

The object ^^, is a keyword.

This operator may be used as a binary operator in an expression like x^^y. The
user may install binary methods, for handling such
expressions with code such as

         X ^^ Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

?? -- null coalescing operator
******************************

Synopsis
========

  * Usage:
        x ?? y
  * Inputs:
      * x, a thing,
      * y, a thing,
  * Outputs:
      * a thing, either x or y;

Description
===========

If x is null or a non-interrupting error, then y is returned.  When it is an
error, the error message is suppressed like it is with try.

+--------------+
|i1 : null ?? 2|
|              |
|o1 = 2        |
+--------------+
|i2 : 1/0 ?? 3 |
|              |
|o2 = 3        |
+--------------+

In all other cases, x is returned.

+-----------+
|i3 : 5 ?? 6|
|           |
|o3 = 5     |
+-----------+

Note that y is lazily evaluated, that is, it is only evaluated if it is
necessary.

The null coalescing operator can be combined with augmented assignment,
as a shortcut for if x === null then x = y and if not
x#?i then x#i = y.

+------------------------+
|i4 : x = null           |
+------------------------+
|i5 : x ??= 2            |
|                        |
|o5 = 2                  |
+------------------------+
|i6 : x ??= 3            |
|                        |
|o6 = 2                  |
+------------------------+
|i7 : x = new MutableList|
|                        |
|o7 = MutableList{}      |
|                        |
|o7 : MutableList        |
+------------------------+
|i8 : x#0 ??= 4          |
|                        |
|o8 = 4                  |
+------------------------+
|i9 : peek x             |
|                        |
|o9 = MutableList{4}     |
+------------------------+
|i10 : x#0 ??= 5         |
|                        |
|o10 = 4                 |
+------------------------+
|i11 : peek x            |
|                        |
|o11 = MutableList{4}    |
+------------------------+

It is also possible to install a method for a particular type to determine
whether an instance x of that type should be considered "null" or not.  Such a
method should return either x or null,

+------------------------------------+
|i12 : X = new Type of BasicList;    |
+------------------------------------+
|i13 : ?? X := x -> if #x > 0 then x;|
+------------------------------------+
|i14 : x = new X from {};            |
+------------------------------------+
|i15 : y = new X from {5};           |
+------------------------------------+
|i16 : x ?? y                        |
|                                    |
|o16 = X{5}                          |
|                                    |
|o16 : X                             |
+------------------------------------+
|i17 : y ?? x                        |
|                                    |
|o17 = X{5}                          |
|                                    |
|o17 : X                             |
+------------------------------------+

It is also possible to use ?? as a prefix operator to call this method.

+-------------+
|i18 : ?? 2   |
|             |
|o18 = 2      |
+-------------+
|i19 : ?? x   |
+-------------+
|i20 : ??(1/0)|
+-------------+

Caveat
======

Although this operator is "flexible" in the sense that it possible to install a
method to determine the behavior on the left-hand side, it is not truly
flexible like most other binary operators.  In particular, since it is only
lazily evaluated, it is not possible to install a method that uses the value of
the right-hand side.

For the programmer
==================

The object ??, is a keyword.

This operator may be used as a binary operator in an expression like x??y.

This operator may be used as a prefix unary operator in an expression like ??y.
The user may install a method, for handling such
expressions with code such as

           ?? Y := (y) -> ...

where Y is the class of y.

|- -- a binary operator
***********************

For the programmer
==================

The object |-, is a keyword.

This operator may be used as a binary operator in an expression like x|-y. The
user may install binary methods, for handling such
expressions with code such as

         X |- Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

This operator may be used as a prefix unary operator in an expression like |-y.
The user may install a method, for handling such
expressions with code such as

           |- Y := (y) -> ...

where Y is the class of y.

<==> -- a binary operator
*************************

For the programmer
==================

The object <==>, is a keyword.

This operator may be used as a binary operator in an expression like x<==>y.
The user may install binary methods, for handling such
expressions with code such as

         X <==> Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

===> -- a binary operator
*************************

For the programmer
==================

The object ===>, is a keyword.

This operator may be used as a binary operator in an expression like x===>y.
The user may install binary methods, for handling such
expressions with code such as

         X ===> Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

==> -- a binary operator
************************

For the programmer
==================

The object ==>, is a keyword.

This operator may be used as a binary operator in an expression like x==>y. The
user may install binary methods, for handling such
expressions with code such as

         X ==> Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

<=== -- a unary and binary operator
***********************************

For the programmer
==================

The object <===, is a keyword.

This operator may be used as a binary operator in an expression like x<===y.
The user may install binary methods, for handling such
expressions with code such as

         X <=== Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

This operator may be used as a prefix unary operator in an expression like
<===y. The user may install a method, for handling
such expressions with code such as

           <=== Y := (y) -> ...

where Y is the class of y.

<== -- a unary and binary operator
**********************************

For the programmer
==================

The object <==, is a keyword.

This operator may be used as a binary operator in an expression like x<==y. The
user may install binary methods, for handling such
expressions with code such as

         X <== Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

This operator may be used as a prefix unary operator in an expression like
<==y. The user may install a method, for handling
such expressions with code such as

           <== Y := (y) -> ...

where Y is the class of y.

=> -- produce an Option
***********************

Description
===========

x => y a binary operator that produces a type of list called an Option.

Ways to use symbol =>:
======================

  * "Thing => Thing"

For the programmer
==================

The object =>, is a keyword.

, -- the comma, used for separating entries in a list or sequence
*****************************************************************

For the programmer
==================

The object ,, is a keyword.

; -- expression separator
*************************

Synopsis
========

  * Usage:
        (e;f;...;g;h)

Description
===========

The semicolon can be used for evaluating a sequence of expressions.  The value
of the sequence is the value of its last expression, unless it is omitted, in
which case the value is null.

+-------------+
|i1 : (3;4;5) |
|             |
|o1 = 5       |
+-------------+
|i2 : (3;4;5;)|
+-------------+

Putting expressions on separate lines is not a substitute for the semicolons.

For the programmer
==================

The object ;, is a keyword.

%= -- augmented assignment for %
********************************

Synopsis
========

  * Usage:
        x %=y

Description
===========

In most cases, x %= y is equivalent to x = x % y, unless a method is installed
for the class of x.

See also
========

  * % -- a binary operator, usually used for remainder and reduction
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object %=, is a keyword.

This operator may be used as a binary operator in an expression like x%=y. The
user may install a method, for handling such expressions with code
such as

         X %= (x,y) -> ...

where X is the class of x.

&= -- augmented assignment for &
********************************

Synopsis
========

  * Usage:
        x &=y

Description
===========

In most cases, x &= y is equivalent to x = x & y, unless a method is installed
for the class of x.

See also
========

  * & -- a binary operator
  * augmented assignment
  * installing augmented assignment methods

Ways to use symbol &=:
======================

  * AtomicInt &= ZZ -- atomic fetch and bitwise and

For the programmer
==================

The object &=, is a keyword.

This operator may be used as a binary operator in an expression like x&=y. The
user may install a method, for handling such expressions with code
such as

         X &= (x,y) -> ...

where X is the class of x.

**= -- augmented assignment for **
**********************************

Synopsis
========

  * Usage:
        x **=y

Description
===========

In most cases, x **= y is equivalent to x = x ** y, unless a method is
installed for the class of x.

See also
========

  * ** -- a binary operator, usually used for tensor product or
    Cartesian product
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object **=, is a keyword.

This operator may be used as a binary operator in an expression like x**=y. The
user may install a method, for handling such expressions with code
such as

         X **= (x,y) -> ...

where X is the class of x.

*= -- augmented assignment for *
********************************

Synopsis
========

  * Usage:
        x *=y

Description
===========

In most cases, x *= y is equivalent to x = x * y, unless a method is installed
for the class of x.

See also
========

  * * -- a binary operator, usually used for multiplication
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object *=, is a keyword.

This operator may be used as a binary operator in an expression like x*=y. The
user may install a method, for handling such expressions with code
such as

         X *= (x,y) -> ...

where X is the class of x.

++= -- augmented assignment for ++
**********************************

Synopsis
========

  * Usage:
        x ++=y

Description
===========

In most cases, x ++= y is equivalent to x = x ++ y, unless a method is
installed for the class of x.

See also
========

  * ++ -- a binary operator, usually used for direct sum
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object ++=, is a keyword.

This operator may be used as a binary operator in an expression like x++=y. The
user may install a method, for handling such expressions with code
such as

         X ++= (x,y) -> ...

where X is the class of x.

+= -- augmented assignment for +
********************************

Synopsis
========

  * Usage:
        x +=y

Description
===========

In most cases, x += y is equivalent to x = x + y, unless a method is installed
for the class of x.

See also
========

  * + -- a unary or binary operator, usually used for addition
  * augmented assignment
  * installing augmented assignment methods

Ways to use symbol +=:
======================

  * AtomicInt += ZZ -- atomic fetch and add

For the programmer
==================

The object +=, is a keyword.

This operator may be used as a binary operator in an expression like x+=y. The
user may install a method, for handling such expressions with code
such as

         X += (x,y) -> ...

where X is the class of x.

-= -- augmented assignment for -
********************************

Synopsis
========

  * Usage:
        x -=y

Description
===========

In most cases, x -= y is equivalent to x = x - y, unless a method is installed
for the class of x.

See also
========

  * - -- a unary or binary operator, usually used for negation or
    subtraction
  * augmented assignment
  * installing augmented assignment methods

Ways to use symbol -=:
======================

  * AtomicInt -= ZZ -- atomic fetch and subtract

For the programmer
==================

The object -=, is a keyword.

This operator may be used as a binary operator in an expression like x-=y. The
user may install a method, for handling such expressions with code
such as

         X -= (x,y) -> ...

where X is the class of x.

..<= -- augmented assignment for ..<
************************************

Synopsis
========

  * Usage:
        x ..<=y

Description
===========

In most cases, x ..<= y is equivalent to x = x ..< y, unless a method is
installed for the class of x.

See also
========

  * ..< -- a binary operator, used for sequences of consecutive
    items, not including the endpoint
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object ..<=, is a keyword.

This operator may be used as a binary operator in an expression like x..<=y.
The user may install a method, for handling such expressions with
code such as

         X ..<= (x,y) -> ...

where X is the class of x.

..= -- augmented assignment for ..
**********************************

Synopsis
========

  * Usage:
        x ..=y

Description
===========

In most cases, x ..= y is equivalent to x = x .. y, unless a method is
installed for the class of x.

See also
========

  * .. -- a binary operator, used for sequences of consecutive
    items
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object ..=, is a keyword.

This operator may be used as a binary operator in an expression like x..=y. The
user may install a method, for handling such expressions with code
such as

         X ..= (x,y) -> ...

where X is the class of x.

//= -- augmented assignment for //
**********************************

Synopsis
========

  * Usage:
        x //=y

Description
===========

In most cases, x //= y is equivalent to x = x // y, unless a method is
installed for the class of x.

See also
========

  * // -- a binary operator, usually used for quotient
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object //=, is a keyword.

This operator may be used as a binary operator in an expression like x//=y. The
user may install a method, for handling such expressions with code
such as

         X //= (x,y) -> ...

where X is the class of x.

/= -- augmented assignment for /
********************************

Synopsis
========

  * Usage:
        x /=y

Description
===========

In most cases, x /= y is equivalent to x = x / y, unless a method is installed
for the class of x.

See also
========

  * / -- a binary operator, usually used for division
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object /=, is a keyword.

This operator may be used as a binary operator in an expression like x/=y. The
user may install a method, for handling such expressions with code
such as

         X /= (x,y) -> ...

where X is the class of x.

<<= -- augmented assignment for <<
**********************************

Synopsis
========

  * Usage:
        x <<=y

Description
===========

In most cases, x <<= y is equivalent to x = x << y, unless a method is
installed for the class of x.

See also
========

  * << -- a binary operator (file output, ...)
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object <<=, is a keyword.

This operator may be used as a binary operator in an expression like x<<=y. The
user may install a method, for handling such expressions with code
such as

         X <<= (x,y) -> ...

where X is the class of x.

<==>= -- augmented assignment for <==>
**************************************

Synopsis
========

  * Usage:
        x <==>=y

Description
===========

In most cases, x <==>= y is equivalent to x = x <==> y, unless a method is
installed for the class of x.

See also
========

  * <==> -- a binary operator
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object <==>=, is a keyword.

This operator may be used as a binary operator in an expression like x<==>=y.
The user may install a method, for handling such expressions with
code such as

         X <==>= (x,y) -> ...

where X is the class of x.

===>= -- augmented assignment for ===>
**************************************

Synopsis
========

  * Usage:
        x ===>=y

Description
===========

In most cases, x ===>= y is equivalent to x = x ===> y, unless a method is
installed for the class of x.

See also
========

  * ===> -- a binary operator
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object ===>=, is a keyword.

This operator may be used as a binary operator in an expression like x===>=y.
The user may install a method, for handling such expressions with
code such as

         X ===>= (x,y) -> ...

where X is the class of x.

==>= -- augmented assignment for ==>
************************************

Synopsis
========

  * Usage:
        x ==>=y

Description
===========

In most cases, x ==>= y is equivalent to x = x ==> y, unless a method is
installed for the class of x.

See also
========

  * ==> -- a binary operator
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object ==>=, is a keyword.

This operator may be used as a binary operator in an expression like x==>=y.
The user may install a method, for handling such expressions with
code such as

         X ==>= (x,y) -> ...

where X is the class of x.

>>= -- augmented assignment for >>
**********************************

Synopsis
========

  * Usage:
        x >>=y

Description
===========

In most cases, x >>= y is equivalent to x = x >> y, unless a method is
installed for the class of x.

See also
========

  * >> -- a binary operator, uses include bit shifting, or attaching
    optional inputs to functions
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object >>=, is a keyword.

This operator may be used as a binary operator in an expression like x>>=y. The
user may install a method, for handling such expressions with code
such as

         X >>= (x,y) -> ...

where X is the class of x.

??= -- augmented assignment for ??
**********************************

Synopsis
========

  * Usage:
        x ??=y

Description
===========

In most cases, x ??= y is equivalent to x = x ?? y, unless a method is
installed for the class of x.

See also
========

  * ?? -- null coalescing operator
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object ??=, is a keyword.

This operator may be used as a binary operator in an expression like x??=y. The
user may install a method, for handling such expressions with code
such as

         X ??= (x,y) -> ...

where X is the class of x.

@= -- augmented assignment for @
********************************

Synopsis
========

  * Usage:
        x @=y

Description
===========

In most cases, x @= y is equivalent to x = x @ y, unless a method is installed
for the class of x.

See also
========

  * @ -- a binary operator
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object @=, is a keyword.

This operator may be used as a binary operator in an expression like x@=y. The
user may install a method, for handling such expressions with code
such as

         X @= (x,y) -> ...

where X is the class of x.

@@= -- augmented assignment for @@
**********************************

Synopsis
========

  * Usage:
        x @@=y

Description
===========

In most cases, x @@= y is equivalent to x = x @@ y, unless a method is
installed for the class of x.

See also
========

  * @@ -- a binary operator
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object @@=, is a keyword.

This operator may be used as a binary operator in an expression like x@@=y. The
user may install a method, for handling such expressions with code
such as

         X @@= (x,y) -> ...

where X is the class of x.

\= -- augmented assignment for \
********************************

Synopsis
========

  * Usage:
        x \=y

Description
===========

In most cases, x \= y is equivalent to x = x \ y, unless a method is installed
for the class of x.

See also
========

  * \ -- a binary operator
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object \=, is a keyword.

This operator may be used as a binary operator in an expression like x\=y. The
user may install a method, for handling such expressions with code
such as

         X \= (x,y) -> ...

where X is the class of x.

\\= -- augmented assignment for \\
**********************************

Synopsis
========

  * Usage:
        x \\=y

Description
===========

In most cases, x \\= y is equivalent to x = x \\ y, unless a method is
installed for the class of x.

See also
========

  * \\ -- a binary operator
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object \\=, is a keyword.

This operator may be used as a binary operator in an expression like x\\=y. The
user may install a method, for handling such expressions with code
such as

         X \\= (x,y) -> ...

where X is the class of x.

^**= -- augmented assignment for ^**
************************************

Synopsis
========

  * Usage:
        x ^**=y

Description
===========

In most cases, x ^**= y is equivalent to x = x ^** y, unless a method is
installed for the class of x.

See also
========

  * ^** -- a binary operator, usually used for tensor or
    Cartesian power
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object ^**=, is a keyword.

This operator may be used as a binary operator in an expression like x^**=y.
The user may install a method, for handling such expressions with
code such as

         X ^**= (x,y) -> ...

where X is the class of x.

^= -- augmented assignment for ^
********************************

Synopsis
========

  * Usage:
        x ^=y

Description
===========

In most cases, x ^= y is equivalent to x = x ^ y, unless a method is installed
for the class of x.

See also
========

  * ^ -- a binary operator, usually used for powers
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object ^=, is a keyword.

This operator may be used as a binary operator in an expression like x^=y. The
user may install a method, for handling such expressions with code
such as

         X ^= (x,y) -> ...

where X is the class of x.

^^= -- augmented assignment for ^^
**********************************

Synopsis
========

  * Usage:
        x ^^=y

Description
===========

In most cases, x ^^= y is equivalent to x = x ^^ y, unless a method is
installed for the class of x.

See also
========

  * ^^ -- logical exclusive-or
  * augmented assignment
  * installing augmented assignment methods

Ways to use symbol ^^=:
=======================

  * AtomicInt ^^= ZZ -- atomic fetch and bitwise xor

For the programmer
==================

The object ^^=, is a keyword.

This operator may be used as a binary operator in an expression like x^^=y. The
user may install a method, for handling such expressions with code
such as

         X ^^= (x,y) -> ...

where X is the class of x.

_= -- augmented assignment for _
********************************

Synopsis
========

  * Usage:
        x _=y

Description
===========

In most cases, x _= y is equivalent to x = x _ y, unless a method is installed
for the class of x.

See also
========

  * _ -- a binary operator, used for subscripting and access to
    elements
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object _=, is a keyword.

This operator may be used as a binary operator in an expression like x_=y. The
user may install a method, for handling such expressions with code
such as

         X _= (x,y) -> ...

where X is the class of x.

|-= -- augmented assignment for |-
**********************************

Synopsis
========

  * Usage:
        x |-=y

Description
===========

In most cases, x |-= y is equivalent to x = x |- y, unless a method is
installed for the class of x.

See also
========

  * |- -- a binary operator
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object |-=, is a keyword.

This operator may be used as a binary operator in an expression like x|-=y. The
user may install a method, for handling such expressions with code
such as

         X |-= (x,y) -> ...

where X is the class of x.

|= -- augmented assignment for |
********************************

Synopsis
========

  * Usage:
        x |=y

Description
===========

In most cases, x |= y is equivalent to x = x | y, unless a method is installed
for the class of x.

See also
========

  * | -- a binary operator, often used for horizontal concatenation
  * augmented assignment
  * installing augmented assignment methods

Ways to use symbol |=:
======================

  * AtomicInt |= ZZ -- atomic fetch and bitwise or

For the programmer
==================

The object |=, is a keyword.

This operator may be used as a binary operator in an expression like x|=y. The
user may install a method, for handling such expressions with code
such as

         X |= (x,y) -> ...

where X is the class of x.

|_= -- augmented assignment for |_
**********************************

Synopsis
========

  * Usage:
        x |_=y

Description
===========

In most cases, x |_= y is equivalent to x = x |_ y, unless a method is
installed for the class of x.

See also
========

  * |_ -- a binary operator, used for restriction to a subset
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object |_=, is a keyword.

This operator may be used as a binary operator in an expression like x|_=y. The
user may install a method, for handling such expressions with code
such as

         X |_= (x,y) -> ...

where X is the class of x.

||= -- augmented assignment for ||
**********************************

Synopsis
========

  * Usage:
        x ||=y

Description
===========

In most cases, x ||= y is equivalent to x = x || y, unless a method is
installed for the class of x.

See also
========

  * || -- a binary operator, often used for vertical concatenation
  * augmented assignment
  * installing augmented assignment methods

For the programmer
==================

The object ||=, is a keyword.

This operator may be used as a binary operator in an expression like x||=y. The
user may install a method, for handling such expressions with code
such as

         X ||= (x,y) -> ...

where X is the class of x.

precedence of operators
***********************

One aspect of parsing precedence is associativity.  A left-associative operator
is one, such as *, with the property that x * y * z is parsed as (x
* y) * z. A right-associative operator is one, such as =, with the
property that x = y = z is parsed as x = (y = z).  These operators are left
associative: #, #?, %, &, *,
**, +, ++, ,, -, .,
see .., ..<, .?, /,
//, <<, @@, ^, ^**, ^<,
see ^<=, ^>, ^>=, ^^, _,
_<, _<=, _>, _>=, |,
|_, ||, and these operators are right associative:
!=, %=, &=, **=, *=,
++=, +=, -=, ->, ..<=,
..=, //=, /=, _colon_, _colon_=,
see ;, <, <-, <<=, <=,
<==, <===, <==>, <==>=, =,
=!=, ==, ===, ===>,
===>=, ==>, ==>=, =>, >,
>=, >>, >>=, ?, ??,
??=, @, @=, @@=, \, \=,
\\, \\=, ^**=, ^=, ^^=,
see _=, |-, |-=, |=, |_=,
see ||=, and, or, SPACE,
xor, .

Here are the operators arranged in order of increasing parsing precedence.  For
example, * has higher parsing precedence than +, and hence 2+3*5 is parsed as
though it had been written as 2+(3*5).  The symbol SPACE,
represents the operator that is used when two things are adjacent in program
code.

+-----------------------------------------------------------------------------+
| 8                                                                           |
|                                                                             |
|10                                                                           |
|                                                                             |
|14  %=  &=  **=  *=  ++=  +=  -=  ->  ..<=  ..=  //=  /=  :=                 |
|                                                                             |
|18                                                                           |
|                                                                             |
|20                                                                           |
|                                                                             |
|22                                                                           |
|                                                                             |
|24                                                                           |
|                                                                             |
|26                                                                           |
|                                                                             |
|28                                                                           |
|                                                                             |
|30                                                                           |
|                                                                             |
|32                                                                           |
|                                                                             |
|34                                                                           |
|                                                                             |
|36                                                                           |
|                                                                             |
|38                                                                           |
|                                                                             |
|40                                                                           |
|                                                                             |
|42                                                                           |
|                                                                             |
|44                                                                           |
|                                                                             |
|46                                                                           |
|                                                                             |
|48                                                                           |
|                                                                             |
|50                                                                           |
|                                                                             |
|52                                                                           |
|                                                                             |
|56                                                                           |
|                                                                             |
|58                                                                           |
|                                                                             |
|60                                                                           |
|                                                                             |
|62                                                                           |
|                                                                             |
|64                                                                           |
|                                                                             |
|66                                                                           |
|                                                                             |
|68                                                    #  #?                  |
|                                                                             |
|70                                                                           |
|-----------------------------------------------------------------------------|
|                        ;                                                    |
|                                                                             |
|                        ,                                                    |
|                                                                             |
| <-  <<=  <==>=  =  ===>=  ==>=  =>  >>  >>=  ??=  @=  @@=  \=  \\=  ^**=  ^=|
|                                                                             |
|                       <<                                                    |
|                                                                             |
|                       |-                                                    |
|                                                                             |
|                   <===  ===>                                                |
|                                                                             |
|                      <==>                                                   |
|                                                                             |
|                    <==  ==>                                                 |
|                                                                             |
|                     ??  or                                                  |
|                                                                             |
|                       xor                                                   |
|                                                                             |
|                       and                                                   |
|                                                                             |
|                       not                                                   |
|                                                                             |
|        !=  <  <=  =!=  ==  ===  >  >=  ?                                    |
|                                                                             |
|                       ||                                                    |
|                                                                             |
|                        :                                                    |
|                                                                             |
|                        |                                                    |
|                                                                             |
|                       ^^                                                    |
|                                                                             |
|                        &                                                    |
|                                                                             |
|                     ..  ..<                                                 |
|                                                                             |
|                    +  ++  -                                                 |
|                                                                             |
|                       **                                                    |
|                                                                             |
|               %  *  /  //  \  \\                                            |
|                                                                             |
|                        @                                                    |
|                                                                             |
|                      SPACE                                                  |
|                                                                             |
|                       (*)                                                   |
|                                                                             |
|                       @@                                                    |
|                                                                             |
|                ^*  ^~  _*  _~  ~                                            |
|                                                                             |
|.  .?  ^  ^**  ^<  ^<=  ^>  ^>=  _  _<  _<=  _>  _>=  |_                     |
|                                                                             |
|                    !  ^!  _!                                                |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|^^=  _=  |-=  |=  |_=  ||=                                                   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
+-----------------------------------------------------------------------------+

See also
========

  * parsing precedence, in detail

operatorAttributes -- a hashtable with information about Macaulay2 operators
****************************************************************************

Synopsis
========

  * Usage:
        operatorAttributes
  * Outputs:
      * an experimental hash table that give information about operators,
        in the Macaulay2 language

Description
===========

Meanings of the symbols used:
  * Flexible -- user defined methods may be installed
  * Binary -- it's a binary operator
  * Prefix -- it's a prefix unary operator
  * Postfix -- it's a postfix unary operator
We intend to add parsing precedences to this table and eliminate
seeParsing.

For the programmer
==================

The object operatorAttributes, is a hash table.

conditional execution -- if-then-else statements
************************************************

The basic way to control the execution of code is with the if,
expression.  Such an expression typically has the form
if X then Y else Z
 and is evaluated as follows.  First X is evaluated.  If the result is true,
then the value of Y is provided, and if the result is false, then the value of
Z is provided.  An error is signalled if the value of X is anything but true or
false.
+--------------------------------------------------+
|i1 : (-4 .. 4) /                                  |
|          (i -> if i < 0 then "neg"               |
|               else if i == 0 then "zer"          |
|               else "pos")                        |
|                                                  |
|o1 = (neg, neg, neg, neg, zer, pos, pos, pos, pos)|
|                                                  |
|o1 : Sequence                                     |
+--------------------------------------------------+
The else clause may be omitted from an if expression.  In that case, if value
of the predicate X is false, then null, is provided as the value of
the if expression.
+--------------------------------------+
|i2 : (-4 .. 4) /                      |
|          (i -> if i < 0 then "neg"   |
|          else if i == 0 then "zer")  |
|                                      |
|o2 = (neg, neg, neg, neg, zer, , , , )|
|                                      |
|o2 : Sequence                         |
+--------------------------------------+
There are a variety of predicate functions (such as <, used above) that yield
true or false and can be used as the predicate in an if expression.  For a
list, see Boolean.  Boolean results may be combined with
not, and, and or.

while -- while loops
********************

Synopsis
========

  * Usage:
        while p list x do z
  * Consequences:
      * The expression p is repeatedly evaluated.  As long as the result is
        true, x is evaluated and its value is saved, and z is evaluated and its
        value is discarded.  When the value of p is false, then the loop
        terminates, and the list of values of x is returned as the value of the
        entire expression.

Description
===========

+---------------------------------------------+
|i1 : i = 0 ; while i < 10 list i^2 do i = i+1|
|                                             |
|o2 = {0, 1, 4, 9, 16, 25, 36, 49, 64, 81}    |
|                                             |
|o2 : List                                    |
+---------------------------------------------+

The list x clause may be omitted, in which case no list is accumulated, and
null, is returned as the value of the expression.

+----------------------------------------------+
|i3 : i = 0 ; while i < 4 do (print i; i = i+1)|
|0                                             |
|1                                             |
|2                                             |
|3                                             |
+----------------------------------------------+

Alternatively, the do z clause may be omitted.

+---------------------------------------------+
|i5 : i = 0 ; while i < 10 list (i = i+1; i^2)|
|                                             |
|o6 = {1, 4, 9, 16, 25, 36, 49, 64, 81, 100}  |
|                                             |
|o6 : List                                    |
+---------------------------------------------+

Observe the use of the semicolon (see ;) in the expression above.

If continue, is executed by x then execution of x is
interrupted, no value is added to the list, and iteration of the loop
continues.

+---------------------------------------------------------------------+
|i7 : i = 0 ; while i < 10 list (i = i+1; if odd i then continue; i^2)|
|                                                                     |
|o8 = {4, 16, 36, 64, 100}                                            |
|                                                                     |
|o8 : List                                                            |
+---------------------------------------------------------------------+

If continue w is executed by x then execution of x is interrupted, the value of
w is added to the list, and iteration of the loop continues.

+--------------------------------------------------------------------------+
|i9 : i = 0 ; while i < 10 list (i = i+1; if odd i then continue 1234; i^2)|
|                                                                          |
|o10 = {1234, 4, 1234, 16, 1234, 36, 1234, 64, 1234, 100}                  |
|                                                                          |
|o10 : List                                                                |
+--------------------------------------------------------------------------+

  If break v is executed by x, then the loop is stopped and v is returned as
its value.

+----------------------------------------------------------------------+
|i11 : i = 0 ; while i < 10 list (i = i+1; if i == 5 then break i; i^2)|
|                                                                      |
|o12 = 5                                                               |
+----------------------------------------------------------------------+

If break, is executed by x, then the loop is stopped and the list
accumulated so far is returned as the value.

+--------------------------------------------------------------------+
|i13 : i = 0 ; while i < 10 list (i = i+1; if i == 5 then break; i^2)|
|                                                                    |
|o14 = {1, 4, 9, 16}                                                 |
|                                                                    |
|o14 : List                                                          |
+--------------------------------------------------------------------+

For the programmer
==================

The object while, is a keyword.

for -- for loops
****************

Description
===========

Synopsis
========

  * Usage:
        for i from m to n when p list x do z
  * Inputs:
      * m, an integer,
      * n, an integer,
  * Outputs:
      * the list of values of the clause x, as described above
  * Consequences:
      * The numbers m and n must be small integers that fit into a single word.
        The variable i is initialized to m. As long as i is not greater than n,
        evaluation of the loop continues. First p is evaluated; as long as the
        value of p is true, evaluation of the loop continues. Next x is
        evaluated and its value is saved, and z is evaluated and its value is
        discarded. Then i is incremented by 1, and the loop repeats. When the
        value of p is false, then the loop terminates, and the list of values
        of x is returned as the value of the entire expression.

Synopsis
========

  * Usage:
        for i in v when p list x do z
  * Inputs:
      * v, a basic list, or an instance of a class with the
        iterator, method installed
  * Consequences:
      * The variable i is set to consecutive values of the list v.  First p is
        evaluated. As long as the value of p is true, evaluation of the loop
        continues.  Next x is evaluated, and its value is saved.  Then z is
        evaluated and its value is discarded.  Then the loop repeats with the
        next element of v.  When the value of p is false, then the loop
        terminates, and the list of values of x is returned as the value of the
        entire expression.

examples
========

+--------------------------------------------------------+
|i1 : for i from 1 to 5 when i < 15 list i^2 do print i  |
|1                                                       |
|2                                                       |
|3                                                       |
|4                                                       |
|5                                                       |
|                                                        |
|o1 = {1, 4, 9, 16, 25}                                  |
|                                                        |
|o1 : List                                               |
+--------------------------------------------------------+
|i2 : for i from 1 to 5 when i^2 < 15 list i^2 do print i|
|1                                                       |
|2                                                       |
|3                                                       |
|                                                        |
|o2 = {1, 4, 9}                                          |
|                                                        |
|o2 : List                                               |
+--------------------------------------------------------+

The expressions in this construction may be arbitrarily complicated. Here is an
example where z is a sequence of expressions separated by semicolons (see
;).

+---------------------------------------+
|i3 : for i from 1 to 3 do (            |
|          print "The value of i is : ";|
|          print i                      |
|          )                            |
|The value of i is :                    |
|1                                      |
|The value of i is :                    |
|2                                      |
|The value of i is :                    |
|3                                      |
+---------------------------------------+

The do z clause may be omitted.

+-------------------------------------------+
|i4 :                                       |
|     for i from 1 to 5 when i < 15 list i^2|
|                                           |
|o4 = {1, 4, 9, 16, 25}                     |
|                                           |
|o4 : List                                  |
+-------------------------------------------+

The from m clause may be omitted, in which case i starts with 0.

+------------------------------------+
|i5 : for i to 5 when i < 15 list i^2|
|                                    |
|o5 = {0, 1, 4, 9, 16, 25}           |
|                                    |
|o5 : List                           |
+------------------------------------+

The when p clause may be omitted.

+-------------------------+
|i6 : for i to 5 list i^2 |
|                         |
|o6 = {0, 1, 4, 9, 16, 25}|
|                         |
|o6 : List                |
+-------------------------+

The to n clause may be omitted.

+------------------------------------------------------------------+
|i7 : for i when i < 15 list i^2                                   |
|                                                                  |
|o7 = {0, 1, 4, 9, 16, 25, 36, 49, 64, 81, 100, 121, 144, 169, 196}|
|                                                                  |
|o7 : List                                                         |
+------------------------------------------------------------------+

The list x clause may be omitted.

+-----------------------------------+
|i8 : for i when i^2 < 15 do print i|
|0                                  |
|1                                  |
|2                                  |
|3                                  |
+-----------------------------------+

If continue, is executed by x then execution of x is
interrupted, no value is added to the list, and iteration of the loop
continues.

+----------------------------------------------------------------+
|i9 : for i from 0 when i < 10 list (if odd i then continue; i^2)|
|                                                                |
|o9 = {0, 4, 16, 36, 64}                                         |
|                                                                |
|o9 : List                                                       |
+----------------------------------------------------------------+

If continue w is executed by x then execution of x is interrupted, the value of
w is added to the list, and iteration of the loop continues.

+----------------------------------------------------------------------+
|i10 : for i from 0 when i < 10 list (if odd i then continue 4567; i^2)|
|                                                                      |
|o10 = {0, 4567, 4, 4567, 16, 4567, 36, 4567, 64, 4567}                |
|                                                                      |
|o10 : List                                                            |
+----------------------------------------------------------------------+

  If break v is executed by x, then the loop is stopped and v is returned as
its value.

+----------------------------------------------------------------+
|i11 : for i from 0 when i < 10 list (if i== 5 then break i; i^2)|
|                                                                |
|o11 = 5                                                         |
+----------------------------------------------------------------+

If break, is executed by x, then the loop is stopped and the list
accumulated so far is returned as the value.

+--------------------------------------------------------------+
|i12 : for i from 0 when i < 10 list (if i== 5 then break; i^2)|
|                                                              |
|o12 = {0, 1, 4, 9, 16}                                        |
|                                                              |
|o12 : List                                                    |
+--------------------------------------------------------------+
+----------------------------+
|i13 : for i in 0..3 list i^2|
|                            |
|o13 = {0, 1, 4, 9}          |
|                            |
|o13 : List                  |
+----------------------------+

If v is an instance of any class with the iterator, method
installed (e.g., a string), then the values of i are obtained by repeatedly
calling next, on the output of iterator v until
StopIteration, is returned.

+-------------------------------+
|i14 : for i in "foo" do print i|
|f                              |
|o                              |
|o                              |
+-------------------------------+

Caveat
======

The variable i is a new local variable whose scope includes only the
expressions p, x, and z in the body of the loop.  Moreover, new local variables
defined inside the body of the loop will not be visible outside it.

For the programmer
==================

The object for, is a keyword.

mapping over hash tables -- apply a function to each element of a hash table
****************************************************************************

Each entry in a hash table consists of a key and a value.  We provide three
ways to map functions over a hash table, depending on whether the function is
to receive a value and return a new value, to receive a key and return a new
key, or to receive a key-value pair and return a new key-value pair.  The
corresponding functions, see applyValues, applyKeys,
and applyPairs, are illustrated in the next
example.
+----------------------------------------------+
|i1 : x = new HashTable from {a=>1, b=>2}      |
|                                              |
|o1 = HashTable{a => 1}                        |
|               b => 2                         |
|                                              |
|o1 : HashTable                                |
+----------------------------------------------+
|i2 : applyValues(x, value -> 1000*value)      |
|                                              |
|o2 = HashTable{a => 1000}                     |
|               b => 2000                      |
|                                              |
|o2 : HashTable                                |
+----------------------------------------------+
|i3 : applyKeys(x, key -> {key})               |
|                                              |
|o3 = HashTable{{a} => 1}                      |
|               {b} => 2                       |
|                                              |
|o3 : HashTable                                |
+----------------------------------------------+
|i4 : applyPairs(x, (key,value) -> (value,key))|
|                                              |
|o4 = HashTable{1 => a}                        |
|               2 => b                         |
|                                              |
|o4 : HashTable                                |
+----------------------------------------------+
The functions, see scanValues, scanKeys, and
scanPairs, are similar, but the values returned are discarded
instead of being assembled into a new hash table.
+----------------------------------------+
|i5 : x = new HashTable from {a=>1, b=>2}|
|                                        |
|o5 = HashTable{a => 1}                  |
|               b => 2                   |
|                                        |
|o5 : HashTable                          |
+----------------------------------------+
|i6 : scanValues(x, print)               |
|1                                       |
|2                                       |
+----------------------------------------+
|i7 : scanKeys(x, print)                 |
|a                                       |
|b                                       |
+----------------------------------------+
|i8 : scanPairs(x, print)                |
|(a, 1)                                  |
|(b, 2)                                  |
+----------------------------------------+
The function merge, can be used to merge two hash tables.  The
result is a hash table whose keys are those occurring in one of the two
incoming hash tables.  We must provide a function of two arguments that is used
to combine the values when a key occurs in both hash tables.
+--------------------------------------------+
|i9 : y = new HashTable from {b=>200, c=>300}|
|                                            |
|o9 = HashTable{b => 200}                    |
|               c => 300                     |
|                                            |
|o9 : HashTable                              |
+--------------------------------------------+
|i10 : merge(x, y, plus)                     |
|                                            |
|o10 = HashTable{a => 1  }                   |
|                b => 202                    |
|                c => 300                    |
|                                            |
|o10 : HashTable                             |
+--------------------------------------------+
The function combine, can be used to combine two hash tables x
and y into a new hash table.  Three functions must be provided.  The first one
produces new keys from a key of x and a key of y.  The second one produces a
new values from a value of x and a value of y.  The third one is used to
combine values when two new keys turn out to be the same.
+--------------------------------------+
|i11 : combine(x,y,identity,times,plus)|
|                                      |
|o11 = HashTable{(a, b) => 200}        |
|                (a, c) => 300         |
|                (b, b) => 400         |
|                (b, c) => 600         |
|                                      |
|o11 : HashTable                       |
+--------------------------------------+

error handling -- signalling and trapping errors
************************************************

When an error occurs in your program, an error message will appear that gives
the name of the file, the line number, and the column number of the code that
provoked the error.

You may use the function error, in your programs to signal errors.
Your error message will appear on the screen and execution will be stopped.

The function try, can be used to catch an error before execution is
stopped and to continue or to try something else.

error -- deliver error message
******************************

Synopsis
========

  * Usage:
        error s
  * Inputs:
      * s, a string, a string or a sequence of things that can
        be converted to strings
  * Consequences:
      * an error message is displayed

Description
===========

error s causes an error message s to be displayed.

The error message s (which should be a string or a sequence of things that can
be converted to strings and concatenated) is printed. Execution of the code is
interrupted, and control is returned to top level. Here is an explicit example
showing how this command is used:
exampleCode = p -> (
     if not isPrime p
     then error "expected a prime integer";
     if p == 2
     then error "expected an odd prime";
     lift((p+1)/2, ZZ)
     );

Eventually we will have a means of ensuring that the line number printed out
with the error message will have more significance, but currently it is the
location in the code of the error expression itself.

If the error message begins with a hyphen, then the word "error" will not be
inserted into the error message.

For the programmer
==================

The object error, is a function closure.

try -- catch an error
*********************

Synopsis
========

  * Usage:
        try x then y else z
  * Inputs:
      * x, code
      * y, code
      * z, code
  * Consequences:
      * the code x is run; if no error or alarm, occurs, then the
        code y is run; otherwise, the code z is run

Description
===========

The return value is the value returned by y or z, as the case may be.

The clause 'then y' may be omitted, in which case the return value is the value
returned by x, if there is no error or alarm.

The clause 'else z' may be omitted, in which case the return value is the value
returned by y, unless an error or alarm occurs, in which case null,
is returned.

The clauses 'then y else z' may both be omitted, in which case the return value
is the value returned by x, unless an error or alarm occurs, in which case
null, is returned.

The behavior of interrupts (other than alarms) is unaffected.
+------------------------------------------+
|i1 : apply(-3..3,i->try 1/i else infinity)|
|                                          |
|        1    1                   1  1     |
|o1 = (- -, - -, -1, infinity, 1, -, -)    |
|        3    2                   2  3     |
|                                          |
|o1 : Sequence                             |
+------------------------------------------+

Caveat
======

We will change the behavior of this function soon so that it will be possible
to catch errors of a particular type.  Meanwhile, users are recommended to use
this function sparingly, if at all.

For the programmer
==================

The object try, is a keyword.

throw -- throw and catch exceptions
***********************************

Synopsis
========

  * Usage:
        catch c
        throw x
  * Outputs:
      * catch returns the value obtained by evaluating the code c, or, if a
        throw was executed during the evaluation of c, the argument given to
        throw.
  * Consequences:
      * throw passes the flow of control to the surrounding catch, and x is
        returned as its value

Description
===========

+-----------------------------------------------------------------+
|i1 : catch scan(0..10, i -> if i == 5 then throw 18 else print i)|
|0                                                                |
|1                                                                |
|2                                                                |
|3                                                                |
|4                                                                |
|                                                                 |
|o1 = 18                                                          |
+-----------------------------------------------------------------+

For the programmer
==================

The object throw, is a keyword.

using functions
***************

There are many functions in Macaulay2 that do various things.  You can get a
brief indication of what a function does by typing a ? before its name.  In
this case, one would see that the function sin, takes a single
argument x.  We apply a function to its argument by typing them in adjacent
positions.  It is possible but not necessary to place parentheses around the
argument.
+-------------------------+
|i1 : sin 1.2             |
|                         |
|o1 = .9320390859672263   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+
|i2 : sin(1.2)            |
|                         |
|o2 = .9320390859672263   |
|                         |
|o2 : RR (of precision 53)|
+-------------------------+
|i3 : sin(1.0+0.2)        |
|                         |
|o3 = .9320390859672263   |
|                         |
|o3 : RR (of precision 53)|
+-------------------------+
In parsing the operator ^, takes precedence over adjacency, so the
function is applied after the power is computed in the following code.  This
may not be what you expect.
+--------------------+
|i4 : print(10 + 1)^2|
|121                 |
+--------------------+
Some functions take more than one argument, and the arguments are separated by
a comma, and then parentheses are needed.
+----------------------+
|i5 : append           |
|                      |
|o5 = append           |
|                      |
|o5 : CompiledFunction |
+----------------------+
|i6 : append({a,b,c},d)|
|                      |
|o6 = {a, b, c, d}     |
|                      |
|o6 : List             |
+----------------------+
Some functions take a variable number of arguments.
+------------------------------------+
|i7 : join                           |
|                                    |
|o7 = join                           |
|                                    |
|o7 : CompiledFunction               |
+------------------------------------+
|i8 : join({a,b},{c,d},{e,f},{g,h,i})|
|                                    |
|o8 = {a, b, c, d, e, f, g, h, i}    |
|                                    |
|o8 : List                           |
+------------------------------------+
Functions, like anything else, can be assigned to variables.  You may do this
to provide handy private abbreviations.
+-------------------+
|i9 : ap = append;  |
+-------------------+
|i10 : ap({a,b,c},d)|
|                   |
|o10 = {a, b, c, d} |
|                   |
|o10 : List         |
+-------------------+

using functions with optional inputs
************************************

Some functions accept optional inputs in addition to their required inputs.  In
the documentation, such an optional input is indicated by writing NAME => ...,
where NAME is the name of the optional input, and the dots indicate the place
where the user will provide the value of the optional input.

Optional inputs can be provided between parentheses along with the other inputs
(or arguments) of the function.  For example, if the function is normally used
with two required inputs, then instead of typing f(x,y), you may type f(x,y,FOO
=> t, BAR => u), where t is the value to be provided to f as the value of the
optional input named FOO and u is the value to be provided to f as the value of
the optional input named BAR.

The optional inputs can be inserted in any order, and may even occur before the
required inputs.  If more than one optional input with the same option name are
given, then the value accompanying the right-most one is the value provided to
the function.

Use options, to discover the optional arguments
accepted by a function.
+--------------------------------------------------------------------+
|i1 : R = ZZ/101[x,y,z,w];                                           |
+--------------------------------------------------------------------+
|i2 : gb ideal(x*y-z^2,y^2-w^2)                                      |
|                                                                    |
|o2 = GroebnerBasis[status: done; S-pairs encountered up to degree 4]|
|                                                                    |
|o2 : GroebnerBasis                                                  |
+--------------------------------------------------------------------+
|i3 : gens oo                                                        |
|                                                                    |
|o3 = | y2-w2 xy-z2 yz2-xw2 z4-x2w2 |                                |
|                                                                    |
|             1      4                                               |
|o3 : Matrix R  <-- R                                                |
+--------------------------------------------------------------------+
One of the optional arguments for gb, is named DegreeLimit,;
we may use options, to discover that,
as follows.
+----------------------------------------------------+
|i4 : options gb                                     |
|                                                    |
|o4 = OptionTable{Algorithm => Inhomogeneous        }|
|                 BasisElementLimit => infinity      |
|                 ChangeMatrix => false              |
|                 CodimensionLimit => infinity       |
|                 DegreeLimit => {}                  |
|                 GBDegrees => null                  |
|                 HardDegreeLimit => null            |
|                 Hilbert => null                    |
|                 MaxReductionCount => 10            |
|                 PairLimit => infinity              |
|                 StopBeforeComputation => false     |
|                 StopWithMinimalGenerators => false |
|                 Strategy => {}                     |
|                 SubringLimit => infinity           |
|                 Syzygies => false                  |
|                 SyzygyLimit => infinity            |
|                 SyzygyRows => infinity             |
|                                                    |
|o4 : OptionTable                                    |
+----------------------------------------------------+
The optional input named DegreeLimit, can be used to specify
that the computation should stop after a certain degree has been reached.
+---------------------------------------------------------------------------+
|i5 : gb(ideal(x*y-z^2,y^2-w^2), DegreeLimit => 2)                          |
|                                                                           |
|o5 = GroebnerBasis[status: DegreeLimit; all S-pairs handled up to degree 2]|
|                                                                           |
|o5 : GroebnerBasis                                                         |
+---------------------------------------------------------------------------+
|i6 : gens oo                                                               |
|                                                                           |
|o6 = | y2-w2 xy-z2 |                                                       |
|                                                                           |
|             1      2                                                      |
|o6 : Matrix R  <-- R                                                       |
+---------------------------------------------------------------------------+

Programming hint
================

The value returned by options, is a type of hash
table that can be used to obtain default values.

See also making new functions with optional arguments.

+--------------------------+
|i7 : (options gb).Syzygies|
|                          |
|o7 = false                |
+--------------------------+

making functions
****************

The operator ->, is used to make new functions.  On its left we
provide the names of the parameters to the function, and to the right we
provide the body of the function, an expression involving those parameters
whose value is to be computed when the function is applied.  Let's illustrate
this by making a function for squaring numbers and calling it sq.
+--------------------+
|i1 : sq = i -> i^2  |
|                    |
|o1 = sq             |
|                    |
|o1 : FunctionClosure|
+--------------------+
|i2 : sq 10          |
|                    |
|o2 = 100            |
+--------------------+
|i3 : sq(5+5)        |
|                    |
|o3 = 100            |
+--------------------+
When the function is evaluated, the argument is evaluated and assigned
temporarily as the value of the parameter i.  In the example above, i was
assigned the value 10, and then the body of the function was evaluated,
yielding 100.

Here is how we make a function with more than one argument.
+----------------------+
|i4 : tm = (i,j) -> i*j|
|                      |
|o4 = tm               |
|                      |
|o4 : FunctionClosure  |
+----------------------+
|i5 : tm(5,7)          |
|                      |
|o5 = 35               |
+----------------------+
Functions can be used without assigning them to variables.
+-----------------+
|i6 : (i -> i^2) 7|
|                 |
|o6 = 49          |
+-----------------+
Another way to make new functions is to compose two old ones with the operator
@@.
+-------------------------+
|i7 : sincos = sin @@ cos |
|                         |
|o7 = sincos              |
|                         |
|o7 : FunctionClosure     |
+-------------------------+
|i8 : sincos 2.2          |
|                         |
|o8 = -.5551149157594247  |
|                         |
|o8 : RR (of precision 53)|
+-------------------------+
|i9 : sin(cos(2.2))       |
|                         |
|o9 = -.5551149157594247  |
|                         |
|o9 : RR (of precision 53)|
+-------------------------+
Code that implements composition of functions is easy to write, because
functions can create new functions and return them.  We illustrate this by
writing a function called comp that will compose two functions, just as the
operator @@, did above.
+---------------------------------+
|i10 : comp = (f,g) -> x -> f(g x)|
|                                 |
|o10 = comp                       |
|                                 |
|o10 : FunctionClosure            |
+---------------------------------+
|i11 : sincos = comp(sin,cos)     |
|                                 |
|o11 = sincos                     |
|                                 |
|o11 : FunctionClosure            |
+---------------------------------+
|i12 : cossin = comp(cos,sin)     |
|                                 |
|o12 = cossin                     |
|                                 |
|o12 : FunctionClosure            |
+---------------------------------+
|i13 : sincos 2.2                 |
|                                 |
|o13 = -.5551149157594247         |
|                                 |
|o13 : RR (of precision 53)       |
+---------------------------------+
|i14 : cossin 2.2                 |
|                                 |
|o14 = .6905866885609112          |
|                                 |
|o14 : RR (of precision 53)       |
+---------------------------------+
We created two composite functions in the example above to illustrate an
important point.  The parameters f and g acquire values when sincos is created,
and they acquire different values when cossin is created.  These two sets of
values do not interfere with each other, and the memory they occupy will be
retained as long as they are needed.  Indeed, the body of both functions is x
-> f(g(x)), and the only difference between them is the values assigned to the
parameters f and g.

The class of all functions is Function.

local variables in a function
*****************************

A local variable in a function is one that is not visible to code in other
locations.  Correct use of local variables is important, for data stored in
global variables will stay around forever, needlessly occupying valuable memory
space.  For recursive functions especially, it is important to use local
variables so that one invocation of the function doesn't interfere with
another.

The simplest way to create a local variable in a function is with the
assignment operator _colon_=.  The expression X := Y means that
the value of Y will be assigned to a newly created local variable whose name is
X.  Once X has been created, new values can be assigned to it with expressions
like X = Z.
+-------------------------------------------------------------------+
|i1 : i = 22;                                                       |
+-------------------------------------------------------------------+
|i2 : f = () -> (i := 0; while i<9 do (<< i << " "; i=i+1); <<endl;)|
|                                                                   |
|o2 = f                                                             |
|                                                                   |
|o2 : FunctionClosure                                               |
+-------------------------------------------------------------------+
|i3 : f()                                                           |
|0 1 2 3 4 5 6 7 8                                                  |
+-------------------------------------------------------------------+
|i4 : i                                                             |
|                                                                   |
|o4 = 22                                                            |
+-------------------------------------------------------------------+
In the example above, we see that the function f does its work with a local
variable i that is unrelated to the global variable i introduced on the first
line.

In the next example, we show that the local variables in two invocations of a
function don't interfere with each other.  We write a function f that returns a
newly created counting function. The counting function simply returns the
number of times it has been called.
+--------------------------------------+
|i5 : f = () -> (i := 0; () -> i = i+1)|
|                                      |
|o5 = f                                |
|                                      |
|o5 : FunctionClosure                  |
+--------------------------------------+
Let's use f to create counting functions and show that they operate
independently.
+--------------------------------------------+
|i6 : p = f()                                |
|                                            |
|o6 = p                                      |
|                                            |
|o6 : FunctionClosure                        |
+--------------------------------------------+
|i7 : q = f()                                |
|                                            |
|o7 = q                                      |
|                                            |
|o7 : FunctionClosure                        |
+--------------------------------------------+
|i8 : p(),p(),p(),p(),q(),p(),p(),q(),p(),p()|
|                                            |
|o8 = (1, 2, 3, 4, 1, 5, 6, 2, 7, 8)         |
|                                            |
|o8 : Sequence                               |
+--------------------------------------------+

making functions with a variable number of arguments
****************************************************

It is easy to write a function with a variable number of arguments. Define the
function with just one parameter, with no parentheses around it.  If the
function is called with several arguments, the value of the single parameter
will be a sequence containing the several arguments; if the function is called
with one argument, the value of the parameter will be that single argument.
+---------------------------------------------------------+
|i1 : f = x -> {class x, if class x === Sequence then #x};|
+---------------------------------------------------------+
|i2 : f()                                                 |
|                                                         |
|o2 = {Sequence, 0}                                       |
|                                                         |
|o2 : List                                                |
+---------------------------------------------------------+
|i3 : f(3)                                                |
|                                                         |
|o3 = {ZZ, }                                              |
|                                                         |
|o3 : List                                                |
+---------------------------------------------------------+
|i4 : f(3,4)                                              |
|                                                         |
|o4 = {Sequence, 2}                                       |
|                                                         |
|o4 : List                                                |
+---------------------------------------------------------+
|i5 : f(3,4,5)                                            |
|                                                         |
|o5 = {Sequence, 3}                                       |
|                                                         |
|o5 : List                                                |
+---------------------------------------------------------+
We could use the function sequence, to bring the case where
there is just one argument into line with the others.  It will enclose anything
that is not a sequence in a sequence of length one.
+-------------------------+
|i6 : f = x -> (          |
|          x = sequence x;|
|          {class x, #x});|
+-------------------------+
|i7 : f()                 |
|                         |
|o7 = {Sequence, 0}       |
|                         |
|o7 : List                |
+-------------------------+
|i8 : f(3)                |
|                         |
|o8 = {Sequence, 1}       |
|                         |
|o8 : List                |
+-------------------------+
|i9 : f(3,4)              |
|                         |
|o9 = {Sequence, 2}       |
|                         |
|o9 : List                |
+-------------------------+
|i10 : f(3,4,5)           |
|                         |
|o10 = {Sequence, 3}      |
|                         |
|o10 : List               |
+-------------------------+
As an aside, we reveal that there is a way to define a function of one argument
that will signal an error if it's given more than one argument: put parentheses
around the single parameter in the definition of the function. As a side effect
it can be used to extract the single element from a singleton sequence.
+-------------------+
|i11 : ((x) -> x) 3 |
|                   |
|o11 = 3            |
+-------------------+
|i12 : 1 : 3        |
|                   |
|o12 = 1 : (3)      |
|                   |
|o12 : Sequence     |
+-------------------+
|i13 : ((x) -> x) oo|
|                   |
|o13 = 3            |
+-------------------+

making functions with multiple return values
********************************************

A function may return multiple values by returning a sequence.
Multiple assignment (see =) or multiple local assignment (see
_colon_=) can be used to assign the values to separate variables, if the
number of values to be returned is known.

+----------------------------+
|i1 : f = i -> (i, i^2, i^3);|
+----------------------------+
|i2 : (x,y,z) = f 3          |
|                            |
|o2 = (3, 9, 27)             |
|                            |
|o2 : Sequence               |
+----------------------------+
|i3 : x                      |
|                            |
|o3 = 3                      |
+----------------------------+
|i4 : y                      |
|                            |
|o4 = 9                      |
+----------------------------+
|i5 : z                      |
|                            |
|o5 = 27                     |
+----------------------------+

Simple assignment may be used if the number of values to be returned is
unknown.

+----------------+
|i6 : s = f 4    |
|                |
|o6 = (4, 16, 64)|
|                |
|o6 : Sequence   |
+----------------+
|i7 : #s         |
|                |
|o7 = 3          |
+----------------+
|i8 : s_0        |
|                |
|o8 = 4          |
+----------------+
|i9 : s_1        |
|                |
|o9 = 16         |
+----------------+
|i10 : s_2       |
|                |
|o10 = 64        |
+----------------+

making new functions with optional arguments
********************************************

Let's consider an example where we wish to construct a linear function of x
called f, with the slope and y-intercept of the graph being optional arguments
of f.  We use the >>, operator to attach the default values to our
function, coded in a special way.
+----------------------------------------------------+
|i1 : opts = {Slope => 1, Intercept => 1}            |
|                                                    |
|o1 = {Slope => 1, Intercept => 1}                   |
|                                                    |
|o1 : List                                           |
+----------------------------------------------------+
|i2 : f = opts >> o -> x -> x * o.Slope + o.Intercept|
|                                                    |
|o2 = f                                              |
|                                                    |
|o2 : FunctionClosure                                |
+----------------------------------------------------+
|i3 : f 5                                            |
|                                                    |
|o3 = 6                                              |
+----------------------------------------------------+
|i4 : f(5, Slope => 100)                             |
|                                                    |
|o4 = 501                                            |
+----------------------------------------------------+
|i5 : f(5, Slope => 100, Intercept => 1000)          |
|                                                    |
|o5 = 1500                                           |
+----------------------------------------------------+
In the example the function body is the code x * opts.Slope + opts.Intercept.
When it is evaluated, a hash table is assigned to opts; its keys are the names
of the optional arguments, and the values are the corresponding current values,
obtained either from the default values specified in the definition of f, or
from the options specified at the time f is called.

In the example above, the inner function has just one argument, x, but handling
multiple arguments is just as easy.  Here is an example with two arguments.
+--------------------------------------------------+
|i6 : f = {a => 1000} >> o -> (x,y) -> x * o.a + y;|
+--------------------------------------------------+
|i7 : f(3,7)                                       |
|                                                  |
|o7 = 3007                                         |
+--------------------------------------------------+
|i8 : f(5,11,a=>10^20)                             |
|                                                  |
|o8 = 500000000000000000011                        |
+--------------------------------------------------+

using hooks
***********

Hooks in Macaulay2 are a type of dynamic dispatch (see
https://en.wikipedia.org/wiki/dynamic_dispatch ), that is, a way to provide
different implementations of methods and events and select which implementation
to use depending on characteristics of the input arguments.

The addHook, method allows the user to attach multiple hooks, or
strategies, for computing a method key such as (intersect, Ideal, Ideal), or a
symbol.

Hooks can be functions or methods, and they can accept optional arguments.

+--------------------------------------------------------------------------+
|i1 : f = {a=>3, c=>12} >> opts -> val -> if val == 1 then opts.a + opts.c;|
+--------------------------------------------------------------------------+
|i2 : g = method(Options => {b => 5});                                     |
+--------------------------------------------------------------------------+
|i3 : g ZZ := opts -> val -> if val == 2 then opts.b + 1;                  |
+--------------------------------------------------------------------------+
|i4 : h = val -> if val == 3 then 24;                                      |
+--------------------------------------------------------------------------+
|i5 : foo = method(Options => true);                                       |
+--------------------------------------------------------------------------+
|i6 : addHook((foo, ZZ), f)                                                |
|                                                                          |
|o6 = f                                                                    |
|                                                                          |
|o6 : FunctionClosure                                                      |
+--------------------------------------------------------------------------+
|i7 : addHook((foo, ZZ), g, Strategy => "G")                               |
|                                                                          |
|o7 = g                                                                    |
|                                                                          |
|o7 : MethodFunctionWithOptions                                            |
+--------------------------------------------------------------------------+
|i8 : addHook((foo, ZZ), h)                                                |
|                                                                          |
|o8 = h                                                                    |
|                                                                          |
|o8 : FunctionClosure                                                      |
+--------------------------------------------------------------------------+

The method runHooks, runs all the hooks until one of them
returns a non-see null, value. Hooks are run in order starting from the
most recently added hook. Because of this, each hook should be able to decide
quickly whether it is the right implementation for the input, and if not should
return null.

Any optional argument passed to runHooks that matches a key in the
OptionTable, of a hook will be passed on to it. Otherwise it will
be ignored.

+-----------------------------------------------------------------------+
|i9 : foo ZZ := true >> opts -> args -> runHooks((foo, ZZ), args, opts);|
+-----------------------------------------------------------------------+
|i10 : debugLevel = 1                                                   |
|                                                                       |
|o10 = 1                                                                |
+-----------------------------------------------------------------------+
|i11 : assert( foo 1 == 15 )                                            |
| -- (foo,ZZ) with Strategy => 2 from h                                 |
| -- (foo,ZZ) with Strategy => G from g                                 |
| -- (foo,ZZ) with Strategy => 0 from f                                 |
+-----------------------------------------------------------------------+
|i12 : assert( foo(2, b => 9) == 10 )                                   |
| -- (foo,ZZ) with Strategy => 2 from h                                 |
| -- (foo,ZZ) with Strategy => G from g                                 |
+-----------------------------------------------------------------------+
|i13 : assert( foo 3 == 24 )                                            |
| -- (foo,ZZ) with Strategy => 2 from h                                 |
+-----------------------------------------------------------------------+

The function hooks, lists all hooks attached to a method key or
symbol, in the order in which they were added, that is, the opposite order in
which they are run.

+-------------------------------------+
|i14 : hooks(foo, ZZ)                 |
|                                     |
|o14 = {0 => (foo, ZZ, Strategy => 0)}|
|      {1 => (foo, ZZ, Strategy => G)}|
|      {2 => (foo, ZZ, Strategy => 2)}|
|                                     |
|o14 : NumberedVerticalList           |
+-------------------------------------+

Hooks are automatically assigned an integer which can be used as the value of
the Strategy option to specify only one strategy to run.

+--------------------------------------------+
|i15 : assert( foo(3, Strategy => 2) == 24 ) |
| -- (foo,ZZ) with Strategy => 2 from h      |
+--------------------------------------------+
|i16 : assert( foo(2, Strategy => "G") == 6 )|
| -- (foo,ZZ) with Strategy => G from g      |
+--------------------------------------------+

If the code for a hook was read from a file, then it can be retrieved with the
code, function.

+-----------------------------------------------------------------------------+
|i17 : hooks(quotient, Ideal, Ideal)                                          |
|                                                                             |
|o17 = {0 => (quotient, Ideal, Ideal, Strategy => Quotient)}                  |
|      {1 => (quotient, Ideal, Ideal, Strategy => Iterate) }                  |
|      {2 => (quotient, Ideal, Ideal, Strategy => Monomial)}                  |
|                                                                             |
|o17 : NumberedVerticalList                                                   |
+-----------------------------------------------------------------------------+
|i18 : code 1                                                                 |
|                                                                             |
|o18 = -- code for strategy: quotient(Ideal,Ideal,Strategy => Iterate)        |
|      /usr/local/share/Macaulay2/Saturation.m2:                              |
|      217:15-223:82: --source code:                                          |
|          Iterate => (opts, I, J) -> (                                       |
|              R := ring I;                                                   |
|              -- TODO: extend this into a strategy for any PID               |
|              if R === ZZ then return ideal sub(gcd I_* / gcd flatten(I_*, J |
|              fold(first entries mingens J, ideal 1_R, (f, M1) ->            |
|                  if generators(f * M1) % generators I == 0 then M1          |
|                  else intersect(M1, quotient(I, ideal f, opts, Strategy =>  |
|-----------------------------------------------------------------------------|
|_*), ZZ);                                                                    |
|                                                                             |
|                                                                             |
|Quotient)))),                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * code -- display source code
  * method -- make a new method function
  * methods -- list methods
  * making a new method function

hooks -- list hooks attached to a key
*************************************

Synopsis
========

  * Usage:
        hooks key
        hooks store
        hooks(store, key)
  * Inputs:
      * key, a sequence, or a symbol,
      * store, a hash table, the hash table where the hooks
        are stored
  * Optional inputs,:
      * Strategy => a thing, default value null, only list hooks
        with the given strategy
  * Outputs:
      * a numbered vertical list, of those hooks
        associated with key or stored in store

Description
===========

+---------------------------------------------------------------------------+
|i1 : hooks(intersect, Ideal, Ideal)                                        |
|                                                                           |
|o1 = {0 => (intersect, Ideal, Ideal, Strategy => Default)    }             |
|     {1 => (intersect, Ideal, Ideal, Strategy => Elimination)}             |
|     {2 => (intersect, Ideal, Ideal, Strategy => Monomial)   }             |
|                                                                           |
|o1 : NumberedVerticalList                                                  |
+---------------------------------------------------------------------------+
|i2 : code 0                                                                |
|                                                                           |
|o2 = -- code for strategy: intersect(Ideal,Ideal,Strategy => Default)      |
|     ../../../../../Macaulay2/m2/intersect.m2:116:15-116:67: --source code:|
|         Default => (opts, L) -> ideal intersect(opts, apply(L, module)),  |
+---------------------------------------------------------------------------+
|i3 : hooks(quotient, Strategy => Iterate)                                  |
|                                                                           |
|o3 = {0 => (quotient, Ideal, Ideal, Strategy => Iterate)  }                |
|     {1 => (quotient, Module, Ideal, Strategy => Iterate) }                |
|     {2 => (quotient, Module, Module, Strategy => Iterate)}                |
|                                                                           |
|o3 : NumberedVerticalList                                                  |
+---------------------------------------------------------------------------+

See also
========

  * addHook -- add a hook function to an object for later
    processing
  * runHooks -- run the hook functions stored in an object

Ways to use hooks:
==================

  * "hooks(HashTable)"
  * "hooks(List)"
  * "hooks(Sequence)"
  * "hooks(Symbol)"
  * "hooks(Thing)"
  * "hooks(ZZ)"

For the programmer
==================

The object hooks, is a method function with a single argument.

addHook -- add a hook function to an object for later processing
****************************************************************

Synopsis
========

  * Usage:
        addHook(key, hook)
        addHook(store, key, hook)
  * Inputs:
      * key, a sequence, or a symbol,
      * hook, a function,
      * store, a mutable hash table,
  * Optional inputs,:
      * Strategy => a thing, default value null, specifies the
        name for the hook
  * Consequences:
      * the function hook is added to the (possibly absent) hash table of
        hooks, which is either stored in the mutable hash table store or under
        the youngest, Type, T listed in the
        method, key key. In the latter case, the hash table is either
        stored in T.Hooks#key if T is mutable, or in T.cache.Hooks#key
        otherwise. If no appropriate object is found, or if key is a
        Symbol, then the hook is stored under the hash table
        GlobalHookStore

Description
===========

For an explanation and examples of hooks see using hooks.

Code
====

../../../../../Macaulay2/m2/methods.m2:619:46-628:36: --source code:
addHook(MutableHashTable, Thing, Function) := opts -> (store, key, hook) -> (
    -- this is the hashtable of Hooks for a specific key, which stores HookAlgo
    if not store#?key then store#key = new MutableHashTable from {
        HookAlgorithms => new MutableHashTable, -- a mutable hash table "strate
        HookPriority   => new MutableList};     -- a mutable list of strategy k
    store = store#key;
    ind := #store.HookPriority; -- index to add the hook in the list; TODO: use
    alg := if opts.Strategy =!= null then opts.Strategy else ind;
    store.HookPriority#ind = alg;
    store.HookAlgorithms#alg = hook)
-------------------------------------------------------------------------------
rithms and HookPriority

gy key" => "strategy code"
eys, in order

 Priority to insert in the middle?

See also
========

  * hooks -- list hooks attached to a key
  * runHooks -- run the hook functions stored in an object

Ways to use addHook:
====================

  * "addHook(MutableHashTable,Thing,Function)"
  * "addHook(Sequence,Function)"
  * "addHook(Symbol,Function)"

For the programmer
==================

The object addHook, is a method function with options.

runHooks -- run the hook functions stored in an object
******************************************************

Synopsis
========

  * Usage:
        runHooks(key, args)
        runHooks(store, key, args)
  * Inputs:
      * key, a sequence, or a symbol,
      * args, a thing,
      * store, a mutable hash table,
  * Outputs:
      * if one of the hook functions returns a non-see null, value,
        that value will be returned. Otherwise null, will be
        returned.

Description
===========

Each function hook in the hash table of hooks associated to key is called with
args as its argument or sequence of arguments. The optional argument Strategy
can be used to specify which hook should be run. See addHook,
for where the hooks are stored.

Any other optional argument for runHooks that matches any key in options hook
will be passed on to hook. All other options are ignored.

For further explanation and examples of hooks see using hooks.

Code
====

../../../../../Macaulay2/m2/option.m2:37:14-41:8: --source code:
  (opts,f) -> args -> (
       -- Common code for functions created with >> to separate options from ar
       -- uncurry(f, (new OptionTable from toList select(args, i -> instance(i,
       uncurry(f, override (,args))
       )
| symbol  class            value
| ------  -----            -----
| f       FunctionClosure  FunctionClosure[../../../../../Macaulay2/m2/methods.
| opts    Boolean          true
| -- function f:
| ../../../../../Macaulay2/m2/methods.m2:653:52-669:108: --source code:
| runHooks(MutableHashTable, Thing, Thing) := true >> opts -> (store, key, args
|     store = if store#?key then store#key else (
|         if debugLevel > 1 then printerr("runHooks: no hooks installed for ",
|     alg := if opts.?Strategy then opts.Strategy;
|     type := class alg;
|     -- if Strategy is not given, run through all available hooks
|     if alg === null then scan(reverse store.HookPriority, alg -> (
|             result := runHook(store.HookAlgorithms#alg, key, alg, args, opts
|             if not instance(result, Nothing) then break result)) else
|     -- if Strategy is given, and it is among the known strategies, run only t
|     if store.HookAlgorithms#?alg  then runHook(store.HookAlgorithms#alg,  key
|     -- otherwise, if the class of alg is a known strategy, run only that hook
|     -- TODO: implement reverse lookup to find strategy installed under ancest
|     if store.HookAlgorithms#?type then runHook(store.HookAlgorithms#type, key
|     -- otherwise, give an error with the list of possible strategies
|     error("unrecognized Strategy => '", toString alg, "' for ", toString key,
|         "  available strategies are: ", demark_", " \\ toExternalString \ new
-------------------------------------------------------------------------------
guments.
Option)), select(args, i -> not instance(i,Option))))

     location of symbol
     ------------------
m2.  ../../../../../Macaulay2/m2/option.m2:37:8-37:9
     ../../../../../Macaulay2/m2/option.m2:37:3-37:7

) -> (

toString key); return );

++ { Strategy => alg });

hat hook
, alg,  args, opts) else

ors of type?
, type, args, opts) else

 newline,
 List from store.HookPriority))

See also
========

  * hooks -- list hooks attached to a key
  * addHook -- add a hook function to an object for later
    processing

Ways to use runHooks:
=====================

  * "runHooks(MutableHashTable,Thing,Thing)"
  * "runHooks(Sequence,Thing)"
  * "runHooks(Symbol,Thing)"

For the programmer
==================

The object runHooks, is a method function with options.

code -- display source code
***************************

Description
===========

Synopsis
========

  * Usage:
        code f
  * Inputs:
      * f, a function, or a command,
  * Outputs:
      * a net, the source code of the function or commandf
+---------------------------------------------------------------------------+
|i1 : code listUserSymbols                                                  |
|                                                                           |
|o1 = ../../../../../Macaulay2/m2/debugging.m2:198:28-198:64: --source code:|
|     listUserSymbols = Command ( type -> listSymbols userSymbols type )    |
+---------------------------------------------------------------------------+

Synopsis
========

  * Usage:
        code(f,X)
  * Inputs:
      * f, a function, or a keyword,
      * X, a type,
  * Outputs:
      * a net, the source code of method for applying f to an
        argument of type X
+-----------------------------------------------------------------------------+
|i2 : code(res,Ideal)                                                         |
|                                                                             |
|o2 = -- code for method: resolution(Ideal)                                   |
|     ../../../../../Macaulay2/m2/res.m2:282:37-282:78: --source code:        |
|     resolution Ideal  := ChainComplex => opts -> I -> resolution(comodule I,|
|-----------------------------------------------------------------------------|
|opts)                                                                        |
+-----------------------------------------------------------------------------+

Synopsis
========

  * Usage:
        code(f,X,Y)
  * Inputs:
      * f, a function, or a keyword,
      * X, a type,
      * Y, a type,
  * Outputs:
      * a net, the source code of method for applying f to
        arguments of type X and Y
+-----------------------------------------------------------------------------+
|i3 : code(symbol :, Ideal, Ideal)                                            |
|                                                                             |
|o3 = -- code for method: Ideal : Ideal                                       |
|     ../../../../../Macaulay2/packages/Saturation.m2:148:51-148:75: --source |
|     code:                                                                   |
|     Ideal  : Ideal                := Ideal  =>         (I, J) -> quotient(I,|
|-----------------------------------------------------------------------------|
|J)                                                                           |
+-----------------------------------------------------------------------------+

Synopsis
========

  * Usage:
        code(f,X,Y,Z)
  * Inputs:
      * f, a function, or a keyword,
      * X, a type,
      * Y, a type,
      * Z, a type,
  * Outputs:
      * a net, the source code of method for applying f to
        arguments of type X, Y, and Z

Synopsis
========

  * Usage:
        code(f,X,Y,Z,T)
  * Inputs:
      * f, a function, or a keyword,
      * X, a type,
      * Y, a type,
      * Z, a type,
      * T, a type,
  * Outputs:
      * a net, the source code of method for applying f to
        arguments of type X, Y, Z, and T

Synopsis
========

  * Usage:
        code {v,w,...}
  * Inputs:
      * {v,w,...}, a list,
  * Outputs:
      * a net, the source code of the functions or commandsv,w,....
        Such a list can be obtained, for example, with methods.
+-----------------------------------------------------------------------------+
|i4 : code methods use                                                        |
|                                                                             |
|o4 = -- code for method: use(Ring)                                           |
|     ../../../../../Macaulay2/m2/enginering.m2:384:12-389:7: --source code:  |
|     use Ring := R -> (                                                      |
|          if R.?ring then use R.ring;                            -- I'm not s|
|          generators R;                                                      |
|          if R.?generators and R.?generatorSymbols then scan(R.generatorSymbo|
|          if R.?use then R.use R;                                            |
|          R)                                                                 |
|     ------------------------------------------------------------------------|
|     -- code for method: use(Monoid)                                         |
|     ../../../../../Macaulay2/m2/monoids.m2:193:21-193:56: --source code:    |
|     use        Monoid := M ->(if M.?use     then M.use M; M)                |
|     ------------------------------------------------------------------------|
|     -- code for method: use(Package)                                        |
|     ../../../../../Macaulay2/m2/packages.m2:561:15-566:42: --source code:   |
|     use Package := pkg -> (                                                 |
|         scan(nonnull pkg.Options.PackageExports, needsPackage);             |
|         loadedPackages = prepend(pkg,            delete(pkg,            load|
|         dictionaryPath = prepend(pkg.Dictionary, delete(pkg.Dictionary, dict|
|         checkShadow();                                                      |
|         if pkg.?use then pkg.use pkg else pkg)                              |
|     ------------------------------------------------------------------------|
|     -- code for method: use(Thing)                                          |
|     compiled function identity:  source code not available                  |
|-----------------------------------------------------------------------------|
|ure what this is for.  Which rings have this key?                            |
|                                                                             |
|ls,R.generators,(sym,val) -> sym <- val);                                    |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|edPackages));                                                                |
|ionaryPath));                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * edit -- edit source code
  * methods -- list methods

Ways to use code:
=================

  * "code(Command)"
  * "code(Function)"
  * "code(List)"
  * "code(Pseudocode)"
  * "code(Sequence)"
  * "code(Symbol)"
  * "code(ZZ)"
  * code(FilePosition) (missing documentation)
  * "code(TestInput)" -- see tests, -- locate a package's tests

For the programmer
==================

The object code, is a method function with a single argument.

what a class is
***************

In Macaulay2 the behavior of a function depends heavily on the types of the
arguments it's presented with.  For example, the expression x+y means the sum
if x and y are integers, but it means the union if x and y are sets.  To
implement this in a clean fashion, we store the code for doing things with sets
in something called Set, and we store the code for doing things with
integers in something called ZZ.  We say that each integer is an
instance, of ZZ, and ZZ, is the
class, (or type) of each integer.  The function class,
provides the class of an object, and the function instance,
tells whether a given object is an instance of a given class, or a subclass of
it, and so on.

+------------------------+
|i1 : class 33           |
|                        |
|o1 = ZZ                 |
|                        |
|o1 : Ring               |
+------------------------+
|i2 : instance(33,ZZ)    |
|                        |
|o2 = true               |
+------------------------+
|i3 : instance(33,String)|
|                        |
|o3 = false              |
+------------------------+
The corresponding mathematical idea is that ZZ, is the set of all
integers.

The class of all classes or types is called Type.
+----------------------+
|i4 : instance(ZZ,Type)|
|                      |
|o4 = true             |
+----------------------+
|i5 : instance(33,Type)|
|                      |
|o5 = false            |
+----------------------+
The class of all objects in the system is Thing.
+-----------------------+
|i6 : instance(33,Thing)|
|                       |
|o6 = true              |
+-----------------------+
Everything has a class, and every class has a parent.  The
parent class represents a broader class of objects, and is used to contain code
that applies to the broader class.  For example, see ZZ, is a ring, and
every ring is also a type.
+--------------------+
|i7 : class ZZ       |
|                    |
|o7 = Ring           |
|                    |
|o7 : Type           |
+--------------------+
|i8 : parent class ZZ|
|                    |
|o8 = Type           |
|                    |
|o8 : Type           |
+--------------------+
Types are implemented as hash tables -- it's a versatile way of storing bits of
code that are needed in various situations; the keys for the hash table are
constructed in a certain way from the function and the types of its arguments
whose details the user doesn't need to know.

See also
========

  * uniform -- whether all elements of a list are the same
    class
  * Thing -- the class of all things
  * Nothing -- the empty class
  * Type -- the class of all types
  * MutableList -- the class of all mutable lists
  * MutableHashTable -- the class of all mutable hash
    tables
  * SelfInitializingType -- the class of all self
    initializing types

class -- class of an object
***************************

Synopsis
========

  * Usage:
        class x
  * Inputs:
      * x, a thing, any Macaulay2 object
  * Outputs:
      * a type, the class of x

Description
===========

Every object in Macaulay2 has a class, see what a class is,
for more details.
+-------------------+
|i1 : class {1,2,3} |
|                   |
|o1 = List          |
|                   |
|o1 : Type          |
+-------------------+
|i2 : R = QQ[a..d]  |
|                   |
|o2 = R             |
|                   |
|o2 : PolynomialRing|
+-------------------+
|i3 : class R       |
|                   |
|o3 = PolynomialRing|
|                   |
|o3 : Type          |
+-------------------+
Use strict equality === to test the exact class of an object.
+-------------------------------+
|i4 : class R === PolynomialRing|
|                               |
|o4 = true                      |
+-------------------------------+
|i5 : class R === Ring          |
|                               |
|o5 = false                     |
+-------------------------------+
However, each PolynomialRing is a Ring, by inheritance, so a more useful test
uses instance.
+---------------------+
|i6 : instance(R,Ring)|
|                     |
|o6 = true            |
+---------------------+

See also
========

  * instance -- whether something has a certain type

Ways to use class:
==================

  * "class(Thing)"

For the programmer
==================

The object class, is a compiled function.

parent -- parent type of an object
**********************************

Synopsis
========

  * Usage:
        X = parent x
  * Inputs:
      * x
  * Outputs:
      * X, the parent class of x

Description
===========

Methods for the instances of X which are not found in X itself are sought in P,
and its parent, and so on. Thus the mathematical notion of a set P and a subset
X can modeled in this way.

Things that don't have instances have the empty class, called Nothing,
as their parent.  The parent of Thing, is Thing,
itself (because every thing is a thing).

The entire structure of types and their parents can be displayed with
showStructure.

Ways to use parent:
===================

  * "parent(Thing)"
  * parent(HashTable) (missing documentation)

For the programmer
==================

The object parent, is a compiled function.

instance -- whether something has a certain type
************************************************

Description
===========

instance(x,X) -- tells whether x is an instance of the type X.

We say that x is an instance of X if X is the class of x, or a parent of the
class of x, or a grandparent, and so on.

See also
========

  * class -- class of an object
  * parent -- parent type of an object

Ways to use instance:
=====================

  * "instance(Thing,Type)"

For the programmer
==================

The object instance, is a compiled function.

ancestor(Type,Type) -- whether one type is an ancestor of another
*****************************************************************

Synopsis
========

  * Function: ancestor,
  * Usage:
        ancestor(x,y)
  * Inputs:
      * x, a type,
      * y, a type,
  * Outputs:
      * whether x is an ancestor of y

Description
===========

The ancestors of y are y, parent y, parent parent y, and so on.

If x is an ancestor of y, then we also say that y is a specialization of x.

+--------------------------------+
|i1 : parent String              |
|                                |
|o1 = Net                        |
|                                |
|o1 : Type                       |
+--------------------------------+
|i2 : parent parent String       |
|                                |
|o2 = Thing                      |
|                                |
|o2 : Type                       |
+--------------------------------+
|i3 : parent parent parent String|
|                                |
|o3 = Thing                      |
|                                |
|o3 : Type                       |
+--------------------------------+

See also
========

  * ancestors -- the ancestors of something

Ways to use this method:
========================

  * ancestor(Type,Type) -- whether one type
    is an ancestor of another

installing methods
******************

The method to be used for computing an expression such as -x depends on the
type of x.  For example, the method for negating a polynomial differs from the
method for negating an integer modulo 111.  Each method is a function of one
variable, and is stored in the class of x under a key that is referred to as
the name of the method. For some built-in methods the method name is a symbol,
but for methods created with method, the method name is the same
as the function used for calling it up.

Let's assume that X is the class of x.  The way to install a method for the
negation of an instance x of X is with a statement of the following form.
- X := x ->( ... )
Here ( ... ) represents the body of the function, consisting of suitable code
for the operation at hand.

The method installed by the code above is automatically inherited by subclasses
of X.  Here is a brief description of the way this works.  Suppose X is the
parent, of P.  When an expression -p is to be evaluated, where
the class of p is P, then the method for -P is applied, unless there isn't one,
in which case the method for -X is applied, and so on, all the way up the chain
of parents to the topmost ancestor of everything, which is called Thing.

As an extreme example of inheritance, code like
- Thing := x -> ...
will install a method for negating anything, which will take effect as a last
resort whenever a more specifically defined method isn't found.  It probably
isn't a good idea to install such a method, for usually all it can do is to
print an error message.

The user may introduce new methods as well as new method names.  So it is
important to understand how methods are installed and consulted.

Applying a method named C to a thing x whose class is X means that
(lookup(C,X)) x
is evaluated.  In other words, C is used as a key to obtain a function from X
(or its parent, grandparent, and so on), and the function is applied to x.  See
lookup.

Installing a method named C for the class X is done with code such as
C X := (x) -> ( ... )
where ( ... ) represents suitable code for the operation at hand.

The routine for making new methods is method.

See also
========

  * binary methods

binary methods
**************

The method for computing a sum x+y depends on the types of x and y. For
example, the method for adding an integer x and a polynomial y differs from the
method for adding two integers modulo 111.  Because both the type of x and the
type of y must enter into the selection of the method, we refer to these
methods as binary methods.  Each binary method is a function of two variables,
and is stored either in the class of x or in the class of y.

Let's assume that X is the class (or type) of x, and that Y is the class of y.
The way to install a method for the addition of an instance x of class X to an
instance y of class Y is with a statement of the form
X + Y := (x,y) -> ( ... )
where ( ... ) represents the body of the function, consisting of suitable code
for the operation at hand.

The method installed by the code above is automatically inherited by subclasses
of X and Y.  Here is a brief description of the way this works.  Suppose X is
the parent, of P and Y is the parent of Q.  When a sum p+q is
evaluated where the class of p is P and the class of q is Q, then the binary
method for P+Q is applied, unless there isn't one, in which case the binary
method for P+Y is applied, unless there isn't one, in which case the binary
method for X+Q is applied, unless there isn't one, in which case the binary
method for P+Q is applied.  In general this search for a binary method
continues all the way up the chain of parents to the topmost ancestor of
everything, which is called Thing.  (See also lookup.)

As an extreme example of inheritance, the code
Thing + Thing := (x,y) -> ( ... )
will install a binary method for adding any two things, which will take effect
as a last resort whenever more a specifically defined method isn't found.

The new, function also uses a ternary lookup table to find the
initialization function for the new thing, and should be thought of as a
ternary operator.  The initialization function for a new expression created by
new Z of x from y
is obtained as
lookup(NewMethod,Z,X,Y)
Here X is class x, and Y is class y.  The initialization function can be
installed with
new Z of X from Y := (z,y) -> ...
where z denotes the new hash table of class Z and parent X provided to the
routine by the system.

inheritance
***********

Each class has a parent class that can be used as a container for bits of code
that apply to a more general class of objects. In this section we show how this
mechanism works in detail.

We begin by creating a new type of basic list.
+------------------------------+
|i1 : X = new Type of BasicList|
|                              |
|o1 = X                        |
|                              |
|o1 : Type                     |
+------------------------------+
|i2 : parent X                 |
|                              |
|o2 = BasicList                |
|                              |
|o2 : Type                     |
+------------------------------+
The parent of X is BasicList, as desired, thus methods
applicable to basic lists will also apply also to instances of X.  One such
method is the method for creating a net from a basic list; here is its code:
+-----------------------------------------------------------+
|i3 : code(net,BasicList)                                   |
|                                                           |
|o3 = -- code for method: net(BasicList)                    |
|     /usr/local/share/Macaulay2/Core/nets.m2:168:17-172:10:|
|     --source code:                                        |
|     net BasicList := x -> horizontalJoin deepSplice (     |
|           net class x,                                    |
|           "{",                                            |
|           toSequence between(comma,apply(toList x,netn)), |
|           "}")                                            |
+-----------------------------------------------------------+
This code is run automatically to display an instance of X, so if we make one,
we'll be able to see what it is:
+---------------------------+
|i4 : x = new X from {2,3,4}|
|                           |
|o4 = X{2, 3, 4}            |
|                           |
|o4 : X                     |
+---------------------------+
Now let's imagine we wish to treat instances of X as vectors, and to negate one
by negating its entries.  As it happens, no method for this has been installed
for basic lists, so trying to negate x results in an error.
+------------------------------------------------------------------------+
|i5 : stopIfError = false;                                               |
+------------------------------------------------------------------------+
|i6 : - x                                                                |
|stdio:6:0:(3): error: no method for prefix operator - applied to object:|
|            X{2, 3, 4} (of class X)                                     |
+------------------------------------------------------------------------+
We install and test a new method as described in installing methods.
+----------------------------------+
|i7 : - X := t -> apply(t,i -> -i);|
+----------------------------------+
|i8 : - x                          |
|                                  |
|o8 = X{-2, -3, -4}                |
|                                  |
|o8 : X                            |
+----------------------------------+
This method will apply automatically to subclasses of X, as we see now.
+----------------------------+
|i9 : Y = new Type of X;     |
+----------------------------+
|i10 : y = new Y from {4,5,6}|
|                            |
|o10 = Y{4, 5, 6}            |
|                            |
|o10 : Y                     |
+----------------------------+
|i11 : - y                   |
|                            |
|o11 = Y{-4, -5, -6}         |
|                            |
|o11 : Y                     |
+----------------------------+
For binary methods, there is an apparent ambiguity in deciding exactly how
inheritance will work.  Let's illustrate by making a new subclass Z of X.
+----------------------------+
|i12 : Z = new Type of X;    |
+----------------------------+
|i13 : z = new Z from {7,8,9}|
|                            |
|o13 = Z{7, 8, 9}            |
|                            |
|o13 : Z                     |
+----------------------------+
Now let's install two methods, either of which might conceivably be applied to
evaluate the expression y+z, and see what happens.
+--------------------------------+
|i14 : Y + X := (a,b) -> "Y + X";|
+--------------------------------+
|i15 : X + Z := (a,b) -> "X + Z";|
+--------------------------------+
|i16 : y + z                     |
|                                |
|o16 = Y + X                     |
+--------------------------------+
The result is the string Y + X.  The reason is that after finding that no
method applies directly for adding an instance of Y to an instance of Z, the
search continues: Z is replaced by its parent X, and so on.  (After enough
unsuccessful iterations of this, the second type is reset to Z, the first type
is replaced by its parent, and the search continues.)

The same search order applies to method functions defined with method.

making new classes
******************

All new classes are made with the operator new. You may choose to
implement the instances of your new class either as basic lists or as hash
tables, or you may even base it on a subclass of BasicList, or
a subclass of HashTable, if you find a class that has some of
the methods you need already implemented.

As an example, we may wish to implement quaternions as lists of four real
numbers.  We know that lists already have a method for addition that treats
them as vectors, and we could use the same code for addition of quaternions.
+------------------------------+
|i1 : Qu = new Type of List    |
|                              |
|o1 = Qu                       |
|                              |
|o1 : Type                     |
+------------------------------+
|i2 : w = new Qu from {1,2,3,4}|
|                              |
|o2 = {1, 2, 3, 4}             |
|                              |
|o2 : Qu                       |
+------------------------------+
|i3 : w+w                      |
|                              |
|o3 = {2, 4, 6, 8}             |
|                              |
|o3 : Qu                       |
+------------------------------+
Now all we have to do is to install a method for multiplying quaternions.
+------------------------------------------------+
|i4 : Qu * Qu := (x,y) -> new Qu from {          |
|          x#0*y#0 - x#1*y#1 - x#2*y#2 - x#3*y#3,|
|          x#0*y#1 + x#1*y#0 + x#2*y#3 - x#3*y#2,|
|          x#0*y#2 + x#2*y#0 + x#3*y#1 - x#1*y#3,|
|          x#0*y#3 + x#3*y#0 + x#1*y#2 - x#2*y#1 |
|          };                                    |
+------------------------------------------------+
|i5 : w*w                                        |
|                                                |
|o5 = {-28, 4, 6, 8}                             |
|                                                |
|o5 : Qu                                         |
+------------------------------------------------+

new -- new objects and new types
********************************

Description
===========

In this reference section we discuss how to make new types of object and new
objects of those types.

installing a new method for new-of-from
=======================================

  * Usage:
        new AA of BB from C := (A,B,c) -> ...
  * Inputs:
      * AA, a hash table,
      * BB, a hash table,
      * C, a hash table,
      * (A,B,c) -> ..., a function of 3 arguments: AA will be an ancestor of A,
        BB will be an ancestor of B, and C will be an ancestor of the class of
        c. Alternatively, A will be a type of AA, B will be a type of BB, and c
        will be an instance of C.
  * Outputs:
      * the function is returned as the value of the expression
  * Consequences:
      * the function will be installed as the method for new AA of BB from C.
        It will be stored under the key (NewOfFromMethod,AA,BB,C) in the
        youngest of the hash tables AA, BB, and C.

In this example we install a creation method for new types of types from
functions.  The function is used to construct the method for converting
instances of the new type to nets for display.

+-----------------------------------------------------------------------------+
|i1 : new Type of BasicList from Function := (A,B,f) -> hashTable { net => f, |
|-----------------------------------------------------------------------------|
|html => f };                                                                 |
+-----------------------------------------------------------------------------+

The hash tables AA, BB, and C will normally be instances of Type.

new-of-from
===========

  * Usage:
        new A of B from c
  * Inputs:
      * A, a hash table,
      * B, a hash table,
      * c, an instance of C
  * Outputs:
      * the new object of class A and with parent B described above
  * Consequences:
      * the function previously installed as the method for new A of B from C
        will be called with arguments (A,B,c).
      * if no such method has been installed, then ancestors of A, B, and C,
        will be consulted, searching lexicographically for a method; see
        inheritance.
      * if no method is found by searching the ancestors, then the function
        (A,B,c) -> c will be used
      * the value returned by the function, (or c, if no method was found),
        will have its class set to A and its parent set to B; see
        newClass.

We use the creation method installed above to create a new type of list.

+----------------------------------+
|i2 : f = s -> "--list of type X--"|
|                                  |
|o2 = f                            |
|                                  |
|o2 : FunctionClosure              |
+----------------------------------+
|i3 : X = new Type of List from f  |
|                                  |
|o3 = X                            |
|                                  |
|o3 : Type                         |
+----------------------------------+
|i4 : class X                      |
|                                  |
|o4 = Type                         |
|                                  |
|o4 : Type                         |
+----------------------------------+
|i5 : parent X                     |
|                                  |
|o5 = List                         |
|                                  |
|o5 : Type                         |
+----------------------------------+
|i6 : peek X                       |
|                                  |
|o6 = Type of List{html => f}      |
|                  net => f        |
+----------------------------------+

Now we use new, to create a new list of type X from a list.  The
system knows how to convert lists to lists of type X, so no creation method
need be installed for new X from List.

+-------------------------------+
|i7 : x = new X from {1,3,11,12}|
|                               |
|o7 = --list of type X--        |
|                               |
|o7 : X                         |
+-------------------------------+
|i8 : class x                   |
|                               |
|o8 = X                         |
|                               |
|o8 : Type                      |
+-------------------------------+
|i9 : parent x                  |
|                               |
|o9 = Nothing                   |
|                               |
|o9 : Type                      |
+-------------------------------+
|i10 : peek x                   |
|                               |
|o10 = {1, 3, 11, 12}           |
+-------------------------------+

installing a new method for new-of
==================================

  * Usage:
        new AA of BB := (A,B) -> ...
  * Inputs:
      * AA, a hash table,
      * BB, a hash table,
      * (A,B) -> ..., a function of 2 arguments: AA will be an ancestor of A,
        and BB will be an ancestor of B. Alternatively, A will be a type of AA,
        and B will be a type of BB.
  * Outputs:
      * the function is returned as the value of the expression
  * Consequences:
      * the function will be installed as the method for new AA of BB.  It will
        be stored under the key (NewOfMethod,AA,BB) in the younger of the hash
        tables AA and BB.

This operation turns out to be needed infrequently, because there is no
from-clause to provide data for initializing the instance of A.

+-------------------------------------------------------------+
|i11 : new Type of BasicList := (type,array) -> (             |
|                    stderr << "--new " << type << " of "     |
|                           << array << " being made" << endl;|
|                    new MutableHashTable)                    |
|                                                             |
|o11 = FunctionClosure[stdio:11:25-14:41]                     |
|                                                             |
|o11 : FunctionClosure                                        |
+-------------------------------------------------------------+

new-of
======

  * Usage:
        new A of B
  * Inputs:
      * A, a hash table,
      * B, a hash table,
  * Outputs:
      * the new object of class A and parent B described above
  * Consequences:
      * the function previously installed as the method for new A of B will be
        called with arguments (A,B).
      * if no such method has been installed, then ancestors of A and B will be
        consulted, searching lexicographically for a method; see
        inheritance.
      * the value returned by the function will have its class set to A and its
        parent set to B; see newClass.
      * if no method is found by searching the ancestors, then a new empty
        instance of A with parent B will be created

We illustrate this operation by making a new type of basic list, and then by
making a list of that type.

+----------------------------------+
|i12 : M = new Type of BasicList   |
|--new Type of BasicList being made|
|                                  |
|o12 = M                           |
|                                  |
|o12 : Type                        |
+----------------------------------+
|i13 : m = new M from {3,4,5}      |
|                                  |
|o13 = M{3, 4, 5}                  |
|                                  |
|o13 : M                           |
+----------------------------------+
|i14 : class m                     |
|                                  |
|o14 = M                           |
|                                  |
|o14 : Type                        |
+----------------------------------+
|i15 : m#1                         |
|                                  |
|o15 = 4                           |
+----------------------------------+

Now let's define a method for reversing the elements of a list of class M,
using the unary operator -.

+----------------------+
|i16 : - M := reverse  |
|                      |
|o16 = reverse         |
|                      |
|o16 : CompiledFunction|
+----------------------+
|i17 : - m             |
|                      |
|o17 = M{5, 4, 3}      |
|                      |
|o17 : M               |
+----------------------+

installing a new method for new-from
====================================

  * Usage:
        new AA from C := (A,c) -> ...
  * Inputs:
      * AA, a hash table,
      * C, a type,
      * (A,c) -> ..., a function of 2 arguments: AA will be an ancestor of A,
        and C will be an ancestor of the class of c. Alternatively, A will be a
        type of AA and c will be an instance of C.
  * Outputs:
      * the function is returned as the value of the expression
  * Consequences:
      * the function will be installed as the method for new AA from C.  It
        will be stored under the key (NewFromMethod,AA,C) in the younger of the
        hash tables AA and C.

Let's use the class M defined above, and introduce a method for creating lists
of class M from integers.  Then we use it in the subsection below.

+----------------------------------------+
|i18 : new M from ZZ := (M',i) -> 0 .. i |
|                                        |
|o18 = FunctionClosure[stdio:21:17-21:33]|
|                                        |
|o18 : FunctionClosure                   |
+----------------------------------------+

new-from
========

  * Usage:
        new A from c
  * Inputs:
      * A, a hash table,
      * c, an instance of C
  * Outputs:
      * the new object of class A initialized from c described above
  * Consequences:
      * the function previously installed as the method for new A from C will
        be called with arguments (A,c).
      * if no such method has been installed, then ancestors of A and C, will
        be consulted, searching lexicographically for a method; see
        inheritance.
      * if no method is found by searching the ancestors, then the function
        (A,c) -> c will be used
      * the value returned by the function, (or c, if no method was found),
        will have its class set to A and its parent retained; see
        newClass,

We use the new-from method for new M from ZZ installed above.

+-----------------------------------------------------+
|i19 : n = new M from 13                              |
|                                                     |
|o19 = M{0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13}|
|                                                     |
|o19 : M                                              |
+-----------------------------------------------------+
|i20 : - n                                            |
|                                                     |
|o20 = M{13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0}|
|                                                     |
|o20 : M                                              |
+-----------------------------------------------------+

installing a new method for new
===============================

  * Usage:
        new AA := (A) -> ...
  * Inputs:
      * AA, a hash table,
      * (A) -> ..., a function of 1 argument: AA will be an ancestor of A.
        Alternatively, A will be a type of AA.
  * Outputs:
      * the function is returned as the value of the expression
  * Consequences:
      * the function will be installed as the method for new AA.  It will be
        stored under the key NewMethod in the hash table AA.

We use the class M introduced above, and install a method for new M, and we use
it in the next subsection.

+---------------------------------------+
|i21 : new M := (M') -> {"a","b","c"}   |
|                                       |
|o21 = FunctionClosure[stdio:24:9-24:30]|
|                                       |
|o21 : FunctionClosure                  |
+---------------------------------------+

new
===

  * Usage:
        new A
  * Inputs:
      * A, a hash table,
  * Outputs:
      * the new object of class A described above
  * Consequences:
      * the function previously installed as the method for new A will be
        called with argument A.
      * if no such method has been installed, then ancestors of A will be
        consulted, searching for a method; see inheritance.
      * the value returned by the function will have its class set to A; see
        newClass,
      * if no method is found by searching the ancestors, then a new empty
        instance of A will be created, if possible

We use the method for new M installed above.

+----------------+
|i22 : new M     |
|                |
|o22 = M{a, b, c}|
|                |
|o22 : M         |
+----------------+

For the programmer
==================

The object new, is a keyword.

newClass -- set the class and parent of an object
*************************************************

Description
===========

setting the class and parent
============================

  * Usage:
        newClass(A,B,x)
  * Inputs:
      * A, a hash table,
      * B, a hash table,
      * x
  * Outputs:
      * a copy (possibly) of x with A as class and B as parent

setting the class
=================

  * Usage:
        newClass(A,x)
  * Inputs:
      * A, a hash table,
      * x
  * Outputs:
      * a copy (possibly) of x with A as the new class

common remarks
==============

If x is a basic list or sequence, then BasicList, should be an
ancestor of A and B should be Nothing. If x is a hash table,
then HashTable, should be an ancestor of A.

If the class (and parent) of x are already equal to A (and B, respectively),
then copying of the elements of x is not required, and is not done.

If x is mutable, and instances of class A are also mutable, then copying of the
elements of x is not required, and is not done.

If x is not a hash table, basic list, or sequence, then its class will be set
to A internally, essentially by wrapping it in a special kind of object
designed solely to indicate the new class.  The new class A must be a
specialization of the class of x. The parent cannot be reset this way. Not all
of the internal code of Macaulay2 is ready to recognize such wrapped objects,
which are part of a new feature, except for the code that handles functions.

+----------------------------------------------+
|i1 : t = 1..4                                 |
|                                              |
|o1 = (1, 2, 3, 4)                             |
|                                              |
|o1 : Sequence                                 |
+----------------------------------------------+
|i2 : newClass(Array,t)                        |
|                                              |
|o2 = [1, 2, 3, 4]                             |
|                                              |
|o2 : Array                                    |
+----------------------------------------------+
|i3 : x = new HashTable from { a => 1, b => 2 }|
|                                              |
|o3 = HashTable{a => 1}                        |
|               b => 2                         |
|                                              |
|o3 : HashTable                                |
+----------------------------------------------+
|i4 : z = newClass(ImmutableType,Vector,x)     |
|                                              |
|o4 = ImmutableType{a => 1}                    |
|                   b => 2                     |
|                                              |
|o4 : ImmutableType                            |
+----------------------------------------------+
|i5 : parent z                                 |
|                                              |
|o5 = Vector                                   |
|                                              |
|o5 : Type                                     |
+----------------------------------------------+

The difference between new A of B from x and newClass(A,B,x) is that the
methods installed for new, are not used.

+-----------------------------------------------------------------------+
|i6 : new Thing of Thing from Thing := (A,B,c) -> (                     |
|            << "-- new " << A << " of " << B                           |
|            << " from " << toString c << endl;                         |
|            c);                                                        |
+-----------------------------------------------------------------------+
|i7 : new ImmutableType of Vector from x                                |
|-- new ImmutableType of Vector from new HashTable from {a => 1, b => 2}|
|                                                                       |
|o7 = ImmutableType{a => 1}                                             |
|                   b => 2                                              |
|                                                                       |
|o7 : ImmutableType                                                     |
+-----------------------------------------------------------------------+
|i8 : newClass(ImmutableType,Vector,x)                                  |
|                                                                       |
|o8 = ImmutableType{a => 1}                                             |
|                   b => 2                                              |
|                                                                       |
|o8 : ImmutableType                                                     |
+-----------------------------------------------------------------------+

See also
========

  * new -- new objects and new types
  * copy -- copy an object
  * toList -- create a list

For the programmer
==================

The object newClass, is a compiled function.

printing and formatting for new classes
***************************************

After making a new type, it's desirable to install methods for displaying the
instances of the new type in various formats.
+-------------------------------+
|i1 : Qu = new Type of List     |
|                               |
|o1 = Qu                        |
|                               |
|o1 : Type                      |
+-------------------------------+
|i2 : w = new Qu from {1,-2,0,4}|
|                               |
|o2 = {1, -2, 0, 4}             |
|                               |
|o2 : Qu                        |
+-------------------------------+
For example, it's desirable to display the quaternion above so it looks like a
quaternion.  One way to achieve this is to install first a method for creating
an Expression, from a quaternion, since there are methods
already installed for converting expressions to common forms of output, such as
to nets, which are used most commonly.
+------------------------------------------------+
|i3 : expression Qu := z -> (                    |
|               expression z#0 +                 |
|               expression z#1 * expression "I" +|
|               expression z#2 * expression "J" +|
|               expression z#3 * expression "K");|
+------------------------------------------------+
|i4 : net Qu := z -> net expression z;           |
+------------------------------------------------+
|i5 : toString Qu := z -> toString expression z; |
+------------------------------------------------+
|i6 : tex Qu := z -> tex expression z;           |
+------------------------------------------------+
|i7 : html Qu := z -> html expression z;         |
+------------------------------------------------+
|i8 : w                                          |
|                                                |
|o8 = 1 - 2*I + 4*K                              |
|                                                |
|o8 : Qu                                         |
+------------------------------------------------+
|i9 : toString w                                 |
|                                                |
|o9 = 1-2*I+4*K                                  |
+------------------------------------------------+
|i10 : tex w                                     |
|                                                |
|o10 = $1-2\,\texttt{I}+4\,\texttt{K}$           |
+------------------------------------------------+
|i11 : html w                                    |
|                                                |
|o11 = $1-2\,\texttt{I}+4\,\texttt{K}$           |
+------------------------------------------------+
Of course, now that we've decided that there should be certain quaternions
called I, J, and K, perhaps we should install them, too.
+-------------------------------+
|i12 : I = new Qu from {0,1,0,0}|
|                               |
|o12 = I                        |
|                               |
|o12 : Qu                       |
+-------------------------------+
|i13 : J = new Qu from {0,0,1,0}|
|                               |
|o13 = J                        |
|                               |
|o13 : Qu                       |
+-------------------------------+
|i14 : K = new Qu from {0,0,0,1}|
|                               |
|o14 = K                        |
|                               |
|o14 : Qu                       |
+-------------------------------+
|i15 : 2*I + 5*J                |
|                               |
|o15 = 2*I + 5*J                |
|                               |
|o15 : Qu                       |
+-------------------------------+
|i16 : peek oo                  |
|                               |
|o16 = {0, 2, 5, 0}             |
+-------------------------------+

making a new method function
****************************

The function method, can be used to make new functions which
execute different bits of code depending on the types of the arguments
presented.  Our system depends heavily on such functions.
+-------------------+
|i1 : f = method()  |
|                   |
|o1 = f             |
|                   |
|o1 : MethodFunction|
+-------------------+
We can install a method to be used when f is applied to a string as follows.
+--------------------------+
|i2 : f String := s -> s|s;|
+--------------------------+
|i3 : f ".abcd."           |
|                          |
|o3 = .abcd..abcd.         |
+--------------------------+
We can check for the types of up to three arguments, too.
+------------------------------------------------+
|i4 : f(ZZ,String) := (n,s) -> concatenate (n:s);|
+------------------------------------------------+
|i5 : f(5,".abcd.")                              |
|                                                |
|o5 = .abcd..abcd..abcd..abcd..abcd.             |
+------------------------------------------------+

method -- make a new method function
************************************

Synopsis
========

  * Usage:
        f = method()
  * Optional inputs,:
      * TypicalValue => a type, default value Thing, the type of
        the value returned by f, typically.  This information is used only to
        build documentation automatically, and is stored in the hash table
        typicalValues.
      * Options => a list, default value null, a list of options J
        => v, where J is the name of an optional argument for f, and v is its
        default value. The list of options could be also replaced by the
        corresponding OptionTable. Specifying true here
        indicates that option handling is done by the individual methods, while
        still allowing dispatching to methods based on types of arguments to be
        done. The individual methods may have various sets of acceptable option
        names, possibly empty. See making new functions with optional arguments.
      * Binary => a Boolean value, default value false, whether
        the method is to be binary: for three arguments or more the result will
        be computed by calling binary methods installed for f with two
        arguments at a time.
      * Dispatch => ..., default value {Thing, Thing, Thing, Thing}, the method
        for getting a list of types from the parameters; the value of this
        option should be Thing, or Type, to indicate
        that a sequence should be regarded as a single argument, or, if the
        elements of a sequence are to be regarded as separate parameters, a
        list whose elements are Thing, or Type.
        Parameters corresponding to Thing, or to a position beyond
        the end of the list are dispatched according to their class,
        whereas parameters corresponding to Type, are
        expected to be types (actually, hash tables) and are used directly in
        the search for methods; see inheritance.
  * Outputs:
      * f, a new method function, a method function, a
        method function with a single argument, an
        associative binary method function, or a
        method function with options,

Description
===========

The code above creates a method function that takes up to four arguments,
looking up the appropriate method according to the classes of the arguments,
with inheritance.  To install a method for two arguments, (x,y), of classes X
and Y, use code like this:
     f(X,Y) := (x,y) -> ...
where '...' represents the body of the function you wish to install. The syntax
for one or three arguments is analogous.  See _colon_=, for
details.
+-----------------------------------------------------------------------------+
|i1 : f = method()                                                            |
|                                                                             |
|o1 = f                                                                       |
|                                                                             |
|o1 : MethodFunction                                                          |
+-----------------------------------------------------------------------------+
|i2 : f ZZ := x -> -x;                                                        |
+-----------------------------------------------------------------------------+
|i3 : f(ZZ,String) := (n,s) -> concatenate(n:s);                              |
+-----------------------------------------------------------------------------+
|i4 : f(String,ZZ,String) := (s,n,t) -> concatenate(s," : ",toString n," :    |
|-----------------------------------------------------------------------------|
|",t);                                                                        |
+-----------------------------------------------------------------------------+
|i5 : f 44                                                                    |
|                                                                             |
|o5 = -44                                                                     |
+-----------------------------------------------------------------------------+
|i6 : f(5,"abcd ")                                                            |
|                                                                             |
|o6 = abcd abcd abcd abcd abcd                                                |
+-----------------------------------------------------------------------------+
|i7 : f("foo",88,"bar")                                                       |
|                                                                             |
|o7 = foo : 88 : bar                                                          |
+-----------------------------------------------------------------------------+

In the following example we install a asymmetric method to illustrate the
left-associative order of evaluation for a binary method function.

+-----------------------------------------------------+
|i8 : p = method(Binary => true, TypicalValue => List)|
|                                                     |
|o8 = p                                               |
|                                                     |
|o8 : MethodFunctionBinary                            |
+-----------------------------------------------------+
|i9 : p(ZZ,ZZ) := p(List,ZZ) := (i,j) -> {i,j}        |
|                                                     |
|o9 = FunctionClosure[stdio:9:26-9:40]                |
|                                                     |
|o9 : FunctionClosure                                 |
+-----------------------------------------------------+
|i10 : p(1,2)                                         |
|                                                     |
|o10 = {1, 2}                                         |
|                                                     |
|o10 : List                                           |
+-----------------------------------------------------+
|i11 : p(1,2,3,4,5,6)                                 |
|                                                     |
|o11 = {{{{{1, 2}, 3}, 4}, 5}, 6}                     |
|                                                     |
|o11 : List                                           |
+-----------------------------------------------------+
By default, at most four arguments (in a sequence) can be handled by a method
function, and the types have to be considered separately when installing
methods. In this example, we define a method function that treats a sequence as
a single argument, and we install a method for handling such arguments.
+------------------------------------+
|i12 : g = method(Dispatch => Thing);|
+------------------------------------+
|i13 : g ZZ := i -> -i;              |
+------------------------------------+
|i14 : g Sequence := S -> reverse S; |
+------------------------------------+
|i15 : g 44                          |
|                                    |
|o15 = -44                           |
+------------------------------------+
|i16 : g(3,4,5,6)                    |
|                                    |
|o16 = (6, 5, 4, 3)                  |
|                                    |
|o16 : Sequence                      |
+------------------------------------+
Here we define a method whose first argument is to be a type.  It will convert
its second argument to that type.
+------------------------------------+
|i17 : h = method(Dispatch => {Type})|
|                                    |
|o17 = h                             |
|                                    |
|o17 : MethodFunction                |
+------------------------------------+
|i18 : h(QQ,ZZ) := (QQ,n) -> n/1;    |
+------------------------------------+
|i19 : h(RR,ZZ) := (RR,n) -> n + 0.; |
+------------------------------------+
|i20 : h(ZZ,ZZ) := (ZZ,n) -> n;      |
+------------------------------------+
|i21 : h(ZZ,14)                      |
|                                    |
|o21 = 14                            |
+------------------------------------+
|i22 : h(QQ,14)                      |
|                                    |
|o22 = 14                            |
|                                    |
|o22 : QQ                            |
+------------------------------------+
|i23 : h(RR,14)                      |
|                                    |
|o23 = 14                            |
|                                    |
|o23 : RR (of precision 53)          |
+------------------------------------+

In the next example we make a linear function of a single real variable whose
coefficients are provided as optional arguments named Slope and Intercept, with
default value 1.

+---------------------------------------------------------+
|i24 : r = method(Options => {Slope => 1, Intercept => 1})|
|                                                         |
|o24 = r                                                  |
|                                                         |
|o24 : MethodFunctionWithOptions                          |
+---------------------------------------------------------+

The methods installed for this method function should be written in the form
opts -> args -> (...).  The argument opts will be assigned a hash table of type
OptionTable, containing the optional argument names and
their current values.  For example, in the body of the function, the current
value for the argument named b can be recovered with opts#b, or with opts.b, in
case b is known to be a global symbol.  Be careful not to change the value of
b, or the code will stop working; it would be a good idea to protect it.

+-------------------------------------------------+
|i25 : r RR := o -> x -> o.Slope * x + o.Intercept|
|                                                 |
|o25 = FunctionClosure[stdio:25:8-25:43]          |
|                                                 |
|o25 : FunctionClosure                            |
+-------------------------------------------------+
|i26 : r(5.)                                      |
|                                                 |
|o26 = 6                                          |
|                                                 |
|o26 : RR (of precision 53)                       |
+-------------------------------------------------+
|i27 : r(5.,Slope=>100)                           |
|                                                 |
|o27 = 501                                        |
|                                                 |
|o27 : RR (of precision 53)                       |
+-------------------------------------------------+

The default option table, for r can be recovered with the
function options.  The options given to method,
can be recovered with methodOptions.

+-----------------------------------------------------------+
|i28 : options r                                            |
|                                                           |
|o28 = OptionTable{Intercept => 1}                          |
|                  Slope => 1                               |
|                                                           |
|o28 : OptionTable                                          |
+-----------------------------------------------------------+
|i29 : methodOptions r                                      |
|                                                           |
|o29 = OptionTable{Binary => false                         }|
|                  Dispatch => {Thing, Thing, Thing, Thing} |
|                  Options => {Slope => 1, Intercept => 1}  |
|                  TypicalValue => Thing                    |
|                                                           |
|o29 : OptionTable                                          |
+-----------------------------------------------------------+

In the next example we define a method function that leaves option processing
to the individual methods.

+---------------------------------------------------------------------------+
|i30 : s = method(Options => true)                                          |
|                                                                           |
|o30 = s                                                                    |
|                                                                           |
|o30 : MethodFunctionWithOptions                                            |
+---------------------------------------------------------------------------+
|i31 : s ZZ := { Slope => 17 } >> o -> x -> o.Slope * x                     |
|                                                                           |
|o31 = FunctionClosure[/usr/local/share/Macaulay2/Core/option.m2:15:14-18:8]|
|                                                                           |
|o31 : FunctionClosure                                                      |
+---------------------------------------------------------------------------+
|i32 : s RR := { Intercept => 11 } >> o -> x -> x + o.Intercept             |
|                                                                           |
|o32 = FunctionClosure[/usr/local/share/Macaulay2/Core/option.m2:15:14-18:8]|
|                                                                           |
|o32 : FunctionClosure                                                      |
+---------------------------------------------------------------------------+
|i33 : s 100                                                                |
|                                                                           |
|o33 = 1700                                                                 |
+---------------------------------------------------------------------------+
|i34 : s 1000.                                                              |
|                                                                           |
|o34 = 1011                                                                 |
|                                                                           |
|o34 : RR (of precision 53)                                                 |
+---------------------------------------------------------------------------+
|i35 : options s                                                            |
+---------------------------------------------------------------------------+
|i36 : options(s,ZZ)                                                        |
|                                                                           |
|o36 = OptionTable{Slope => 17}                                             |
|                                                                           |
|o36 : OptionTable                                                          |
+---------------------------------------------------------------------------+
|i37 : options(s,RR)                                                        |
|                                                                           |
|o37 = OptionTable{Intercept => 11}                                         |
|                                                                           |
|o37 : OptionTable                                                          |
+---------------------------------------------------------------------------+

For now, one installs a method function for s with no non-optional arguments
using installMethod,:

+---------------------------------------------------------------------------+
|i38 : installMethod(s,{ Slope => 1234 } >> o -> () -> o.Slope)             |
|                                                                           |
|o38 = FunctionClosure[/usr/local/share/Macaulay2/Core/option.m2:15:14-18:8]|
|                                                                           |
|o38 : FunctionClosure                                                      |
+---------------------------------------------------------------------------+
|i39 : s()                                                                  |
|                                                                           |
|o39 = 1234                                                                 |
+---------------------------------------------------------------------------+
|i40 : s(Slope => 4)                                                        |
|                                                                           |
|o40 = 4                                                                    |
+---------------------------------------------------------------------------+

For the programmer
==================

The object method, is a function closure.

:Types of method functions

specifying typical values
*************************

For the purpose of constructing good documentation automatically, it is useful
to specify the type of value typically returned by a function or method.  For
example, the function isModule, returns a boolean value, and
this is specified when creating the method function with the option
TypicalValue, as follows.
isModule = method(TypicalValue => Boolean)

Other functions, such as prune, return values of various types,
depending on the type of the arguments provided.  To install a function f as
the handler for prune applied to a matrix, we would normally use the following
statement.
prune Matrix := f
To specify that the value typically returned is a matrix (of class Matrix), we
replace f by Matrix => f, as follows.
prune Matrix := Matrix => f
Here is the way our code looks.
+-----------------------------------------------------------------------------+
|i1 : code(prune, Matrix)                                                     |
|                                                                             |
|o1 = -- code for method: prune(Matrix)                                       |
|     ../../../../../Macaulay2/m2/modules2.                                   |
|     minimalPresentation(Matrix) := prune(                                   |
|          M := source m;                                                     |
|          if not M.cache.?pruningMap then                                    |
|          N := target m;                                                     |
|          if not N.cache.?pruningMap then                                    |
|          m)                                                                 |
|-----------------------------------------------------------------------------|
|m2:204:58-209:7: --source code:                                              |
|Matrix) := Matrix => opts -> (m) -> (                                        |
|                                                                             |
|m = m * (minimalPresentation M).cache.pruningMap;                            |
|                                                                             |
|m = (minimalPresentation N).cache.pruningMap^-1 * m;                         |
+-----------------------------------------------------------------------------+
The information is stored in the hash table typicalValues,
and can be recovered like this.
+---------------------------------+
|i2 : typicalValues#(prune,Matrix)|
|                                 |
|o2 = Matrix                      |
|                                 |
|o2 : Type                        |
+---------------------------------+

Warning: don't imagine that a definition of the form
f = t -> (...)
can be replaced with a declaration of the following form.
f = X => t -> (...)
The difference here is that here we are using simple assignment, rather than
installing a method.  To document the return type is X in this case, make an
entry in typicalValues directly.
f = t -> (...)
typicalValues#f = X

MethodFunction -- a type of method function
*******************************************

Description
===========

Functions of this type are created by method.

Protected objects of class MethodFunction:
==========================================

  * abs -- absolute value function
  * accumulate -- apply a binary operator repeatedly
  * acos -- arccosine
  * acosh -- inverse hyperbolic cosine
  * acot -- compute the inverse cotangent
  * acoth -- compute the hyperbolic arctangent of a number
  * addCone (Polyhedra) -- adds cones to a Fan
  * addPolyhedron (Polyhedra) -- adds Polyhedra to a
    PolyhedralComplex
  * "adjoint'" -- see adjoint, -- the tensor-Hom adjunction maps
  * affineHull (Polyhedra) -- computes the affine hull of a
    polyhedron
  * affineImage (Polyhedra) -- computes the affine image of
    a cone or polyhedron
  * affinePreimage (Polyhedra) -- computes the affine
    preimage of a cone or polyhedron
  * agm -- arithmetic-geometric mean
  * all -- whether all elements satisfy a specified condition
  * ambDim (Polyhedra) -- ambient dimension of a Polyhedron, Cone
    or Fan
  * ambient -- ambient free module of a subquotient, or ambient
    ring
  * antipode -- antipode for skew commuting polynomial rings
  * apropos -- symbols matching a pattern
  * areCompatible (Polyhedra) -- checks if the
    intersection of two cones/polyhedra is a face of each
  * arXiv (SimpleDoc) -- link to an arXiv article
  * asin -- arcsine
  * asinh -- inverse hyperbolic sine
  * assert -- check whether something is true, raise an error if
    not
  * atan -- compute the arctangent of a number
  * atan2 -- compute an angle of a certain triangle
  * atanh -- compute the hyperbolic arctangent of a number
  * autoload -- arrange for a function to be loaded
    automatically
  * barycentricTriangulation (Polyhedra), --
    computes a triangulation of a polytope
  * baseName -- the base name of a generator
  * baseRing -- produce the ring from which a ring was formed
  * BesselJ -- Bessel function of the first kind
  * BesselY -- Bessel function of the second kind
  * Beta -- Beta function
  * between -- insert something between elements of a list
  * binomial -- binomial coefficient
  * bipyramid (Polyhedra) -- computes the bipyramid over a
    polyhedron
  * "borel" -- see borel(Matrix), -- make a Borel
    fixed submodule
  * ccRefinement (Polyhedra) -- computes the coarsest
    common refinement of a set of rays
  * ceiling -- ceiling function
  * cellDecompose (Polyhedra) -- Deprecated variant of
    {\tt regularSubdivision}
  * changeBase -- change integer base
  * char -- computes the characteristic of the ring or field
  * chi
  * clean -- Set to zero elements that are approximately zero
  * coefficient -- coefficient of a monomial
  * coefficientRing -- get the coefficient ring
  * coimage -- coimage of a map
  * cokernel -- cokernel of a map of modules, graded modules,
    or chaincomplexes
  * columnAdd -- add a multiple of one column to another
  * columnMult -- multiply a column by a ring element
  * columnPermute -- permute some columns
  * columnRankProfile -- find the column rank profile
    of a mutable matrix
  * columnSwap -- interchange columns
  * commonFace (Polyhedra) -- checks if the intersection is a
    face of both Cones or Polyhedra, or of cones with fans
  * commonRing -- find smallest containing ring
  * comodule -- submodule to quotient module
  * compareExchange -- compares and possibly exchanges
    the value of an atomic integer
  * "complement" -- see complement(Matrix), --
    find the minimal generators for cokernel of a matrix (low level form)
  * complete
  * components -- list the components of a direct sum
  * compositions -- list the compositions of an integer
  * compress -- extract nonzero columns from a matrix
  * conductor (IntegralClosure) -- the conductor of a finite
    ring map
  * cone -- mapping cone or polyhedral cone
  * coneFromHData (Polyhedra) -- Constructing a polyhedral
    cone as intersection of halfspaces.
  * coneFromVData (Polyhedra) -- computes the positive
    hull of rays, cones, and the cone over a polyhedron
  * cones (Polyhedra) -- computes all cones of a fan of a certain
    dimension
  * conjugate -- complex conjugate
  * contains (Polyhedra) -- checks if the first argument
    contains the second argument
  * content -- the content of a polynomial
  * contract -- contract one matrix by another
  * "contract'" -- see contract'(Matrix,Matrix),
    -- contract a matrix by a matrix, the dual
    notion
  * convexHull (Polyhedra) -- computing the convex hull of
    points, rays and polyhedra
  * cos -- compute the cosine
  * cosh -- compute the hyperbolic cosine
  * cot -- cotangent
  * coth -- hyperbolic cotangent
  * cover -- get the covering free module
  * "coverMap" -- see coverMap(Module), -- the
    surjective map from a free module to a module corresponding to the
    generators
  * crossPolytope (Polyhedra) -- computes the
    d-dimensional crosspolytope with diameter 2s
  * csc -- cosecant
  * csch -- hyperbolic cosecant
  * cyclicPolytope (Polyhedra) -- computes the d
    dimensional cyclic polytope with n vertices
  * debug -- open the private dictionary of a package
  * default -- default member of a family
  * degree
  * degreeGroup (missing documentation)
  * degreeLength -- the length of the degree vector
  * degrees -- degrees of generators
  * "degreesMonoid" -- see degreesRing, -- the ring or
    monoid of degrees
  * degreesRing -- the ring or monoid of degrees
  * delete -- delete some elements of a list
  * denominator -- denominator of a fraction
  * depth -- depth of a net
  * diagonalMatrix -- make a diagonal matrix
  * diameter -- diameter of an interval
  * dictionary -- determine the dictionary to which a symbol
    belongs
  * diff -- differentiate or take difference
  * "diff'" -- see diff'(Matrix,Matrix), --
    differentiate a matrix by a matrix, the dual notion
  * Digamma -- Digamma function
  * dim -- compute the Krull dimension
  * directProduct (Polyhedra) -- computes the direct
    product of two convex objects
  * dismiss -- dismiss a package
  * divideByVariable -- divide all columns by a (power
    of a) variable
  * doc (SimpleDoc) -- a simple documentation function
  * dualCone (Polyhedra) --  computes the dual Cone
  * dualFaceRepresentationMap (missing documentation)
  * "eagonNorthcott" -- see eagonNorthcott(Matrix),
    -- Eagon-Northcott complex of a matrix of
    linear forms
  * effCone (missing documentation)
  * effGenerators (missing documentation)
  * ehrhart (Polyhedra) -- calculates the Ehrhart polynomial of
    a polytope
  * eint -- exponential integral
  * elements -- list of elements
  * eliminate (Elimination)
  * emptyPolyhedron (Polyhedra) -- generates the empty
    polyhedron in n-space
  * endPackage -- end a new package
  * entries -- lists the entries of a matrix
  * erf -- error function
  * erfc -- complementary error function
  * euler (Varieties) -- Euler characteristic
  * eulers (Varieties) -- list the sectional Euler
    characteristics
  * exchange -- exchange the value of an atomic integer
  * exp -- exponential function
  * expectedReesIdeal (ReesAlgebra) -- symmetric
    algebra ideal plus jacobian dual
  * expm1 -- exponential minus 1
  * exponents -- the exponents of a polynomial
  * exportFrom -- export symbols from a package's private
    dictionary
  * faceFan (Polyhedra) --  computes the fan generated by the
    cones over the faces
  * faces (Polyhedra) -- computes all faces of a certain
    codimension of a Cone or Polyhedron
  * facesAsCones (Polyhedra) -- Returns the faces of a cone
    as actual cones.
  * facesAsPolyhedra (Polyhedra) -- Returns the faces
    of a polyhedron as actual polyhedra.
  * facets (Polyhedra) -- Giving the facet inequalities of a cone
    or polyhedron.
  * fan (Polyhedra) -- generates a Fan
  * fanFromGfan (Polyhedra) -- Construct a fan from output
    data of {\tt Gfan}
  * Fano -- Fano scheme
  * "findSynonyms" -- see findSynonyms(Symbol),
    -- find synonyms of symbols
  * fittingIdeal -- Fitting ideal of a module
  * flip -- isomorphism map of commutativity of tensor product
  * floor -- floor function
  * fold -- apply a binary operator repeatedly
  * formation -- recover the methods used to make a module
  * frac -- construct a fraction field
  * fraction
  * fromDividedPowers (InverseSystems) -- Translates
    from divided power monomial basis to ordinary monomial basis
  * fVector (Polyhedra) -- computes the f-vector of a Cone,
    Polyhedron, Fan or PolyhedralComplex
  * Gamma -- Gamma function
  * gbRemove -- remove Gröbner basis
  * gbSnapshot -- the Gröbner basis matrix as so far
    computed
  * gcdCoefficients -- gcd with coefficients
  * genera (Varieties) -- list of the successive linear sectional
    arithmetic genera
  * generateAssertions -- generate assert statements
    from experimental input
  * generator -- provide a single generator
  * genericMatrix -- make a generic matrix of variables
  * genericSkewMatrix -- make a generic skew
    symmetric matrix of variables
  * genericSymmetricMatrix -- make a generic
    symmetric matrix
  * genus (Varieties) -- arithmetic genus
  * getChangeMatrix -- get the change of basis matrix
  * getWWW -- get a web page
  * gramm (missing documentation)
  * halfspaces (Polyhedra) -- computes the defining
    half-spaces of a Cone or a Polyhedron
  * headlines -- display a table of documentation headlines
  * heft -- heft vector of ring or monoid
  * height -- height of a net
  * hilbertFunction -- the Hilbert function
  * hirzebruch (Polyhedra) -- computes the fan of the r-th
    Hirzebruch surface
  * homogenize -- homogenize with respect to a variable
  * homomorphism -- get the homomorphism from element of
    Hom
  * "httpHeaders" -- see httpHeaders(String), --
    prepend http headers to a string
  * hypercube (Polyhedra) -- Returns the d-dimensional
    hypercube
  * hyperplanes (Polyhedra) -- computes the defining
    hyperplanes of a Cone or a Polyhedron
  * icFractions (IntegralClosure) -- fractions integral over
    an affine domain
  * icMap (IntegralClosure) -- natural map from an affine domain
    into its integral closure
  * icPIdeal (IntegralClosure) -- compute the integral closure
    in prime characteristic of a principal ideal
  * image -- image of a map
  * imageFan (Polyhedra) --  computes the fan of the image
  * imaginaryPart -- imaginary part
  * importFrom -- import symbols to the current private
    dictionary
  * incompCones (Polyhedra) -- returns the pairs of
    incompatible cones
  * incompPolyhedra (Polyhedra) -- returns the pairs of
    incompatible polyhedra
  * index -- numeric index of a ring variable
  * indices -- indices of a polynomial; also components for a
    direct sum
  * inducesWellDefinedMap -- whether a map is
    well defined
  * inInterior (Polyhedra) -- checks if a point lies in the
    relative interior of a Cone/Polyhedron
  * insert -- copy a list, inserting an element
  * installAssignmentMethod -- install methods
    assignment to the value of an operator
  * "instances" -- see instances(Type),
  * integrate -- numerical integration
  * interiorLatticePoints (Polyhedra) -- computes
    the lattice points in the relative interior of a polytope
  * interiorPoint (Polyhedra) -- computes a point in the
    relative interior of the Polyhedron
  * interiorVector (Polyhedra) -- computes a vector in
    the relative interior of a Cone
  * inverse -- compute the inverse
  * inverseErf -- inverse error function
  * inverseRegularizedBeta -- inverse of the
    regularized beta function
  * inverseRegularizedGamma -- inverse of the
    upper regularized gamma function
  * irreducibleCharacteristicSeries, --
    irreducible characteristic series of an ideal
  * irreducibleDecomposition (PrimaryDecomposition)
    -- express a monomial ideal
    as an intersection of irreducible monomial ideals
  * isAffineRing -- whether something is an affine ring
  * isBorel -- whether an ideal is fixed by upper triangular
    changes of coordinates
  * isc (OnlineLookup) -- ISC lookup
  * isCommutative -- whether a ring is commutative
  * isCompact (Polyhedra) -- checks compactness of a
    Polyhedron
  * isComplete (Polyhedra) -- checks completeness of a Fan or
    PolyhedralComplex
  * isConstant -- whether a ring element is constant
  * isDirectSum -- whether something is a direct sum
  * isEmpty
  * isFace (Polyhedra) -- tests if the first argument is a face
    of the second
  * isField -- whether something is a field
  * isFinite -- whether a number is finite
  * isFreeModule -- whether something is a free module
  * isFullDimensional (Polyhedra) -- Determine whether
    a polyhedral object is full-dimensional
  * isHomogeneous -- whether something is homogeneous
    (graded)
  * isIdeal -- whether something is an ideal
  * isInfinite -- whether a number is infinite
  * isInjective -- whether a map is injective
  * isIsomorphism -- whether a map is an isomorphism
  * isLatticePolytope (Polyhedra) -- checks if a
    polyhedron is a lattice polytope
  * isLiftable (missing documentation)
  * isMember -- test membership in a list or set
  * isModule -- whether something is a module
  * isMonomialIdeal -- whether something is a monomial
    ideal
  * isNormal
  * isPointed (Polyhedra) -- checks if a Cone or Fan is
    pointed
  * isPolynomialRing -- whether something is a
    polynomial ring
  * isPolytopal (Polyhedra) -- checks if a Fan is polytopal
  * isProjective (missing documentation)
  * isPure (Polyhedra) -- checks if a Fan or PolyhedralComplex is
    of pure dimension
  * isQuotientModule -- whether something is evidently
    a quotient of a free module
  * isQuotientOf -- whether one thing is a quotient of
    another
  * isQuotientRing -- whether something is a quotient
    ring
  * isReal -- whether a number is real
  * isRing -- whether something is a ring
  * isSimplicial (Polyhedra) --  checks if a polyhedral
    object is simplicial
  * isSkewCommutative -- whether a ring has skew
    commuting variables
  * isSquareFree -- whether something is square free
    monomial ideal
  * isStandardGradedPolynomialRing (InverseSystems)
    -- Checks whether a ring is
    a polynomial ring over a field with variables of degree 1
  * isSubmodule -- whether a module is evidently a
    submodule of a free module
  * "isSubquotient" -- see isSubquotient(Module,Module),
    -- check whether a module is a
    subquotient of another
  * isSubset -- whether one object is a subset of another
  * isSupportedInZeroLocus (Saturation), --
    whether support of a module is contained in the zero locus of the
    (irrelevant) ideal
  * isSurjective -- whether a map is surjective
  * isUnit -- whether a ring element is a unit
  * isWellDefined -- whether a map is well defined
  * jacobian -- the Jacobian matrix of partial derivatives
  * kernelOfLocalization (PrimaryDecomposition), --
    the kernel of the localization map
  * koszul -- Koszul complex or specific matrix in the Koszul
    complex
  * latticePoints (Polyhedra) -- computes the lattice
    points of a polytope
  * latticeVolume (Polyhedra) -- Returning the lattice
    volume of a polyhedron.
  * leadCoefficient -- the coefficient of the leading
    term
  * leadComponent -- the leading component(s) of a vector
    or matrix
  * leadMonomial -- the leading monomial of a ring element
  * leadTerm -- get the greatest term
  * liftable -- whether lifting to another ring is possible
  * linealitySpace (Polyhedra) -- computes a basis of the
    lineality space
  * linearTransform (missing documentation)
  * linSpace (Polyhedra) -- Deprecated version of @TO
    "linealitySpace"@
  * listForm -- convert to list form
  * listSymbols -- compact display of symbols and their
    values
  * lngamma -- logarithm of the Gamma function
  * log -- logarithm function
  * log1p -- logarithm of 1+x
  * LUdecomposition -- LU decomposition
  * "makeDirectory" -- see makeDirectory(String),
    -- make a directory
  * maxCones (Polyhedra) -- displays the generating Cones of a
    Fan
  * maxFace (Polyhedra) -- computes the face of a Polyhedron or
    Cone where a weight attains its maximum
  * maxPolyhedra (Polyhedra) -- displays the generating
    Polyhedra of a PolyhedralComplex
  * memoize -- record results of function evaluation for future
    use
  * "methodOptions" -- see methodOptions(Function),
    -- recover the options used when a method
    function was created
  * minFace (Polyhedra) -- computes the face of a Polyhedron or
    Cone where a weight attains its minimum
  * minimalNonFaces (missing documentation)
  * minimize (missing documentation)
  * minkowskiSum (Polyhedra) --  computes the Minkowski sum
    of two convex objects
  * minkSummandCone (Polyhedra) -- computes the Cone of
    all Minkowski summands and the minimal decompositions
  * mixedVolume (Polyhedra) -- computes the mixed volume of
    a list of polytope
  * module -- make or get a module
  * monomialSubideal -- find the largest monomial
    ideal in an ideal
  * multidegree -- multidegree
  * multigraded -- convert a Betti tally into a multigraded
    Betti tally
  * nefCone (missing documentation)
  * nefGenerators (missing documentation)
  * newCoordinateSystem -- change variables
  * newtonPolytope (Polyhedra) -- computes the Newton
    polytope of a polynomial
  * next -- get the next object from an iterator
  * nextPrime -- compute the smallest prime greater than or
    equal to a given number
  * norm
  * normalFan (Polyhedra) -- computes the normalFan of a
    polyhedron
  * nullhomotopy -- make a null homotopy
  * nullSpace -- find the null space of a mutable matrix
  * "numColumns" -- see numColumns(Matrix), --
    number of columns in a matrix or mutable matrix
  * numerator -- numerator of a fraction
  * numeric -- convert to floating point
  * numericInterval -- converts to an interval
  * numgens -- the number of generators
  * "numRows" -- see numRows(Matrix), -- number of
    rows in a matrix or mutable matrix
  * nVertices (Polyhedra) -- Returns the number of vertices of
    a polyhedron
  * objectiveVector (Polyhedra) -- computes an objective
    vector of a face of a polyhedron
  * ofClass -- English phrases for types
  * pack -- pack elements of a list or string into several shorter
    lists or strings
  * packageTemplate (SimpleDoc) -- a template for a
    package
  * pad -- pad a string or net with spaces
  * part -- select terms of a polynomial by degree(s) or weight(s)
  * partition -- partition a set or list by values of a
    function
  * partitions -- list the partitions of an integer
  * parts -- display terms of a polynomial degree by degree
  * pdim -- calculate the projective dimension
  * peek' -- examine contents of an object
  * permanents -- ideal generated by square permanents of a
    matrix
  * permutations -- produce all permutations of a list
  * pfaffians -- ideal generated by Pfaffians
  * "pivots" -- see pivots(Matrix), -- list of pivot
    locations of a matrix
  * "installHilbertFunction" -- see poincare, -- assemble
    degrees of a ring, module, or ideal into a polynomial
  * poincare -- assemble degrees of a ring, module, or ideal
    into a polynomial
  * poincareN -- assemble degrees into polynomial
  * polar (Polyhedra) --  computes the polar of a polyhedron
  * polarFace (Polyhedra) --  computes the dual face of the
    polar polyhedron
  * "poly" -- see poly(String) (Classic), -- make a
    polynomial using classic Macaulay syntax
  * polyhedra (Polyhedra) -- computes all polyhedra of a
    polyhedral complex of a certain dimension
  * polyhedralComplex (Polyhedra) -- generates a
    PolyhedralComplex
  * polyhedron (Polyhedra) -- Turn a cone into a polyhedron
  * polyhedronFromHData (Polyhedra) -- Constructing
    a polyhedron from its H-representation, i.e. inequalities and equations
  * polytope (Polyhedra) -- returns a polytope of which the fan
    is the normal fan if it is polytopal
  * positions -- which elements of a list satisfy a condition
  * posOrthant (Polyhedra) -- generates the positive orthant
    in n-space
  * precision
  * preimage -- preimage of a map
  * presentation -- presentation of a module or ring
  * product
  * profile -- profile a function
  * Proj (Varieties) -- make a projective variety
  * projectiveHilbertPolynomial -- Hilbert
    polynomial of projective space
  * promote -- promote to another ring
  * proximum (Polyhedra) -- computes the proximum of the
    Polyhedron/Cone to a point in euclidean metric
  * pseudoRemainder -- compute the pseudo-remainder
  * pushout -- compute the pushout morphism
  * pyramid (Polyhedra) -- computes the pyramid over a
    polyhedron
  * QRDecomposition -- compute a QR decomposition of a
    real matrix
  * quotient' -- matrix quotient (opposite)
  * quotientRemainder -- matrix quotient and
    remainder
  * quotientRemainder' -- matrix quotient and
    remainder (opposite)
  * randomKRationalPoint -- Pick a random K
    rational point on the scheme X defined by I
  * rank -- compute the rank
  * realPart -- real part
  * reducedRowEchelonForm -- compute the reduced
    row echelon form of a matrix or mutable matrix over a field
  * reduceHilbert -- reduce a Hilbert series expression
  * reductionNumber (ReesAlgebra) -- Reduction number of
    one ideal with respect to another
  * registerFinalizer -- register a string that will
    be displayed when an object is garbage collected
  * regularizedBeta -- regularized beta function
  * regularizedGamma -- upper regularized gamma
    function
  * regularSubdivision (Polyhedra) -- Computes the
    regular cell decomposition
  * regularTriangulation (Polyhedra) -- Computes a
    regular triangulation of a given polytope.
  * relations -- the defining relations
  * remainder -- matrix remainder
  * remainder' -- matrix quotient and remainder (opposite)
  * removeLowestDimension (PrimaryDecomposition),
    -- remove components of lowest dimension
  * reshape -- reshape a matrix
  * ring -- get the associated ring of an object
  * "rotate" -- see rotate(ZZ,VisibleList),
    -- rotate a list
  * round -- round a number
  * rowAdd -- add a multiple of one row to another
  * rowMult -- multiply a row by a ring element
  * rowPermute -- permute some rows
  * rowRankProfile -- find the row rank profile of a
    mutable matrix
  * rowSwap -- interchange rows
  * saveSession (Polyhedra) -- save the actual Polyhedra
    session to a file
  * scanKeys -- apply a function to each key in a hash table
    or database
  * scanLines -- apply a function to each line of a file
  * scanValues -- apply a function to each value in a hash
    table or database
  * schreyerOrder -- create or obtain free modules with
    Schreyer monomial orders
  * "searchPath" -- see searchPath(List,String),
    -- search a path for a file
  * sec -- secant
  * sech -- hyperbolic secant
  * secondaryPolytope (Polyhedra) -- computes the
    secondary polytope of a compact polyhedron
  * "selectValues" -- see select(HashTable,Function),
    -- select part of a hash table
  * selectInSubring -- select columns in a subring
  * selectKeys -- select a part of a hash table by keys
  * "selectVariables" -- see selectVariables(List,PolynomialRing),
    -- make a subring of a
    polynomial ring generated by selected variables
  * setup
  * setupEmacs
  * setupLift -- set up lift from one ring to another
  * setupPromote -- set up promote from one ring to
    another
  * sheaf (Varieties) -- make a coherent sheaf
  * sheafMap (missing documentation)
  * show -- display various objects in an external viewer
  * simplex (Polyhedra) -- Produces a full-dimensional simplex
  * sin -- compute the sine
  * singularLocus -- singular locus
  * sinh -- compute the hyperbolic sine
  * size -- the size of an object
  * skeleton (Polyhedra) -- computes the k-skeleton of a Fan or
    PolyhedralComplex
  * smallestFace (Polyhedra) -- determines the smallest
    face of the Cone/Polyhedron containing a point
  * smoothSubfan (Polyhedra) -- computes the subfan of all
    smooth cones
  * someTerms -- select some terms of a polynomial
  * source -- source of a map
  * Spec (Varieties) -- make an affine variety
  * splitWWW -- separate an http response into header and body
  * sqrt -- square root function
  * stacksProject (SimpleDoc) -- link to a Stacks Project
    tag
  * standardForm -- convert to standard form
  * standardPairs -- find the standard pairs of a
    monomial ideal
  * stanleyReisnerRing (missing documentation)
  * statePolytope (Polyhedra) -- computes the state
    polytope of a homogeneous ideal
  * stdSimplex (Polyhedra) -- generates the d-dimensional
    standard simplex
  * stellarSubdivision (Polyhedra) -- computes the
    stellar subdivision of the fan by a ray
  * store -- store the value of an atomic integer
  * sublatticeBasis (Polyhedra) -- computes a basis for
    the sublattice generated by integral vectors or lattice points of a
    polytope
  * sublists -- process interspersed subsequences of a visible
    list
  * submatrix
  * submatrix' -- exclude rows and/or columns of a matrix
  * submatrixByDegrees -- submatrix consisting of
    rows and columns in an interval or box of degrees
  * subquotient -- make a subquotient module
  * subsets -- produce the subsets of a set or list
  * substitute -- substituting values for variables
  * sum -- compute the sum
  * super -- get the ambient module
  * support -- list of variables occurring in a polynomial or
    matrix
  * switch -- copy a list, switching two elements
  * "sylvesterMatrix" -- see
    sylvesterMatrix(RingElement,RingElement,RingElement) (Elimination),
  * symmetricPower -- symmetric power
  * tailCone (Polyhedra) -- computes the tail/recession cone of
    a polyhedron
  * tan -- compute the tangent
  * tanh -- compute the hyperbolic tangent
  * target -- target of a map
  * tensorAssociativity -- associativity
    isomorphisms for tensor products
  * terms -- provide a list of terms of a polynomial
  * testHunekeQuestion (IntegralClosure) -- tests a
    conjecture on integral closures strengthening the Eisenbud-Mazur conjecture
  * tests -- locate a package's tests
  * toDividedPowers (InverseSystems) -- Translates to
    divided power monomial basis from ordinary monomial basis
  * "toField" -- see toField(Ring), -- declare that a
    ring is a field
  * topCoefficients -- first variable and its
    coefficient of a polynomial or matrix
  * topComponents (PrimaryDecomposition) -- compute top
    dimensional component of an ideal or module
  * toSublattice (Polyhedra) -- calculates the preimage of
    a polytope in the sublattice generated by its lattice points
  * "trace" -- see trace(Matrix), -- trace of a matrix
  * triangulate (Polyhedra) -- Deprecated name for {\tt
    barycentricTriangulation}
  * truncateOutput
  * ultimate -- ultimate value for an iteration
  * "unbag" -- see unbag(Bag),
  * uniquePermutations -- produce all unique
    permutations of a list
  * urlEncode -- URL encoding
  * value -- evaluate
  * variety (Varieties) -- get the variety
  * vector -- make a vector
  * versalEmbedding (ReesAlgebra) -- Compute a versal
    embedding
  * vertexEdgeMatrix (Polyhedra) -- computes the
    vertex-edge-relations matrix
  * vertexFacetMatrix (Polyhedra) -- computes the
    vertex-facet-relations matrix
  * vertices (Polyhedra) -- displays the vertices of a
    Polyhedron or a PolyhedralComplex
  * volume (Polyhedra) -- computes the volume of a polytope
  * "wedgeProduct" -- see wedgeProduct(ZZ,ZZ,Module),
    -- the exterior multiplication map
  * weightRange -- the pair of lowest and highest weights
    of the monomials
  * "isWeylAlgebra" -- see Weyl algebras,
  * whichGm (ReesAlgebra) -- Largest Gm satisfied by an ideal
  * width -- width of a file or net
  * wikipedia (SimpleDoc) -- link to a Wikipedia article
  * zeta -- Riemann zeta function

For the programmer
==================

The object MethodFunction, is a type, with
ancestor classes CompiledFunctionClosure, <
Function < Thing.

MethodFunctionSingle -- a type of method function
*************************************************

Description
===========

The type of all method functions created with the option Dispatch,
set to Thing, such as code.

See also
========

  * method -- make a new method function

Protected objects of class MethodFunctionSingle:
================================================

  * chainComplex -- make a chain complex
  * code -- display source code
  * commonest -- the most common elements of a list or tally
  * describe -- real description
  * directSum -- direct sum of modules or maps
  * document -- create a documentation node
  * "makeDocumentTag" -- see DocumentTag, -- the class of
    all document tags
  * EXAMPLE -- hypertext EXAMPLE item
  * examples -- list the examples in documentation
  * export -- export symbols from a package
  * exportMutable -- export mutable symbols from a
    package
  * expression -- convert to an expression
  * flatten -- flatten a nested list or a matrix
  * format -- format a string or a real number
  * gradedModule -- make a graded module
  * gradedModuleMap -- make a map of graded modules
  * hold -- hold something in a holder expression
  * hooks -- list hooks attached to a key
  * html -- convert to HTML format
  * hypertext -- prepare hypertext for display
  * ideal -- make an ideal
  * info -- convert hypertext to info format
  * isSorted -- whether a list is sorted
  * iterator -- get an iterator
  * length -- length of an object
  * locate -- locate source code
  * makePackageIndex -- create an index of installed
    packages
  * mathML -- convert to MathML format
  * max -- yields the maximum element in a list or sequence
  * maxPosition -- position of the largest element
  * methods -- list methods
  * min -- yields the minimum element in a list or sequence
  * minPosition -- position of the smallest element
  * monoid -- make or retrieve a monoid
  * monomialIdeal -- make a monomial ideal
  * net -- format for printing, as a net
  * newPackage -- the preamble of a package
  * options -- get options
  * package -- get containing package
  * pretty -- a pretty printer
  * regexQuote -- escape special characters in regular
    expressions
  * "runLengthEncode" -- see runLengthEncode(VisibleList),
    -- run length encoding
  * setRandomSeed -- set starting point for random number
    generator
  * span -- construct smallest interval
  * SYNOPSIS -- a standardized synopsis for use in
    documentation nodes
  * tex -- convert to $\TeX$ format
  * texMath -- convert to TeX math format
  * toExternalString -- convert to a readable string
  * toList -- create a list
  * toString -- convert to a string
  * transpose -- transpose a table or a matrix
  * undocumented -- declare that something need not be
    documented
  * unique -- eliminate duplicates from a list
  * use -- install or activate object
  * vars -- variables

For the programmer
==================

The object MethodFunctionSingle, is a type,
with ancestor classes FunctionClosure, <
Function < Thing.

MethodFunctionBinary -- a type of method function
*************************************************

Description
===========

The type of all method functions created with the option Binary,
set to true, such as gcd.

See also
========

  * method -- make a new method function

Protected objects of class MethodFunctionBinary:
================================================

  * gcd -- greatest common divisor
  * intersect -- compute an intersection
  * lcm -- least common multiple
  * tensor -- tensor product
  * union (missing documentation)

For the programmer
==================

The object MethodFunctionBinary, is a type,
with ancestor classes FunctionClosure, <
Function < Thing.

MethodFunctionWithOptions -- a type of method function
******************************************************

Description
===========

Functions of this type are created by method.

Protected objects of class MethodFunctionWithOptions:
=====================================================

  * about -- search the documentation
  * addHook -- add a hook function to an object for later
    processing
  * adjoint -- the tensor-Hom adjunction maps
  * analyticSpread (ReesAlgebra) -- Compute the analytic
    spread of a module or ideal
  * annihilator (Saturation) -- the annihilator ideal
  * associatedGradedRing (ReesAlgebra) -- The
    normal cone of a subscheme
  * associatedPrimes (PrimaryDecomposition) -- find
    associated primes
  * basis -- basis or generating set of all or part of a ring,
    ideal or module
  * betti -- display or modify a Betti diagram
  * canonicalBundle (missing documentation)
  * capture -- evaluate Macaulay2 code and capture the output
  * check -- perform tests of a package
  * checkDegrees (Isomorphism) -- compares the degrees of
    generators of two modules
  * codim -- compute the codimension
  * coefficients -- monomials and their coefficients
  * cohomology -- general cohomology functor
  * compose -- composition as a pairing on Hom-modules
  * conwayPolynomial (ConwayPolynomials) -- provide a
    Conway polynomial
  * "copyDirectory" -- see copyDirectory(String,String),
  * "copyFile" -- see copyFile(String,String),
  * cotangentSheaf (Varieties) -- cotangent sheaf of a
    projective variety
  * decompose
  * determinant -- determinant of a matrix
  * "discriminant" -- see discriminant(RingElement,RingElement) (Elimination),
  * distinguished (ReesAlgebra) -- Compute the
    distinguished subvarieties of a pullback, intersection or cone
  * dual -- dual module or map
  * eigenvalues -- find eigenvalues of a matrix
  * eigenvectors -- find eigenvectors of a matrix over RR
    or CC
  * extend -- extend a module map to a chain map, if possible
  * exteriorPower -- exterior power
  * factor -- factor a ring element or a ZZ-module
  * fillMatrix -- fill a mutable matrix with random numbers
  * findFiles -- find files recursively
  * findHeft -- find a heft vector for a list of degrees
  * findProgram -- load external program
  * flattenRing -- write a ring as a (quotient of a)
    polynomial ring
  * forceGB -- declare that the columns of a matrix are a
    Gröbner basis
  * fromDual (InverseSystems) -- Ideal from inverse system
  * gb -- compute a Gröbner basis
  * gcdLLL (LLLBases) -- compute the gcd of integers, and small
    multipliers
  * generators -- provide matrix or list of generators
  * getPrimeWithRootOfUnity -- find a prime p
    with a primitive n-th root of unity r in ZZ/p
  * GF -- make a finite field
  * "graphIdeal" -- see graphIdeal(RingMap), --
    the ideal of the graph of the regular map corresponding to a ring map
  * "graphRing" -- see graphRing(RingMap), -- the
    coordinate ring of the graph of the regular map corresponding to a ring map
  * "Grassmannian" -- see Grassmannian(ZZ,ZZ),
    -- the Grassmannian of linear subspaces of a vector space
  * groebnerBasis -- Gröbner basis, as a matrix
  * hermite (missing documentation)
  * hilbertBasis (Polyhedra) -- computes the Hilbert basis
    of a Cone
  * hilbertPolynomial -- compute the Hilbert
    polynomial
  * hilbertSeries -- compute the Hilbert series
  * Hom -- module of homomorphisms
  * homology -- general homology functor
  * homomorphism' -- get the element of Hom from a
    homomorphism
  * icFracP (IntegralClosure) -- compute the integral closure in
    prime characteristic
  * idealizer (IntegralClosure) -- compute Hom(I,I) as a
    quotient ring
  * independentSets -- some size-maximal independent
    subsets of variables modulo an ideal
  * inducedMap -- compute an induced map
  * installPackage -- load and install a package and its
    documentation
  * integralClosure (IntegralClosure) -- integral
    closure of an ideal or a domain
  * intersectInP (ReesAlgebra) -- Compute distinguished
    varieties for an intersection in A^n or P^n
  * intersection -- compute an intersection
  * interval -- construct an interval
  * inverseSystem (InverseSystems) -- Inverse systems with
    equivariance
  * isIsomorphic (Isomorphism) -- Probabilistic test for
    isomorphism of modules
  * isLinearType (ReesAlgebra) -- Determine whether module
    has linear type
  * isLLL (LLLBases) -- is a basis an LLL basis?
  * isPrimary (PrimaryDecomposition) -- determine whether a
    submodule is primary
  * isPrime -- whether a integer or polynomial is prime
  * "isPseudoprime" -- see isPseudoprime(ZZ), --
    whether an integer is probably prime
  * isReduction (ReesAlgebra) -- Determine whether an ideal
    is a reduction
  * isReflexive (Polyhedra) --  checks if a Polytope is
    reflexive
  * isSmooth
  * isVeryAmple
  * jacobianDual (ReesAlgebra) -- Computes the 'jacobian
    dual', part of a method of finding generators for Rees Algebra ideals
  * kernel -- kernel of a ringmap, matrix, or chain complex
  * kernelLLL (missing documentation)
  * lift -- lift to another ring
  * LLL (LLLBases) -- compute an LLL basis
  * loadPackage -- load a package
  * localize (PrimaryDecomposition) -- localize an ideal at a
    prime ideal
  * makeS2 (IntegralClosure) -- compute the S2ification of a
    reduced ring
  * map -- make a map
  * "markedGB" -- see markedGB(Matrix,Matrix),
    -- make a marked Gröbner basis
  * match -- regular expression matching
  * matrix -- make a matrix
  * mingens -- minimal generator matrix
  * minimalBetti -- minimal betti numbers of (the minimal
    free resolution of) a homogeneous ideal or module
  * minimalPresentation -- compute a minimal
    presentation
  * minimalPrimes (MinimalPrimes) -- minimal primes of an
    ideal
  * minimalReduction (ReesAlgebra) -- Find a minimal
    reduction of an ideal
  * "minors" -- see minors(ZZ,Matrix), -- ideal
    generated by minors
  * "modulo" -- see modulo(Matrix,Matrix),
    -- find the pre-image (pullback) of image of a map (low level version)
  * monomials -- matrix of monomials in a ring element or
    matrix
  * "moveFile" -- see moveFile(String,String),
  * multiplicity (ReesAlgebra) -- Compute the
    Hilbert-Samuel multiplicity of an ideal
  * "mutableIdentity" -- see mutableIdentity(Ring,ZZ),
    -- make a mutable identity matrix
  * mutableMatrix -- make a mutable matrix
  * needsPackage -- load a package if not already loaded
  * "netList" -- see netList(VisibleList), -- a
    table of boxes
  * newRing -- make a copy of a ring, with some features
    changed
  * normalCone
  * oeis (OnlineLookup) -- OEIS lookup
  * parallelApply -- apply a function to each element in
    parallel
  * polarize -- given a monomial ideal, computes the
    squarefree monomial ideal obtained via polarization
  * position -- the first element of a list satisfying a
    condition
  * primaryComponent (PrimaryDecomposition) -- find a
    primary component corresponding to an associated prime
  * primaryDecomposition (PrimaryDecomposition), --
    irredundant primary decomposition of an ideal
  * prune -- prune, e.g., compute a minimal presentation
  * pullback -- compute the pullback morphism
  * "pushForward" -- see pushForward(RingMap,Module),
  * quotient -- quotient or division
  * radical (MinimalPrimes) -- the radical of an ideal
  * radicalContainment (MinimalPrimes) -- whether an
    element is contained in the radical of an ideal
  * random -- get a random object
  * "randomMutableMatrix" -- see randomMutableMatrix(ZZ,ZZ,RR,ZZ),
    -- a random mutable matrix of
    integers
  * rays -- 1-dimensional cones of a fan or polyhedral object
  * readPackage -- read the package preamble
  * reesAlgebra (ReesAlgebra) -- Compute the defining ideal
    of the Rees Algebra
  * reesIdeal (ReesAlgebra) -- Compute the defining ideal of
    the Rees Algebra
  * regex -- evaluate a regular expression search
  * regSeqInIdeal (PrimaryDecomposition) -- a regular
    sequence contained in an ideal
  * regularity -- compute the Castelnuovo-Mumford regularity
  * replace -- replacement in strings and lists
  * resolution -- projective resolution
  * "resultant" -- see resultant(RingElement,RingElement,RingElement) (Elimination),
  * ringFromFractions (IntegralClosure) -- find
    presentation for f.g. ring
  * "roots" -- see roots(RingElement), -- compute
    the roots of a polynomial
  * rsort -- sort a list or matrix in reverse order
  * runHooks -- run the hook functions stored in an object
  * runProgram -- run an external program
  * saturate (Saturation) -- saturation of ideal or submodule
  * "Schubert" -- see Schubert(ZZ,ZZ,VisibleList),
    -- find the Plücker ideal of a
    Schubert variety
  * select -- select from a list, hash table, or string
  * separate -- split a string into substrings using a regular
    expression
  * sheafHom (Varieties) -- sheaf Hom
  * simpleDocFrob (SimpleDoc) -- a sample documentation
    node
  * "smithNormalForm" -- see smithNormalForm(Matrix),
    -- smith normal form for a matrix over ZZ or a
    PID
  * solve -- solve linear equation(s)
  * sort -- sort a list or columns of a matrix
  * sortColumns -- permutation giving sort order
  * specialFiber (ReesAlgebra) -- Special fiber of a blowup
  * specialFiberIdeal (ReesAlgebra) -- Special fiber
    of a blowup
  * status -- status of a resolution computation
  * SVD -- singular value decomposition of a matrix
  * "symlinkDirectory" -- see symlinkDirectory(String,String),
    -- make symbolic links for all files
    in a directory tree
  * symmetricAlgebra -- the symmetric algebra of a
    module
  * symmetricAlgebraIdeal (ReesAlgebra) -- Ideal
    of the symmetric algebra of an ideal or module
  * symmetricKernel (ReesAlgebra) -- Compute the Rees
    ring of the image of a matrix
  * syz -- the syzygy matrix
  * "tangentCone" -- see tangentCone(Ideal) (TangentCone),
  * tangentSheaf (Varieties) -- tangent sheaf of a
    projective variety
  * toDual (InverseSystems) -- finds the inverse system to an
    ideal up to a given degree
  * trim -- minimize generators and relations
  * truncate
  * uninstallPackage -- uninstall a package and remove
    its documentation

For the programmer
==================

The object MethodFunctionWithOptions, is a
type, with ancestor classes FunctionClosure,
< Function < Thing.

methods -- list methods
***********************

Description
===========

Synopsis
========

  * Usage:
        methods x
  * Inputs:
      * x, a function, a type, a keyword,
        or a package,
  * Outputs:
      * a vertical list, of those methods associated with x
+-------------------------------------------------------------------+
|i1 : methods BettiTally                                            |
|                                                                   |
|o1 = {0 => (==, BettiTally, BettiTally)                           }|
|     {1 => (++, BettiTally, BettiTally)                           }|
|     {2 => (**, BettiTally, BettiTally)                           }|
|     {3 => (SPACE, BettiTally, Array)                             }|
|     {4 => (SPACE, BettiTally, ZZ)                                }|
|     {5 => (lift, BettiTally, ZZ)                                 }|
|     {6 => (*, QQ, BettiTally)                                    }|
|     {7 => (*, ZZ, BettiTally)                                    }|
|     {8 => (multigraded, BettiTally)                              }|
|     {9 => (net, BettiTally)                                      }|
|     {10 => (texMath, BettiTally)                                 }|
|     {11 => (betti, BettiTally)                                   }|
|     {12 => (pdim, BettiTally)                                    }|
|     {13 => (poincare, BettiTally)                                }|
|     {14 => (hilbertPolynomial, ZZ, BettiTally)                   }|
|     {15 => (degree, BettiTally)                                  }|
|     {16 => (hilbertSeries, ZZ, BettiTally)                       }|
|     {17 => (^, Ring, BettiTally)                                 }|
|     {18 => (regularity, BettiTally)                              }|
|     {19 => (mathML, BettiTally)                                  }|
|     {20 => (truncate, BettiTally, ZZ, InfiniteNumber)            }|
|     {21 => (truncate, BettiTally, ZZ, ZZ)                        }|
|     {22 => (codim, BettiTally)                                   }|
|     {23 => (truncate, BettiTally, InfiniteNumber, InfiniteNumber)}|
|     {24 => (dual, BettiTally)                                    }|
|     {25 => (truncate, BettiTally, InfiniteNumber, ZZ)            }|
|                                                                   |
|o1 : NumberedVerticalList                                          |
+-------------------------------------------------------------------+
|i2 : methods resolution                                            |
|                                                                   |
|o2 = {0 => (resolution, Ideal) }                                   |
|     {1 => (resolution, Module)}                                   |
|     {2 => (resolution, Matrix)}                                   |
|                                                                   |
|o2 : NumberedVerticalList                                          |
+-------------------------------------------------------------------+
|i3 : methods symbol @@                                             |
|                                                                   |
|o3 = {0 => (@@, Function, Function)    }                           |
|     {1 => (@@, Expression, Expression)}                           |
|     {2 => (@@, Expression, Holder)    }                           |
|     {3 => (@@, Holder, Expression)    }                           |
|     {4 => (@@, Holder, Holder)        }                           |
|     {5 => (@@, Expression, Thing)     }                           |
|     {6 => (@@, Thing, Expression)     }                           |
|     {7 => ((@@, =), Type, Type)       }                           |
|     {8 => ((@@, =), Thing, Thing)     }                           |
|     {9 => (@@, Thing, Thing)          }                           |
|                                                                   |
|o3 : NumberedVerticalList                                          |
+-------------------------------------------------------------------+

Synopsis
========

  * Usage:
        methods(s,X)
  * Inputs:
      * s, a symbol,
      * X, a type,
  * Outputs:
      * a vertical list, of those methods associated with
        the operator s and the type X
+--------------------------------------+
|i4 : methods( symbol ++, Module)      |
|                                      |
|o4 = {0 => (++, GradedModule, Module)}|
|     {1 => (++, Module, GradedModule)}|
|     {2 => (++, Module, Module)      }|
|                                      |
|o4 : NumberedVerticalList             |
+--------------------------------------+

Synopsis
========

  * Usage:
        methods(X,Y)
  * Inputs:
      * X, a type,
      * Y, a type,
  * Outputs:
      * a vertical list, of those methods associated with
+------------------------------------------------------------------+
|i5 : methods( Matrix, Matrix )                                    |
|                                                                  |
|o5 = {0 => (diff', Matrix, Matrix)                               }|
|     {1 => (+, Matrix, Matrix)                                   }|
|     {2 => (-, Matrix, Matrix)                                   }|
|     {3 => (contract, Matrix, Matrix)                            }|
|     {4 => (diff, Matrix, Matrix)                                }|
|     {5 => (contract', Matrix, Matrix)                           }|
|     {6 => (markedGB, Matrix, Matrix)                            }|
|     {7 => (Hom, Matrix, Matrix)                                 }|
|     {8 => (==, Matrix, Matrix)                                  }|
|     {9 => (*, Matrix, Matrix)                                   }|
|     {10 => (|, Matrix, Matrix)                                  }|
|     {11 => (||, Matrix, Matrix)                                 }|
|     {12 => (subquotient, Matrix, Matrix)                        }|
|     {13 => (subquotient, Module, Matrix, Matrix)                }|
|     {14 => (**, Matrix, Matrix)                                 }|
|     {15 => (homology, Matrix, Matrix)                           }|
|     {16 => (modulo, Matrix, Matrix)                             }|
|     {17 => (quotientRemainder', Matrix, Matrix)                 }|
|     {18 => (quotientRemainder, Matrix, Matrix)                  }|
|     {19 => (//, Matrix, Matrix)                                 }|
|     {20 => (\\, Matrix, Matrix)                                 }|
|     {21 => (quotient', Matrix, Matrix)                          }|
|     {22 => (quotient, Matrix, Matrix)                           }|
|     {23 => (remainder', Matrix, Matrix)                         }|
|     {24 => (remainder, Matrix, Matrix)                          }|
|     {25 => (%, Matrix, Matrix)                                  }|
|     {26 => (pushout, Matrix, Matrix)                            }|
|     {27 => (solve, Matrix, Matrix)                              }|
|     {28 => (tensor, Matrix, Matrix)                             }|
|     {29 => (pullback, Matrix, Matrix)                           }|
|     {30 => (intersection, Matrix, Matrix)                       }|
|     {31 => (intersection, Matrix, Matrix, Matrix, Matrix)       }|
|     {32 => (substitute, Matrix, Matrix)                         }|
|     {33 => (checkDegrees, Matrix, Matrix)                       }|
|     {34 => (isIsomorphic, Matrix, Matrix)                       }|
|     {35 => (coneFromVData, Matrix, Matrix)                      }|
|     {36 => (coneFromHData, Matrix, Matrix)                      }|
|     {37 => (fan, Matrix, Matrix, List)                          }|
|     {38 => (fan, Matrix, Matrix, Sequence)                      }|
|     {39 => (polyhedralComplex, Matrix, Matrix, Matrix, List)    }|
|     {40 => (polyhedralComplex, Matrix, Matrix, List)            }|
|     {41 => (convexHull, Matrix, Matrix, Matrix)                 }|
|     {42 => (convexHull, Matrix, Matrix)                         }|
|     {43 => (polyhedronFromHData, Matrix, Matrix)                }|
|     {44 => (polyhedronFromHData, Matrix, Matrix, Matrix, Matrix)}|
|     {45 => (affineImage, Matrix, Polyhedron, Matrix)            }|
|     {46 => (affineImage, Matrix, Cone, Matrix)                  }|
|     {47 => (affinePreimage, Matrix, Polyhedron, Matrix)         }|
|     {48 => (affinePreimage, Matrix, Cone, Matrix)               }|
|     {49 => (regularSubdivision, Matrix, Matrix)                 }|
|     {50 => (jacobianDual, Matrix, Matrix, Matrix)               }|
|     {51 => (isLiftable, Matrix, Matrix)                         }|
|     {52 => (++, Matrix, Matrix)                                 }|
|                                                                  |
|o5 : NumberedVerticalList                                         |
+------------------------------------------------------------------+
This function operates by examining those types that are values of global
symbols for keys that appear to be storing references to methods.  Types that
don't appear as values of global variables will not be examined, so perhaps not
all methods will be found.

See also
========

  * options(ZZ) -- get optional arguments and
    default values of functions and methods
  * code(ZZ) -- display source code
  * code(List) -- display source code
  * locate(List) -- locate source code
  * makeDocumentTag(List) -- the class of all document tags

Ways to use methods:
====================

  * "methods(Command)"
  * "methods(Manipulator)"
  * "methods(Package)"
  * "methods(ScriptedFunctor)"
  * "methods(Sequence)"
  * "methods(Symbol)"
  * "methods(Thing)"
  * "methods(Type)"

For the programmer
==================

The object methods, is a method function with a single argument.

printing to the screen
**********************

Use the operator <<, to print something to the screen.
+-------------------------------+
|i1 : << 2^100                  |
|1267650600228229401496703205376|
|o1 = stdio                     |
|                               |
|o1 : File                      |
+-------------------------------+
Notice that the value returned is the standard input output file stdio.
We can also use <<, as a binary operator to print explicitly
to this file, and the output will appear on the screen.
+-------------------------------+
|i2 : stdio << 2^100            |
|1267650600228229401496703205376|
|o2 = stdio                     |
|                               |
|o2 : File                      |
+-------------------------------+
The associativity of the operator <<, during parsing is arranged so
that the following code will work in a useful way.
+----------------------------------------------+
|i3 : << "The answer is " << 2^100 << ".";     |
|The answer is 1267650600228229401496703205376.|
+----------------------------------------------+
Printing works fine with nets, too.
+----------------------------------------------------+
|i4 : << "The answer is " << "aaa"||"bb"||"c" << ".";|
|The answer is aaa.                                  |
|              bb                                    |
|              c                                     |
+----------------------------------------------------+
In the presence of nets, which are used whenever you print something that is
formatted two-dimensionally, the only correct way to terminate a line is with
endl, even though a string called newline, is
available to you.
+---------------------------------------------------+
|i5 : R = ZZ[x,y];                                  |
+---------------------------------------------------+
|i6 : f = (x+y+1)^2; g = (x-y+1)^2                  |
|                                                   |
|      2           2                                |
|o7 = x  - 2x*y + y  + 2x - 2y + 1                  |
|                                                   |
|o7 : R                                             |
+---------------------------------------------------+
|i8 : << "f = " << f << endl << "g = " << g << endl;|
|     2           2                                 |
|f = x  + 2x*y + y  + 2x + 2y + 1                   |
|     2           2                                 |
|g = x  - 2x*y + y  + 2x - 2y + 1                   |
+---------------------------------------------------+
Output is saved in a buffer until the end of the line is encountered. If nets
are not involved, you may use flush, to force the output to appear
on the screen before the end of the line is encountered.  This may be useful in
displaying some tiny indication of computational progress to the user.
+----------------------------------------+
|i9 : scan(0 .. 20, i -> << "." << flush)|
|.....................                   |
+----------------------------------------+

If long lines get displayed too slowly, such as in emacs, then the user may
choose to put a line such as truncateOutput 100 into an initialization file.
Time is still spent creating the wide output that
is eventually truncated.
+-----------------------------------------------------------+
|i10 : truncateOutput 50                                    |
+-----------------------------------------------------------+
|i11 : 41!                                                  |
|                                                           |
|o11 = 33452526613163807108170062053440751665152000000000   |
+-----------------------------------------------------------+
|i12 : 42!                                                  |
|                                                           |
|o12 = 1405006117752879898543142606244511569936384000 ...   |
+-----------------------------------------------------------+
|i13 : 43!                                                  |
|                                                           |
|o13 = 6041526306337383563735513206851399750726451200 ...   |
+-----------------------------------------------------------+
|i14 : truncateOutput infinity                              |
|                                                           |
|o14 = identity                                             |
|                                                           |
|o14 : CompiledFunction                                     |
+-----------------------------------------------------------+
|i15 : 43!                                                  |
|                                                           |
|o15 = 60415263063373835637355132068513997507264512000000000|
+-----------------------------------------------------------+

reading files
*************

Sometimes a file will contain a single expression whose value you wish to have
access to.  For example, it might be a polynomial produced by another program.
The function get, can be used to obtain the entire contents of a
file as a single string.  We illustrate this here with a file whose name is
expression.

First we create the file by writing the desired text to it.
+-----------------------------------------------------------------------------+
|i1 : fn = temporaryFileName()                                                |
|                                                                             |
|o1 = /tmp/M2-2533383-0/0                                                     |
+-----------------------------------------------------------------------------+
|i2 : fn << "z^6+3*x*z^4+6*y*z^4+3*x^2*z^2+12*x*y*z^2+12*y^2*z^2+x^3+6*x^2*y+ |
|                                                                             |
|o2 = /tmp/M2-2533383-0/0                                                     |
|                                                                             |
|o2 : File                                                                    |
|-----------------------------------------------------------------------------|
|12*x*y^2+8*y^3" << endl << close                                             |
+-----------------------------------------------------------------------------+
Now we get the contents of the file, as a single string.
+-----------------------------------------------------------------------------+
|i3 : get fn                                                                  |
|                                                                             |
|o3 = z^6+3*x*z^4+6*y*z^4+3*x^2*z^2+12*x*y*z^2+12*y^2*z^2+x^3+6*x^2*y+12*x*y^2|
|     +8*y^3                                                                  |
+-----------------------------------------------------------------------------+
This isn't quite what you want, because a string containing a description of a
polynomial is not the same as a polynomial.  We may use value, to
evaluate the string and produce the corresponding polynomial, after first
setting up a polynomial ring to contain it.
+-----------------------------------------------------------------------------+
|i4 : R = ZZ/101[x,y,z]                                                       |
|                                                                             |
|o4 = R                                                                       |
|                                                                             |
|o4 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i5 : f = value get fn                                                        |
|                                                                             |
|      6       4       4     2 2          2      2 2    3     2         2     |
|o5 = z  + 3x*z  + 6y*z  + 3x z  + 12x*y*z  + 12y z  + x  + 6x y + 12x*y  +   |
|     ------------------------------------------------------------------------|
|       3                                                                     |
|     8y                                                                      |
|                                                                             |
|o5 : R                                                                       |
+-----------------------------------------------------------------------------+
|i6 : factor f                                                                |
|                                                                             |
|       2          3                                                          |
|o6 = (z  + x + 2y)                                                           |
|                                                                             |
|o6 : Expression of class Product                                             |
+-----------------------------------------------------------------------------+
Often a file will contain code written in the Macaulay2 language. Let's create
such a file.
+--------------------------+
|i7 : fn << "sample = 2^100|
|     print sample         |
|     " << close           |
|                          |
|o7 = /tmp/M2-2533383-0/0  |
|                          |
|o7 : File                 |
+--------------------------+
Now verify that it contains the desired text with get.
+-------------------+
|i8 : get fn        |
|                   |
|o8 = sample = 2^100|
|     print sample  |
+-------------------+
To load and execute that code, use load.  This is the function you
will use most often for using bits of code you have previously written, unless
you have incorporated them into a package, in which case you would use
loadPackage.
+-------------------------------+
|i9 : load fn                   |
|1267650600228229401496703205376|
+-------------------------------+
The command needs, can be used to load a file only if it hasn't
already been loaded.
+--------------+
|i10 : needs fn|
+--------------+

For debugging or display purposes, it is sometimes useful to be able to
simulate entering the lines of a file one by one, so they appear on the screen
along with prompts and output lines.  One may use input, for that.

There are other ways to manipulate the contents of a file with multiple lines.
First, let's use peek, to observe the extent of this string
returned by get.

+---------------------+
|i11 : peek get fn    |
|                     |
|o11 = "sample = 2^100|
|      print sample   |
|      "              |
+---------------------+
The resulting string has newlines in it; we can use lines, to
break it apart into a list of strings, with one row in each string.
+------------------------------------+
|i12 : lines get fn                  |
|                                    |
|o12 = {sample = 2^100, print sample}|
|                                    |
|o12 : List                          |
+------------------------------------+
We may use peek, to observe the extent of these strings.
+----------------------------------------+
|i13 : peek lines get fn                 |
|                                        |
|o13 = {"sample = 2^100", "print sample"}|
+----------------------------------------+
We could even use stack, to assemble the lines of the file into a
net.
+------------------------+
|i14 : stack lines get fn|
|                        |
|o14 = sample = 2^100    |
|      print sample      |
+------------------------+
Now let's remove that file.
+-------------------+
|i15 : removeFile fn|
+-------------------+

getting input from the user
***************************

The function read, can be used to prompt the user and obtain a line
of input as a string.  In response to the prompt, the user enters sample and
press return.
+-----------------------------------+
|i1 : filename = read "file name : "|
|file name : sample                 |
|                                   |
|o1 = sample                        |
+-----------------------------------+
Let's use peek, to verify that this string contains no newline
characters.
+------------------+
|i2 : peek filename|
|                  |
|o2 = "sample"     |
+------------------+
If necessary, we may use value, to evaluate the string provided by
the user.  In this example, we enter (x+y)^2 in response to the prompt.
+-----------------------------+
|i3 : R = ZZ[x,y];            |
+-----------------------------+
|i4 : s = read "polynomial : "|
|polynomial : (x+y)^2         |
|                             |
|o4 = (x+y)^2                 |
+-----------------------------+
|i5 : value s                 |
|                             |
|      2           2          |
|o5 = x  + 2x*y + y           |
|                             |
|o5 : R                       |
+-----------------------------+

creating and writing files
**************************

We can print to a file in essentially the same way we print to the screen. In
the simplest case, we create the entire file with one command; we give the file
name as the initial left hand operand of <<, and we close the file
with close.  Files must be closed before they can be used for
something else.
+-----------------------------------------+
|i1 : "testfile" << 2^100 << endl << close|
|                                         |
|o1 = testfile                            |
|                                         |
|o1 : File                                |
+-----------------------------------------+
|i2 : value get "testfile"                |
|                                         |
|o2 = 1267650600228229401496703205376     |
+-----------------------------------------+
More complicated files may require printing to the file multiple times.  One
way to handle this is to assign the open file created the first time we use
<<, to a variable, so we can use it for subsequent print operations
and for closing the file.
+--------------------------+
|i3 : f = "testfile" << "" |
|                          |
|o3 = testfile             |
|                          |
|o3 : File                 |
+--------------------------+
|i4 : f << "hi" << endl    |
|                          |
|o4 = testfile             |
|                          |
|o4 : File                 |
+--------------------------+
|i5 : f << "ho" << endl    |
|                          |
|o5 = testfile             |
|                          |
|o5 : File                 |
+--------------------------+
|i6 : f << close           |
|                          |
|o6 = testfile             |
|                          |
|o6 : File                 |
+--------------------------+
|i7 : get "testfile"       |
|                          |
|o7 = hi                   |
|     ho                   |
+--------------------------+
|i8 : removeFile "testfile"|
+--------------------------+

saving polynomials and matrices in files
****************************************

Use the function toString, to convert polynomials, matrices,
and other mathematical objects to a linear format that can be saved in a file.
+-----------------------------------------------------------------------------+
|i1 : R = QQ[x..z]                                                            |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : p = (x-y-1)^3                                                           |
|                                                                             |
|      3     2        2    3     2            2                               |
|o2 = x  - 3x y + 3x*y  - y  - 3x  + 6x*y - 3y  + 3x - 3y - 1                 |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+
|i3 : m = matrix {{x^2, x^2-y^2, x*y*z^7 }}                                   |
|                                                                             |
|o3 = | x2 x2-y2 xyz7 |                                                       |
|                                                                             |
|             1      3                                                        |
|o3 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i4 : M = image m                                                             |
|                                                                             |
|o4 = image | x2 x2-y2 xyz7 |                                                 |
|                                                                             |
|                             1                                               |
|o4 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+
|i5 : f = temporaryFileName()                                                 |
|                                                                             |
|o5 = /tmp/M2-2533719-0/0                                                     |
+-----------------------------------------------------------------------------+
|i6 : f << toString (p,m,M) << close                                          |
|                                                                             |
|o6 = /tmp/M2-2533719-0/0                                                     |
|                                                                             |
|o6 : File                                                                    |
+-----------------------------------------------------------------------------+
|i7 : get f                                                                   |
|                                                                             |
|o7 = (x^3-3*x^2*y+3*x*y^2-y^3-3*x^2+6*x*y-3*y^2+3*x-3*y-1,matrix {{x^2,      |
|     x^2-y^2, x*y*z^7}},image matrix {{x^2, x^2-y^2, x*y*z^7}})              |
+-----------------------------------------------------------------------------+
|i8 : (p',m',M') = value get f                                                |
|                                                                             |
|       3     2        2    3     2            2                              |
|o8 = (x  - 3x y + 3x*y  - y  - 3x  + 6x*y - 3y  + 3x - 3y - 1, | x2 x2-y2    |
|     ------------------------------------------------------------------------|
|     xyz7 |, image | x2 x2-y2 xyz7 |)                                        |
|                                                                             |
|o8 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i9 : p == p'                                                                 |
|                                                                             |
|o9 = true                                                                    |
+-----------------------------------------------------------------------------+
|i10 : m == m'                                                                |
|                                                                             |
|o10 = true                                                                   |
+-----------------------------------------------------------------------------+
|i11 : M == M'                                                                |
|                                                                             |
|o11 = true                                                                   |
+-----------------------------------------------------------------------------+
|i12 : removeFile f                                                           |
+-----------------------------------------------------------------------------+

two dimensional formatting
**************************

We have seen that nets (see Net) are potentially useful for two
dimensional formatting of output to an ascii terminal with limited graphical
ability.  We present now a few more hints about putting this idea into
practice.  Nets are used extensively in Macaulay2 for formatting, for example,
for formatting of polynomials and matrices.
+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[x,y,z];                                                      |
+-----------------------------------------------------------------------------+
|i2 : f = random(R^1,R^{5:-3})                                                |
|                                                                             |
|o2 = | 24x3-36x2y-29xy2-10y3-30x2z+19xyz-29y2z+19xz2-8yz2-22z3               |
|     ------------------------------------------------------------------------|
|     -29x3-24x2y-16xy2+34y3-38x2z+39xyz+19y2z+21xz2-47yz2-39z3               |
|     ------------------------------------------------------------------------|
|     -18x3-13x2y-15xy2+38y3-43x2z-28xyz+2y2z-47xz2+16yz2+22z3                |
|     ------------------------------------------------------------------------|
|     45x3-34x2y-47xy2-16y3-48x2z+47xyz+7y2z+19xz2+15yz2-23z3                 |
|     ------------------------------------------------------------------------|
|     39x3+43x2y-11xy2+35y3-17x2z+48xyz+11y2z+36xz2-38yz2+33z3 |              |
|                                                                             |
|             1      5                                                        |
|o2 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
Output of routines such as betti, and net, that return
nets can be easily incorporated into more complex displays using standard
operations on nets (see Net).
+----------------------------------------------------------------------+
|i3 : C = resolution cokernel f                                        |
|                                                                      |
|      1      5      9      5                                          |
|o3 = R  <-- R  <-- R  <-- R  <-- 0                                    |
|                                                                      |
|     0      1      2      3      4                                    |
|                                                                      |
|o3 : ChainComplex                                                     |
+----------------------------------------------------------------------+
|i4 : be = betti C                                                     |
|                                                                      |
|            0 1 2 3                                                   |
|o4 = total: 1 5 9 5                                                   |
|         0: 1 . . .                                                   |
|         1: . . . .                                                   |
|         2: . 5 . .                                                   |
|         3: . . 9 5                                                   |
|                                                                      |
|o4 : BettiTally                                                       |
+----------------------------------------------------------------------+
|i5 : "Betti numbers of " | net C | " are " | (net be)^2               |
|                                                                      |
|                                                               0 1 2 3|
|                                                        total: 1 5 9 5|
|                       1      5      9      5               0: 1 . . .|
|o5 = Betti numbers of R  <-- R  <-- R  <-- R  <-- 0 are     1: . . . .|
|                                                            2: . 5 . .|
|                      0      1      2      3      4         3: . . 9 5|
+----------------------------------------------------------------------+
You could even learn how to display algebraic expressions with nets.
+----------------+
|i6 : "x" | "2"^1|
|                |
|      2         |
|o6 = x          |
+----------------+
There is an easier way to display algebraic expressions, using a type of thing
called an Expression.  It allows you to set up things that
print out as powers, sums, products, matrices, and so on.  There are various
types of expression, such as Power, Sum,
Divide, Minus, and Product, that we can
use for this.
+-------------------------------+
|i7 : Divide(Minus a,b)         |
|                               |
|     -a                        |
|o7 = --                        |
|      b                        |
|                               |
|o7 : Expression of class Divide|
+-------------------------------+
|i8 : Power(Sum(3,4,5),7)       |
|                               |
|                7              |
|o8 = (3 + 4 + 5)               |
|                               |
|o8 : Expression of class Power |
+-------------------------------+
|i9 : Sum(1,2, Minus 3, 4,5)    |
|                               |
|o9 = 1 + 2 - 3 + 4 + 5         |
|                               |
|o9 : Expression of class Sum   |
+-------------------------------+
Actually, the formation of such expressions is contagious, in the sense that
the basic algebraic operations will construct expressions for you if one of
their two operands is already an expression.
+--------------------------------+
|i10 : Minus a / b               |
|                                |
|      -a                        |
|o10 = --                        |
|       b                        |
|                                |
|o10 : Expression of class Divide|
+--------------------------------+
|i11 : (Sum(3,4,5))^7            |
|                                |
|                 7              |
|o11 = (3 + 4 + 5)               |
|                                |
|o11 : Expression of class Power |
+--------------------------------+
|i12 : 1 + 2 + Minus 3 + 4 + 5   |
|                                |
|o12 = 3 - 3 + 4 + 5             |
|                                |
|o12 : Expression of class Sum   |
+--------------------------------+
In the last example above, 1 + 2 was evaluated first, so it yielded 3 but after
that the contagion set in.

The function expression, can be used to prepare things such
as polynomials for formatting using the mechanism introduced above.
+-----------------------------+
|i13 : g = (x+y)^2            |
|                             |
|       2           2         |
|o13 = x  + 2x*y + y          |
|                             |
|o13 : R                      |
+-----------------------------+
|i14 : e = expression g       |
|                             |
|       2           2         |
|o14 = x  + 2x*y + y          |
|                             |
|o14 : Expression of class Sum|
+-----------------------------+
|i15 : peek e                 |
|                             |
|           2         2       |
|o15 = Sum{x , 2x*y, y }      |
+-----------------------------+
In the example above, we see that peek, extracts only one level of
the structure.  We may use peek', to display the structure of e to
depth 2.
+-----------------------------------------------------+
|i16 : peek'(2,e)                                     |
|                                                     |
|o16 = Sum{Power{x, 2}, Product{2, x, y}, Power{y, 2}}|
+-----------------------------------------------------+
Other types of Expression, that can be used for formatting
nested lists as two dimensional arrays are MatrixExpression,
and Table.
+--------------------------------------------------------+
|i17 : Table{{1,2,3},{a,bb,ccc}}                         |
|                                                        |
|o17 = 1   2   3                                         |
|                                                        |
|      a  bb  ccc                                        |
|                                                        |
|o17 : Expression of class Table                         |
+--------------------------------------------------------+
|i18 : MatrixExpression{{1,2,3},{a,bb,ccc}}              |
|                                                        |
|o18 = | 1 2  3   |                                      |
|      | a bb ccc |                                      |
|                                                        |
|o18 : Expression of class MatrixExpression              |
+--------------------------------------------------------+
|i19 : Table{{"Example 1","Example 2"},                  |
|            {Table{{1,2},{3,4}},Table{{11,22},{3,444}}}}|
|                                                        |
|o19 = Example 1  Example 2                              |
|                                                        |
|         1  2     11   22                               |
|                                                        |
|         3  4      3  444                               |
|                                                        |
|o19 : Expression of class Table                         |
+--------------------------------------------------------+

file manipulation -- Unix file manipulation functions
*****************************************************

fileExists -- whether a file exists
***********************************

Synopsis
========

  * Usage:
        fileExists fn
  * Inputs:
      * fn, a string,
  * Outputs:
      * a Boolean value, whether a file with the filename or
        path fn exists

Description
===========

+------------------------------+
|i1 : fn = temporaryFileName() |
|                              |
|o1 = /tmp/M2-2532491-0/0      |
+------------------------------+
|i2 : fileExists fn            |
|                              |
|o2 = false                    |
+------------------------------+
|i3 : fn << "hi there" << close|
|                              |
|o3 = /tmp/M2-2532491-0/0      |
|                              |
|o3 : File                     |
+------------------------------+
|i4 : fileExists fn            |
|                              |
|o4 = true                     |
+------------------------------+
|i5 : removeFile fn            |
+------------------------------+
If fn refers to a symbolic link, then whether the file exists is determined by
the content of the link and whether there is a file with the new path
determined by it.  The presence of a symbolic link can be detected with
readlink.

For the programmer
==================

The object fileExists, is a compiled function.

isRegularFile -- whether a file is a regular file
*************************************************

Synopsis
========

  * Usage:
        isRegularFile fn
  * Inputs:
      * fn, a string, a filename or path
  * Outputs:
      * a Boolean value, whether fn is the path to a regular
        file

Description
===========

In UNIX, a regular file is one that is not special in some way.  Special files
include symbolic links and directories.  A regular file is a sequence of bytes
stored permanently in a file system.
+------------------------------+
|i1 : fn = temporaryFileName() |
|                              |
|o1 = /tmp/M2-2535481-0/0      |
+------------------------------+
|i2 : fn << "hi there" << close|
|                              |
|o2 = /tmp/M2-2535481-0/0      |
|                              |
|o2 : File                     |
+------------------------------+
|i3 : isRegularFile fn         |
|                              |
|o3 = true                     |
+------------------------------+
|i4 : removeFile fn            |
+------------------------------+

See also
========

  * isDirectory -- whether a file is a directory
  * readlink -- readlink fn

For the programmer
==================

The object isRegularFile, is a compiled function.

isDirectory -- whether a file is a directory
********************************************

Synopsis
========

  * Usage:
        isDirectory fn
  * Inputs:
      * fn, a string, a filename or path
  * Outputs:
      * a Boolean value, whether fn is the path to a directory

Description
===========

+------------------------------+
|i1 : isDirectory "."          |
|                              |
|o1 = true                     |
+------------------------------+
|i2 : fn = temporaryFileName() |
|                              |
|o2 = /tmp/M2-2532119-0/0      |
+------------------------------+
|i3 : fn << "hi there" << close|
|                              |
|o3 = /tmp/M2-2532119-0/0      |
|                              |
|o3 : File                     |
+------------------------------+
|i4 : isDirectory fn           |
|                              |
|o4 = false                    |
+------------------------------+
|i5 : removeFile fn            |
+------------------------------+

See also
========

  * isRegularFile -- whether a file is a regular file
  * readlink -- readlink fn

For the programmer
==================

The object isDirectory, is a compiled function.

fileTime -- get or set file modified time
*****************************************

Synopsis
========

  * Usage:
        fileTime s  or  fileTime(t,s)
  * Inputs:
      * t, an integer, if present, the file-modified-time will be
        set to this value
      * s, a string, the name of a file
  * Outputs:
      * an integer, the last modified date of the file with name s
  * Consequences:
      * fileTime(t,s) sets the last modified time for the file s to t, and
        returns null if no error occurs

Description
===========

The value is the number of seconds since 00:00:00 1970-01-01 UTC, the beginning
of the epoch, so the number of seconds ago a file or directory was modified may
be found by using the following code.
+---------------------------------+
|i1 : currentTime() - fileTime "."|
|                                 |
|o1 = 29                          |
+---------------------------------+

See also
========

  * currentTime -- get the current time
  * file manipulation -- Unix file manipulation
    functions

For the programmer
==================

The object fileTime, is a compiled function.

copyFile(String,String)
***********************

Synopsis
========

  * Function: copyFile,
  * Usage:
        copyFile(src,dst)
  * Inputs:
      * src, the filename or path to an existing regular file
      * dst, the filename or path to the copy to be made
  * Optional inputs,:
      * UpdateOnly => a Boolean value, default value false,
        whether to copy file only if the destination file does not exist or is
        older than the source file
      * Verbose => a Boolean value, default value false,
        whether to report individual file operations
  * Consequences:
      * the file may be copied

Description
===========

+--------------------------------------------------------------------+
|i1 : src = temporaryFileName()                                      |
|                                                                    |
|o1 = /tmp/M2-2533165-0/0                                            |
+--------------------------------------------------------------------+
|i2 : dst = temporaryFileName()                                      |
|                                                                    |
|o2 = /tmp/M2-2533165-0/1                                            |
+--------------------------------------------------------------------+
|i3 : src << "hi there" << close                                     |
|                                                                    |
|o3 = /tmp/M2-2533165-0/0                                            |
|                                                                    |
|o3 : File                                                           |
+--------------------------------------------------------------------+
|i4 : copyFile(src,dst,Verbose=>true)                                |
| -- copying: /tmp/M2-2533165-0/0 -> /tmp/M2-2533165-0/1             |
+--------------------------------------------------------------------+
|i5 : get dst                                                        |
|                                                                    |
|o5 = hi there                                                       |
+--------------------------------------------------------------------+
|i6 : copyFile(src,dst,Verbose=>true,UpdateOnly => true)             |
| -- skipping: /tmp/M2-2533165-0/0 not newer than /tmp/M2-2533165-0/1|
+--------------------------------------------------------------------+
|i7 : src << "ho there" << close                                     |
|                                                                    |
|o7 = /tmp/M2-2533165-0/0                                            |
|                                                                    |
|o7 : File                                                           |
+--------------------------------------------------------------------+
|i8 : copyFile(src,dst,Verbose=>true,UpdateOnly => true)             |
| -- skipping: /tmp/M2-2533165-0/0 not newer than /tmp/M2-2533165-0/1|
+--------------------------------------------------------------------+
|i9 : get dst                                                        |
|                                                                    |
|o9 = hi there                                                       |
+--------------------------------------------------------------------+
|i10 : removeFile src                                                |
+--------------------------------------------------------------------+
|i11 : removeFile dst                                                |
+--------------------------------------------------------------------+

See also
========

  * copyDirectory
  * symlinkDirectory -- make
    symbolic links for all files in a directory tree

Ways to use this method:
========================

  * copyFile(String,String)

moveFile(String,String)
***********************

Synopsis
========

  * Function: moveFile,
  * Usage:
        moveFile(src,dst)
  * Inputs:
      * src, the filename or path to an existing file
      * dst, the new filename or path to a location (on the same file system).
        Omit this argument and an appropriately numbered backup filename will
        be invented.
  * Optional inputs,:
      * Verbose => a Boolean value, default value false,
        whether to report individual file operations
  * Outputs:
      * the name of the backup file if one was created, or null,
  * Consequences:
      * the file will be moved by creating a new link to the file and removing
        the old one

Description
===========

+----------------------------------------------------+
|i1 : src = temporaryFileName()                      |
|                                                    |
|o1 = /tmp/M2-2532598-0/0                            |
+----------------------------------------------------+
|i2 : dst = temporaryFileName()                      |
|                                                    |
|o2 = /tmp/M2-2532598-0/1                            |
+----------------------------------------------------+
|i3 : src << "hi there" << close                     |
|                                                    |
|o3 = /tmp/M2-2532598-0/0                            |
|                                                    |
|o3 : File                                           |
+----------------------------------------------------+
|i4 : moveFile(src,dst,Verbose=>true)                |
|--moving: /tmp/M2-2532598-0/0 -> /tmp/M2-2532598-0/1|
+----------------------------------------------------+
|i5 : get dst                                        |
|                                                    |
|o5 = hi there                                       |
+----------------------------------------------------+
|i6 : bak = moveFile(dst,Verbose=>true)              |
|--backup file created: /tmp/M2-2532598-0/1.bak      |
|                                                    |
|o6 = /tmp/M2-2532598-0/1.bak                        |
+----------------------------------------------------+
|i7 : removeFile bak                                 |
+----------------------------------------------------+

See also
========

  * copyFile

Ways to use this method:
========================

  * "moveFile(String)"
  * moveFile(String,String)

removeFile -- remove a file
***************************

Synopsis
========

  * Usage:
        removeFile f
  * Inputs:
      * f, a string,
  * Consequences:
      * the file reachable by the path f is removed

Description
===========

Under a unix system such as GNU/Linux, what really happens is that the link to
the file specified by f is removed.  The file itself disappears after all the
links to it are removed.  See linkFile.

For the programmer
==================

The object removeFile, is a compiled function.

findFiles -- find files recursively
***********************************

Synopsis
========

  * Usage:
        findFiles p
  * Inputs:
      * p, a string, or a list, a directory or list
        of directories
  * Optional inputs,:
      * Exclude => ..., default value {}, a list of strings, regarded as
        regular expressions; files found whose paths have base filenames
        matching one of these regular expressions will be excluded from the
        results
      * FollowLinks => a Boolean value, default value false,
        whether to follow symbolic links to directories and to report on files
        found there
  * Outputs:
      * a list of paths to files found in the directory tree(s) rooted at the
        locations(s) specified by p

Ways to use findFiles:
======================

  * "findFiles(List)"
  * "findFiles(String)"

For the programmer
==================

The object findFiles, is a method function with options.

symlinkFile -- make a symbolic link to a file
*********************************************

Synopsis
========

  * Usage:
        symlinkFile(src,dst)
  * Inputs:
      * src, a string,
      * dst, a string,
  * Consequences:
      * a symbolic link at the location in the directory tree specified by dst
        is created, pointing to src

Description
===========

+-----------------------------+
|i1 : fn = temporaryFileName()|
|                             |
|o1 = /tmp/M2-2533535-0/0     |
+-----------------------------+
|i2 : symlinkFile("qwert", fn)|
+-----------------------------+
|i3 : fileExists fn           |
|                             |
|o3 = false                   |
+-----------------------------+
|i4 : readlink fn             |
|                             |
|o4 = qwert                   |
+-----------------------------+
|i5 : removeFile fn           |
+-----------------------------+

See also
========

  * symlinkDirectory -- make
    symbolic links for all files in a directory tree

For the programmer
==================

The object symlinkFile, is a compiled function.

linkFile(String,String) -- make a new link to a file
****************************************************

Synopsis
========

  * Function: linkFile,
  * Usage:
        linkFile(o,n)
  * Inputs:
      * o, a string, the path to an existing file
      * n, a string, a new path to the file
  * Consequences:
      * a new link n is made to the existing file reachable using the path o

See also
========

  * moveFile
  * copyFile

Ways to use this method:
========================

  * linkFile(String,String) -- make a new
    link to a file

readlink -- readlink fn
***********************

Synopsis
========

  * Usage:
        read the contents of a symbolic link
  * Inputs:
      * fn, a string, a filename or path to a file
  * Outputs:
      * a Boolean value, whether fn is the path to a symbolic
        link

Description
===========

+-----------------------------+
|i1 : p = temporaryFileName ()|
|                             |
|o1 = /tmp/M2-2534630-0/0     |
+-----------------------------+
|i2 : symlinkFile ("foo", p)  |
+-----------------------------+
|i3 : readlink p              |
|                             |
|o3 = foo                     |
+-----------------------------+
|i4 : removeFile p            |
+-----------------------------+

For the programmer
==================

The object readlink, is a compiled function.

mkdir
*****

Synopsis
========

  * Usage:
        mkdir p
  * Inputs:
      * p, a string, a path to a directory to be made
  * Consequences:
      * a directory will be created at the path p

Description
===========

Only one directory will be made, so the components of the path p other than the
last must already exist.

+--------------------------------------------+
|i1 : p = temporaryFileName() | "/"          |
|                                            |
|o1 = /tmp/M2-2532861-0/0/                   |
+--------------------------------------------+
|i2 : mkdir p                                |
+--------------------------------------------+
|i3 : isDirectory p                          |
|                                            |
|o3 = true                                   |
+--------------------------------------------+
|i4 : (fn = p | "foo") << "hi there" << close|
|                                            |
|o4 = /tmp/M2-2532861-0/0/foo                |
|                                            |
|o4 : File                                   |
+--------------------------------------------+
|i5 : get fn                                 |
|                                            |
|o5 = hi there                               |
+--------------------------------------------+
|i6 : removeFile fn                          |
+--------------------------------------------+
|i7 : removeDirectory p                      |
+--------------------------------------------+

A filename starting with ~/ will have the tilde replaced by the home directory.

See also
========

  * makeDirectory -- make a directory

For the programmer
==================

The object mkdir, is a compiled function.

makeDirectory(String) -- make a directory
*****************************************

Synopsis
========

  * Function: makeDirectory,
  * Usage:
        makeDirectory dir
  * Inputs:
      * dir, a string, a path to the desired directory
  * Outputs:
      * a string, the name of the newly made directory
  * Consequences:
      * the directory is made, with as many new path components as needed

Description
===========

+-----------------------------------+
|i1 : dir = temporaryFileName()     |
|                                   |
|o1 = /tmp/M2-2532831-0/0           |
+-----------------------------------+
|i2 : makeDirectory (dir|"/a/b/c")  |
|                                   |
|o2 = /tmp/M2-2532831-0/0/a/b/c     |
+-----------------------------------+
|i3 : removeDirectory (dir|"/a/b/c")|
+-----------------------------------+
|i4 : removeDirectory (dir|"/a/b")  |
+-----------------------------------+
|i5 : removeDirectory (dir|"/a")    |
+-----------------------------------+

A filename starting with ~/ will have the tilde replaced by the home directory.

See also
========

  * mkdir

Ways to use this method:
========================

  * makeDirectory(String) -- make a directory

copyDirectory(String,String)
****************************

Synopsis
========

  * Function: copyDirectory,
  * Usage:
        copyDirectory(src,dst)
  * Inputs:
      * src, a string,
      * dst, a string,
  * Optional inputs,:
      * Exclude => ..., default value "\\.~[0-9.]+~$", a string containing a
        regular expression, or a list of such strings.  If the base part of the
        name of a file in the source tree matches one of the regular
        expressions, then no link to it is created
      * UpdateOnly => a Boolean value, default value false,
        whether to copy files only if the target file does not exist or is
        older than the source file
      * FollowLinks => a Boolean value, default value false,
        whether to follow symbolic links in the source tree to directories
      * Verbose => a Boolean value, default value false,
        whether to report individual file operations
  * Consequences:
      * a copy of the directory tree rooted at src is created, rooted at dst

Description
===========

+-----------------------------------------------------------------------------+
|i1 : src = temporaryFileName() | "/"                                         |
|                                                                             |
|o1 = /tmp/M2-2533511-0/0/                                                    |
+-----------------------------------------------------------------------------+
|i2 : dst = temporaryFileName() | "/"                                         |
|                                                                             |
|o2 = /tmp/M2-2533511-0/1/                                                    |
+-----------------------------------------------------------------------------+
|i3 : makeDirectory (src|"a/")                                                |
|                                                                             |
|o3 = /tmp/M2-2533511-0/0/a/                                                  |
+-----------------------------------------------------------------------------+
|i4 : makeDirectory (src|"b/")                                                |
|                                                                             |
|o4 = /tmp/M2-2533511-0/0/b/                                                  |
+-----------------------------------------------------------------------------+
|i5 : makeDirectory (src|"b/c/")                                              |
|                                                                             |
|o5 = /tmp/M2-2533511-0/0/b/c/                                                |
+-----------------------------------------------------------------------------+
|i6 : src|"a/f" << "hi there" << close                                        |
|                                                                             |
|o6 = /tmp/M2-2533511-0/0/a/f                                                 |
|                                                                             |
|o6 : File                                                                    |
+-----------------------------------------------------------------------------+
|i7 : src|"a/g" << "hi there" << close                                        |
|                                                                             |
|o7 = /tmp/M2-2533511-0/0/a/g                                                 |
|                                                                             |
|o7 : File                                                                    |
+-----------------------------------------------------------------------------+
|i8 : src|"b/c/g" << "ho there" << close                                      |
|                                                                             |
|o8 = /tmp/M2-2533511-0/0/b/c/g                                               |
|                                                                             |
|o8 : File                                                                    |
+-----------------------------------------------------------------------------+
|i9 : stack findFiles src                                                     |
|                                                                             |
|o9 = /tmp/M2-2533511-0/0/                                                    |
|     /tmp/M2-2533511-0/0/a/                                                  |
|     /tmp/M2-2533511-0/0/a/g                                                 |
|     /tmp/M2-2533511-0/0/a/f                                                 |
|     /tmp/M2-2533511-0/0/b/                                                  |
|     /tmp/M2-2533511-0/0/b/c/                                                |
|     /tmp/M2-2533511-0/0/b/c/g                                               |
+-----------------------------------------------------------------------------+
|i10 : copyDirectory(src,dst,Verbose=>true)                                   |
| -- copying: /tmp/M2-2533511-0/0/a/g -> /tmp/M2-2533511-0/1/a/g              |
| -- copying: /tmp/M2-2533511-0/0/a/f -> /tmp/M2-2533511-0/1/a/f              |
| -- copying: /tmp/M2-2533511-0/0/b/c/g -> /tmp/M2-2533511-0/1/b/c/g          |
+-----------------------------------------------------------------------------+
|i11 : copyDirectory(src,dst,Verbose=>true,UpdateOnly => true)                |
| -- skipping: /tmp/M2-2533511-0/0/a/g not newer than /tmp/M2-2533511-0/1/a/g |
| -- skipping: /tmp/M2-2533511-0/0/a/f not newer than /tmp/M2-2533511-0/1/a/f |
| -- skipping: /tmp/M2-2533511-0/0/b/c/g not newer than /tmp/M2-2533511-0/1/b/|
|-----------------------------------------------------------------------------|
|c/g                                                                          |
+-----------------------------------------------------------------------------+
|i12 : stack findFiles dst                                                    |
|                                                                             |
|o12 = /tmp/M2-2533511-0/1/                                                   |
|      /tmp/M2-2533511-0/1/a/                                                 |
|      /tmp/M2-2533511-0/1/a/g                                                |
|      /tmp/M2-2533511-0/1/a/f                                                |
|      /tmp/M2-2533511-0/1/b/                                                 |
|      /tmp/M2-2533511-0/1/b/c/                                               |
|      /tmp/M2-2533511-0/1/b/c/g                                              |
+-----------------------------------------------------------------------------+
|i13 : get (dst|"b/c/g")                                                      |
|                                                                             |
|o13 = ho there                                                               |
+-----------------------------------------------------------------------------+
Now we remove the files and directories we created.
+-------------------------------------------------------------------------+
|i14 : rm = d -> if isDirectory d then removeDirectory d else removeFile d|
|                                                                         |
|o14 = rm                                                                 |
|                                                                         |
|o14 : FunctionClosure                                                    |
+-------------------------------------------------------------------------+
|i15 : scan(reverse findFiles src, rm)                                    |
+-------------------------------------------------------------------------+
|i16 : scan(reverse findFiles dst, rm)                                    |
+-------------------------------------------------------------------------+

See also
========

  * symlinkDirectory -- make
    symbolic links for all files in a directory tree

Ways to use this method:
========================

  * copyDirectory(String,String)

removeDirectory -- remove a directory
*************************************

Synopsis
========

  * Usage:
        removeDirectory dir
  * Inputs:
      * dir, a string, a filename or path to a directory
  * Consequences:
      * the directory is removed

Description
===========

+------------------------------+
|i1 : dir = temporaryFileName()|
|                              |
|o1 = /tmp/M2-2532909-0/0      |
+------------------------------+
|i2 : makeDirectory dir        |
|                              |
|o2 = /tmp/M2-2532909-0/0      |
+------------------------------+
|i3 : readDirectory dir        |
|                              |
|o3 = {.., .}                  |
|                              |
|o3 : List                     |
+------------------------------+
|i4 : removeDirectory dir      |
+------------------------------+

See also
========

  * readDirectory -- read the contents of a directory
  * makeDirectory -- make a directory

For the programmer
==================

The object removeDirectory, is a compiled function.

symlinkDirectory(String,String) -- make symbolic links for all files in a directory tree
****************************************************************************************

Synopsis
========

  * Function: symlinkDirectory,
  * Usage:
        symlinkDirectory(src,dst)
  * Inputs:
      * src, the path to an existing directory, the root of the source
        directory tree
      * dst, a path to the root of the destination directory tree, which may
        not exist yet
  * Optional inputs,:
      * Exclude => ..., default value "\\.~[0-9.]+~$", a string containing a
        regular expression, or a list of such strings.  If the base part of the
        name of a file in the source tree matches one of the regular
        expressions, then no link to it is created
      * Undo => a Boolean value, default value false, whether
        to undo the symbolic links created in a previous application of this
        function.  The directories in the destination directory tree will
        remain.
      * FollowLinks => a Boolean value, default value false,
        whether to follow symbolic links in the source tree to directories
      * Verbose => a Boolean value, default value false,
        whether to report the creation or deletion of each symbolic link
  * Consequences:
      * The directory tree rooted at src is duplicated by a directory tree
        rooted at dst.  The files in the source tree are represented by
        relative symbolic links in the destination tree to the original files
        in the source tree.

Description
===========

+-------------------------------------------------------------+
|i1 : src = temporaryFileName() | "/"                         |
|                                                             |
|o1 = /tmp/M2-2533433-0/0/                                    |
+-------------------------------------------------------------+
|i2 : dst = temporaryFileName() | "/"                         |
|                                                             |
|o2 = /tmp/M2-2533433-0/1/                                    |
+-------------------------------------------------------------+
|i3 : makeDirectory (src|"a/")                                |
|                                                             |
|o3 = /tmp/M2-2533433-0/0/a/                                  |
+-------------------------------------------------------------+
|i4 : makeDirectory (src|"b/")                                |
|                                                             |
|o4 = /tmp/M2-2533433-0/0/b/                                  |
+-------------------------------------------------------------+
|i5 : makeDirectory (src|"b/c/")                              |
|                                                             |
|o5 = /tmp/M2-2533433-0/0/b/c/                                |
+-------------------------------------------------------------+
|i6 : src|"a/f" << "hi there" << close                        |
|                                                             |
|o6 = /tmp/M2-2533433-0/0/a/f                                 |
|                                                             |
|o6 : File                                                    |
+-------------------------------------------------------------+
|i7 : src|"a/g" << "hi there" << close                        |
|                                                             |
|o7 = /tmp/M2-2533433-0/0/a/g                                 |
|                                                             |
|o7 : File                                                    |
+-------------------------------------------------------------+
|i8 : src|"b/c/g" << "ho there" << close                      |
|                                                             |
|o8 = /tmp/M2-2533433-0/0/b/c/g                               |
|                                                             |
|o8 : File                                                    |
+-------------------------------------------------------------+
|i9 : symlinkDirectory(src,dst,Verbose=>true)                 |
|--symlinking: ../../0/a/g -> /tmp/M2-2533433-0/1/a/g         |
|--symlinking: ../../0/a/f -> /tmp/M2-2533433-0/1/a/f         |
|--symlinking: ../../../0/b/c/g -> /tmp/M2-2533433-0/1/b/c/g  |
+-------------------------------------------------------------+
|i10 : get (dst|"b/c/g")                                      |
|                                                             |
|o10 = ho there                                               |
+-------------------------------------------------------------+
|i11 : symlinkDirectory(src,dst,Verbose=>true,Undo=>true)     |
|--unsymlinking: ../../0/a/g -> /tmp/M2-2533433-0/1/a/g       |
|--unsymlinking: ../../0/a/f -> /tmp/M2-2533433-0/1/a/f       |
|--unsymlinking: ../../../0/b/c/g -> /tmp/M2-2533433-0/1/b/c/g|
+-------------------------------------------------------------+
Now we remove the files and directories we created.
+-------------------------------------------------------------------------+
|i12 : rm = d -> if isDirectory d then removeDirectory d else removeFile d|
|                                                                         |
|o12 = rm                                                                 |
|                                                                         |
|o12 : FunctionClosure                                                    |
+-------------------------------------------------------------------------+
|i13 : scan(reverse findFiles src, rm)                                    |
+-------------------------------------------------------------------------+
|i14 : scan(reverse findFiles dst, rm)                                    |
+-------------------------------------------------------------------------+

See also
========

  * symlinkFile -- make a symbolic link to a file
  * copyDirectory

Ways to use this method:
========================

  * symlinkDirectory(String,String)
    -- make symbolic links for all files
    in a directory tree

readDirectory -- read the contents of a directory
*************************************************

Synopsis
========

  * Usage:
        readDirectory dir
  * Inputs:
      * dir, a string, a filename or path to a directory
  * Outputs:
      * a list, the list of filenames stored in the directory

Description
===========

+----------------------------------------------------+
|i1 : dir = temporaryFileName()                      |
|                                                    |
|o1 = /tmp/M2-2534031-0/0                            |
+----------------------------------------------------+
|i2 : makeDirectory dir                              |
|                                                    |
|o2 = /tmp/M2-2534031-0/0                            |
+----------------------------------------------------+
|i3 : (fn = dir | "/" | "foo") << "hi there" << close|
|                                                    |
|o3 = /tmp/M2-2534031-0/0/foo                        |
|                                                    |
|o3 : File                                           |
+----------------------------------------------------+
|i4 : readDirectory dir                              |
|                                                    |
|o4 = {.., foo, .}                                   |
|                                                    |
|o4 : List                                           |
+----------------------------------------------------+
|i5 : removeFile fn                                  |
+----------------------------------------------------+
|i6 : removeDirectory dir                            |
+----------------------------------------------------+

See also
========

  * removeDirectory -- remove a directory
  * removeFile -- remove a file
  * makeDirectory -- make a directory

For the programmer
==================

The object readDirectory, is a compiled function.

realpath -- convert a filename to one passing through no symbolic links
***********************************************************************

Synopsis
========

  * Usage:
        realpath fn
  * Inputs:
      * fn, a string, a filename, or path to a file
  * Outputs:
      * a string, a pathname to fn passing through no symbolic
        links, and ending with a slash if fn refers to a directory

Description
===========

+---------------------------------+
|i1 : realpath "."                |
|                                 |
|o1 = /tmp/M2-2531735-0/85-rundir/|
+---------------------------------+
|i2 : p = temporaryFileName()     |
|                                 |
|o2 = /tmp/M2-2534678-0/0         |
+---------------------------------+
|i3 : q = temporaryFileName()     |
|                                 |
|o3 = /tmp/M2-2534678-0/1         |
+---------------------------------+
|i4 : symlinkFile(p,q)            |
+---------------------------------+
|i5 : p << close                  |
|                                 |
|o5 = /tmp/M2-2534678-0/0         |
|                                 |
|o5 : File                        |
+---------------------------------+
|i6 : readlink q                  |
|                                 |
|o6 = /tmp/M2-2534678-0/0         |
+---------------------------------+
|i7 : realpath q                  |
|                                 |
|o7 = /tmp/M2-2534678-0/0         |
+---------------------------------+
|i8 : removeFile p                |
+---------------------------------+
|i9 : removeFile q                |
+---------------------------------+

The empty string is interpreted as a reference to the current directory.

+----------------------------------+
|i10 : realpath ""                 |
|                                  |
|o10 = /tmp/M2-2531735-0/85-rundir/|
+----------------------------------+

Caveat
======

Every component of the path must exist in the file system and be accessible to
the user. Terminal slashes will be dropped.  Warning: under most operating
systems, the value returned is an absolute path (one starting at the root of
the file system), but under Solaris, this system call may, in certain
circumstances, return a relative path when given a relative path.

See also
========

  * readlink -- readlink fn

For the programmer
==================

The object realpath, is a compiled function.

temporaryFileName -- make a temporary file name
***********************************************

Synopsis
========

  * Usage:
        temporaryFileName()
  * Outputs:
      * a unique temporary file name.

Description
===========

The file name is so unique that even with various suffixes appended, no
collision with existing files will occur.  The files will be removed when the
program terminates, unless it terminates as the result of an error.
+-----------------------------------+
|i1 : temporaryFileName () | ".tex" |
|                                   |
|o1 = /tmp/M2-2535440-0/0.tex       |
+-----------------------------------+
|i2 : temporaryFileName () | ".html"|
|                                   |
|o2 = /tmp/M2-2535440-0/1.html      |
+-----------------------------------+

This function will work under Unix, and also under Windows if you have a
directory on the same drive called /tmp.

If the name of the temporary file will be given to an external program, it may
be necessary to concatenate it with rootPath, or rootURI,
to enable the external program to find the file.

The temporary file name is derived from the value of the environment variable
TMPDIR, if it has one.

If fork, is used, then the parent and child Macaulay2 processes
will each remove their own temporary files upon termination, with the parent
removing any files created before fork, was called.

See also
========

  * File -- the class of all files
  * rootPath
  * rootURI

For the programmer
==================

The object temporaryFileName, is a function closure.

communicating with programs
***************************

The most naive way to interact with another program is simply to run it, let it
communicate directly with the user, and wait for it to finish.  This is done
with the run, command.
+-----------------------------------------------------------------------------+
|i1 : run "uname -a"                                                          |
|Linux mixtuppa 6.8.0-47-generic #47-Ubuntu SMP PREEMPT_DYNAMIC Fri Sep 27    |
|                                                                             |
|o1 = 0                                                                       |
|-----------------------------------------------------------------------------|
|21:40:26 UTC 2024 x86_64 x86_64 x86_64 GNU/Linux                             |
+-----------------------------------------------------------------------------+
To run a program and provide it with input, one way is use the operator
<<, with a file name whose first character is an exclamation point; the
rest of the file name will be taken as the command to run, as in the following
example.
+-----------------------------------------------------+
|i2 : "!grep a" << " ba \n bc \n ad \n ef \n" << close|
| ba                                                  |
| ad                                                  |
|                                                     |
|o2 = !grep a                                         |
|                                                     |
|o2 : File                                            |
+-----------------------------------------------------+
More often, one wants to write Macaulay2 code to obtain and manipulate the
output from the other program.  If the program requires no input data, then we
can use get, with a file name whose first character is an
exclamation point.  In the following example, we also peek at the string to see
whether it includes a newline character.
+----------------------------------------------------------------------------+
|i3 : peek get "!uname -a"                                                   |
|                                                                            |
|o3 = "Linux mixtuppa 6.8.0-47-generic #47-Ubuntu SMP PREEMPT_DYNAMIC Fri Sep|
|     "                                                                      |
|     27 21:40:26 UTC 2024 x86_64 x86_64 x86_64 GNU/Linux                    |
+----------------------------------------------------------------------------+
Bidirectional communication with a program is also possible.  We use
openInOut, to create a file that serves as a bidirectional
connection to a program.  That file is called an input output file.  In this
example we open a connection to the unix utility egrep and use it to locate the
symbol names in Macaulay2 that begin with in.
+--------------------------------------------------------+
|i4 : f = openInOut "!egrep '^in'"                       |
|                                                        |
|o4 = !egrep '^in'                                       |
|                                                        |
|o4 : File                                               |
+--------------------------------------------------------+
|i5 : scan(keys Core.Dictionary, key -> f << key << endl)|
+--------------------------------------------------------+
|i6 : f << closeOut                                      |
|                                                        |
|o6 = !egrep '^in'                                       |
|                                                        |
|o6 : File                                               |
+--------------------------------------------------------+
|i7 : get f                                              |
|                                                        |
|o7 = interpreterDepth                                   |
|     infoHelp                                           |
|     integrate                                          |
|     inducedMap                                         |
|     installMethod                                      |
|     insert                                             |
|     info                                               |
|     interval                                           |
|     intersect                                          |
|     inversePermutation                                 |
|     inverseErf                                         |
|     index                                              |
|     indexComponents                                    |
|     installAssignmentMethod                            |
|     infinity                                           |
|     intersection                                       |
|     indices                                            |
|     incomparable                                       |
|     indeterminate                                      |
|     in                                                 |
|     inverseRegularizedBeta                             |
|     independentSets                                    |
|     installPackage                                     |
|     instance                                           |
|     installedPackages                                  |
|     input                                              |
|     inducesWellDefinedMap                              |
|     inverseRegularizedGamma                            |
|     inverse                                            |
|     installHilbertFunction                             |
|     instances                                          |
+--------------------------------------------------------+
With this form of bidirectional communication there is always a danger of
blocking, because the buffers associated with the communication channels
(pipes) typically hold only 4096 bytes.  In this example we succeeded because
the entire output from egrep was smaller than 4096 bytes.  In general, one
should be careful to arrange things so that the two programs take turns using
the communication channel, so that when one is writing data, the other is
reading it.

A useful function in this connection is isReady,
which will tell you whether an input file has any input available for reading,
or whether it has arrived at the end.  We illustrate it in the following
example by simulating a computation that takes 5 seconds to complete, printing
one dot per second while waiting.
+-------------------------------------------------------+
|i8 : f = openIn "!sleep 5; echo -n the answer is 4"    |
|                                                       |
|o8 = !sleep 5; echo -n the answer is 4                 |
|                                                       |
|o8 : File                                              |
+-------------------------------------------------------+
|i9 : isReady f                                         |
|                                                       |
|o9 = false                                             |
+-------------------------------------------------------+
|i10 : while not isReady f do (sleep 1; << "." << flush)|
|......                                                 |
+-------------------------------------------------------+
|i11 : read f                                           |
|                                                       |
|o11 = the answer is 4                                  |
+-------------------------------------------------------+
|i12 : isReady f                                        |
|                                                       |
|o12 = true                                             |
+-------------------------------------------------------+
|i13 : atEndOfFile f                                    |
|                                                       |
|o13 = true                                             |
+-------------------------------------------------------+
|i14 : close f                                          |
|                                                       |
|o14 = !sleep 5; echo -n the answer is 4                |
|                                                       |
|o14 : File                                             |
+-------------------------------------------------------+
We also allow for bidirectional communication through sockets over the
internet.  See openInOut, and openListener,
or the next section.

Another useful function is wait, which can be used to wait for
input to be available from any of a list of input files.

using sockets
*************

It's easy to use sockets as though they were files.  Simply replace the file
name by a string of the form $host:service where host is the name of IP number
of host to contact, and service is the port number or name to use.  If service
is omitted, then port 2500 is used.  If host is omitted, then an incoming
connection will be listened for.

The following code will illustrate two-way communication using sockets similar
to the interaction used by web servers, and you may try it out on your machine,
unless a firewall prevents it.

if (pid = fork()) == 0 then (
     try "$:7500" << "hi there" << close;
     exit 0;
     )
sleep 2
get "$localhost:7500"
wait pid

The code uses fork, to create a separate process that will listen
for a connection on port 7500 and then send us a message.  The sleep,
command pauses for a while to make sure the child process has had time
to start listening. Then we use an ordinary input command, namely get,
to obtain the message. Finally, we wait, for the child
process to finish, as we should.

See also
========

  * openInOut -- open an input output file
  * openListener -- open a port for listening
  * getWWW -- get a web page

packages -- Macaulay2 packages
******************************

A package is a body of Macaulay2 source code devoted to a particular topic.
Many packages are distributed with Macaulay2, and others are available from the
author's homepage.

To load a package, say FirstPackage, enter:

loadPackage "FirstPackage"

or

needsPackage "FirstPackage"

For technical information about packages, see Package.

Macaulay2 searches for the file FirstPackage.m2 on your search path.
The packages provided with Macaulay2 are on your search path, as is your
current working directory.

Using existing packages
-----------------------

  * loadPackage -- load a package
  * needsPackage -- load a package if not already loaded
  * dismiss -- dismiss a package
  * importFrom -- import symbols to the current private
    dictionary
  * loadedPackages -- the list of loaded packages

Creating a new package
----------------------

  * creating a package
  * newPackage -- the preamble of a package
  * installPackage -- load and install a package and its
    documentation
  * uninstallPackage -- uninstall a package and remove
    its documentation

Writing documentation for a package
-----------------------------------

  * writing documentation
  * doc (SimpleDoc) -- a simple documentation function

Debugging a package
-------------------

  * the debugger
  * debug(Package) -- open the private dictionary of a package
  * check(Package) -- perform tests of a package

Documentation for the packages provided with Macaulay2 is already installed. To
install documentation for another package, use installPackage.

installPackage FirstPackage

You may see what packages have been loaded with the variable
loadedPackages.

See also
========

  * creating a package
  * packages provided with Macaulay2

Accessing packages

Interacting with packages

Miscellaneous nodes

Package -- the class of all packages
************************************

Description
===========

See packages, for an overview about using and writing Macaulay2
packages.

Available packages:
-------------------

  * packages provided with Macaulay2
  * The directory containing the packages is common/share/Macaulay2/ (see
    common/share/Macaulay2/ )

Functions useful when using packages,:
------------------------------------------------------

  * needsPackage -- load a package if not already loaded
  * loadPackage -- load a package
  * installPackage -- load and install a package and its
    documentation
  * check -- perform tests of a package
  * debug -- open the private dictionary of a package
  * importFrom -- import symbols to the current private
    dictionary

Functions useful when creating a package,:
--------------------------------------------------------------------

  * newPackage -- the preamble of a package
  * export -- export symbols from a package
  * exportMutable -- export mutable symbols from a
    package
  * beginDocumentation -- start documentation
    section of a package
  * document -- create a documentation node
  * TEST -- add a test for a package

Functions useful when debugging a package:
------------------------------------------

  * debugging
  * debug -- open the private dictionary of a package
  * check -- perform tests of a package

Functions that are only rarely used:
------------------------------------

  * use -- install or activate object
  * dismiss -- dismiss a package
  * exportFrom -- export symbols from a package's private
    dictionary
  * endPackage -- end a new package
  * readPackage -- read the package preamble
  * uninstallPackage -- uninstall a package and remove
    its documentation
  * makePackageIndex -- create an index of installed
    packages
  * loadedPackages -- the list of loaded packages

See also
========

  * packages -- Macaulay2 packages
  * creating a package
  * packageTemplate (SimpleDoc) -- a template for a
    package

Functions and methods returning a package:
==========================================

  * installPackage -- load and install a package and its
    documentation
  * loadPackage -- load a package
  * needsPackage -- load a package if not already loaded
  * package -- get containing package

Methods that use a package:
===========================

  * "? Package" -- see ? Symbol, -- view brief documentation of
    a symbol
  * "check(List,Package)" -- see check, -- perform tests of a
    package
  * "check(Package)" -- see check, -- perform tests of a package
  * "check(ZZ,Package)" -- see check, -- perform tests of a
    package
  * "debug(Package)" -- see debug, -- open the private dictionary
    of a package
  * "dismiss(Package)" -- see dismiss, -- dismiss a package
  * "exportFrom(Package,List)" -- see exportFrom, -- export
    symbols from a package's private dictionary
  * "exportFrom(Package,String)" -- see exportFrom, -- export
    symbols from a package's private dictionary
  * "importFrom(Package,List)" -- see importFrom, -- import
    symbols to the current private dictionary
  * "importFrom(Package,String)" -- see importFrom, -- import
    symbols to the current private dictionary
  * "installPackage(Package)" -- see installPackage, --
    load and install a package and its documentation
  * "loadPackage(Package)" -- see loadPackage, -- load a
    package
  * "methods(Package)" -- see methods, -- list methods
  * options(Package)
  * "package(Package)" -- see package, -- get containing package
  * "readPackage(Package)" -- see readPackage, -- read the
    package preamble
  * "tests(Package)" -- see tests, -- locate a package's tests
  * "tests(ZZ,Package)" -- see tests, -- locate a package's tests
  * "uninstallPackage(Package)" -- see uninstallPackage,
    -- uninstall a package and remove its documentation
  * use(Package) -- activate a previously dismissed
    package

Protected objects of class Package:
===================================

  * AssociativeAlgebras -- Noncommutative
    algebra computations
  * BernsteinSato -- algorithms for b-functions,
    local cohomology, and intersection cohomology
  * Classic -- a parser for classic Macaulay syntax
  * Complexes -- development package for beta testing
    new version of chain complexes
  * ConwayPolynomials -- database of Conway
    polynomials for use with GF
  * Core -- the core part of Macaulay2
  * Dmodules -- D-modules package collection
  * Elimination -- eliminating specified variables,
    and Sylvester resultant
  * FirstPackage -- an example Macaulay2 package
  * FourierMotzkin -- for convex hull and vertex
    enumeration
  * FourTiTwo -- Interface for 4ti2
  * GenericInitialIdeal -- find the generic
    initial ideal of a given ideal
  * HolonomicSystems -- Examples of Holonomic
    D-modules
  * IntegralClosure -- routines for integral
    closure of affine domains and ideals
  * InverseSystems -- Macaulay's Inverse Systems
  * Isomorphism -- Probabilistic test for isomorphism
  * LLLBases -- lattice reduction (Lenstra-Lenstra-Lovasz
    bases)
  * Macaulay2Doc -- Macaulay2 documentation
  * MinimalPrimes -- minimal primes and radical
    routines for ideals
  * OnlineLookup -- Look up mathematical information
    online
  * PackageCitations -- a package facilitating
    citation of Macaulay2 packages
  * Parsing -- a framework for building parsers
  * Polyhedra -- for computations with convex polyhedra,
    cones, and fans
  * PrimaryDecomposition -- primary
    decomposition and associated primes routines for ideals and modules
  * PruneComplex -- Pruning chain complexes over
    polynomial and local rings
  * ReesAlgebra -- Compute Rees algebras and their
    invariants
  * Saturation -- ideal and submodule quotient,
    saturation, and annihilator routines
  * SimpleDoc -- simpler documentation for functions and
    methods
  * SimplicialComplexes -- exploring abstract
    simplicial complexes within commutative algebra
  * TangentCone -- tangent cones
  * Text -- documentation and hypertext
  * Topcom -- interface to selected functions from topcom
    package
  * Truncations -- truncations of graded ring, ideals
    and modules
  * User (missing documentation)
  * Varieties -- affine and projective algebraic
    geometry
  * WeylAlgebras -- algorithms for D-modules

For the programmer
==================

The object Package, is a type, with ancestor
classes MutableHashTable, < HashTable
< Thing.

loadedPackages -- the list of loaded packages
*********************************************

Description
===========

The value of the variable loadedPackages is a list of the packages that have
been loaded.

+-----------------------------------------------------------------------------+
|i1 : loadedPackages                                                          |
|                                                                             |
|o1 = {PackageCitations, Varieties, Truncations, Polyhedra, Saturation,       |
|     ------------------------------------------------------------------------|
|     Elimination, Isomorphism, OnlineLookup, SimpleDoc, InverseSystems,      |
|     ------------------------------------------------------------------------|
|     ConwayPolynomials, ReesAlgebra, TangentCone, Classic, MinimalPrimes,    |
|     ------------------------------------------------------------------------|
|     PrimaryDecomposition, IntegralClosure, LLLBases, Macaulay2Doc, Core}    |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * packages provided with Macaulay2
  * dismiss -- dismiss a package
  * needsPackage -- load a package if not already loaded

For the programmer
==================

The object loadedPackages, is a list.

package -- get containing package
*********************************

Synopsis
========

  * Usage:
        package x
  * Inputs:
      * x, a thing,
  * Outputs:
      * a package, the package in which the documentation key x
        was defined

Description
===========

+-----------------+
|i1 : package sin |
|                 |
|o1 = Core        |
|                 |
|o1 : Package     |
+-----------------+
|i2 : package poly|
|                 |
|o2 = Classic     |
|                 |
|o2 : Package     |
+-----------------+

Ways to use package:
====================

  * "package(Array)"
  * "package(Dictionary)"
  * "package(DocumentTag)"
  * "package(Function)"
  * "package(HashTable)"
  * "package(Nothing)"
  * "package(Option)"
  * "package(Package)"
  * "package(Sequence)"
  * "package(String)"
  * "package(Symbol)"
  * "package(Thing)"

For the programmer
==================

The object package, is a method function with a single argument.

loadPackage -- load a package
*****************************

Synopsis
========

  * Usage:
        loadPackage PackageName
  * Inputs:
      * PackageName, a string, the name of the package, or a
        Package, object
  * Optional inputs,:
      * FileName => a string, default value null, the name of
        the file containing the source code of the package, from which it
        should be loaded
      * LoadDocumentation => a Boolean value, default value
        false, whether to load the documentation of the package, too; see
        beginDocumentation,
      * DebuggingMode => a Boolean value, default value null,
        the value of debuggingMode, during loading the
        package; specifying it here overrides the value specified as an option
        to newPackage, by the package itself; however, if
        debuggingMode, is already false it will remain so.
      * Configuration => a list, default value {}, the entries are
        options KEY => VALUE overriding the defaults specified in the source
        code of the package and the (possibly updated) values in the file in
        the user's application directory.
      * Reload => a Boolean value, default value null, whether
        to reload the package, if it has been loaded before. If the input was
        an already loaded Package, this is automatically set to
        true.
  * Outputs:
      * a package, the package just loaded; if the input was an
        already loaded Package, this is the reloaded package
  * Consequences:
      * Loads (or reloads) the package PackageName that is in the file
        PackageName.m2.

Description
===========

The file PackageName.m2 should be on the load path, and should
contain a package named PackageName.

If the variable notify, is set to true, then an informational
message is displayed after the file is loaded.

+-----------------------------------------------------------------------------+
|i1 : notify = true                                                           |
|                                                                             |
|o1 = true                                                                    |
+-----------------------------------------------------------------------------+
|i2 : loadPackage "FirstPackage"                                              |
| -- loading FirstPackage.m2                                                  |
| -- opening database /usr/local/lib/Macaulay2/FirstPackage/cache/rawdocumenta|
| -- beginDocumentation: using documentation database, skipping the rest of /u|
| -- package "FirstPackage" loaded                                            |
| -- loaded /usr/local/share/Macaulay2/FirstPackage.m2                        |
|                                                                             |
|o2 = FirstPackage                                                            |
|                                                                             |
|o2 : Package                                                                 |
|-----------------------------------------------------------------------------|
|tion-dcba-8.db                                                               |
|sr/local/share/Macaulay2/FirstPackage.m2                                     |
+-----------------------------------------------------------------------------+

If the input is a loaded package, then this command will reload the package
instead:

+-----------------------------------------------------------------------------+
|i3 : loadPackage FirstPackage                                                |
| -- closing database /usr/local/lib/Macaulay2/FirstPackage/cache/rawdocumenta|
| -- loading FirstPackage.m2                                                  |
| -- opening database /usr/local/lib/Macaulay2/FirstPackage/cache/rawdocumenta|
| -- beginDocumentation: using documentation database, skipping the rest of /u|
| -- package "FirstPackage" loaded                                            |
| -- loaded /usr/local/share/Macaulay2/FirstPackage.m2                        |
|                                                                             |
|o3 = FirstPackage                                                            |
|                                                                             |
|o3 : Package                                                                 |
|-----------------------------------------------------------------------------|
|tion-dcba-8.db                                                               |
|                                                                             |
|tion-dcba-8.db                                                               |
|sr/local/share/Macaulay2/FirstPackage.m2                                     |
+-----------------------------------------------------------------------------+

In fact this version of the command is simply a convenient shortcut for
loadPackage with the option Reload overridden to true.

See also
========

  * packages -- Macaulay2 packages
  * readPackage -- read the package preamble
  * dismiss -- dismiss a package
  * needsPackage -- load a package if not already loaded
  * packages provided with Macaulay2

Ways to use loadPackage:
========================

  * "loadPackage(Package)"
  * "loadPackage(String)"

For the programmer
==================

The object loadPackage, is a method function with options.

readPackage -- read the package preamble
****************************************

Synopsis
========

  * Usage:
        readPackage PackageName
  * Inputs:
      * PackageName, a string, the name of the package, or a
        Package, object
  * Optional inputs,:
      * FileName => a string, default value null, the name of
        the file containing the source code of the package, from which it
        should be read
  * Outputs:
      * an option table, containing the options given to
        newPackage, in the preamble of the package

Description
===========

The file PackageName.m2 should be on the load path, and should
contain a package named PackageName. This function is mostly used for getting
information about a package quickly and without processing the entire package.

+-----------------------------------------------------------------------------+
|i1 : opts = readPackage "NormalToricVarieties"                               |
|                                                                             |
|o1 = OptionTable{Authors => {{Name => Gregory G. Smith, Email => ggsmith@mast|
|                 AuxiliaryFiles => true                                      |
|                 CacheExampleOutput => null                                  |
|                 Certification => null                                       |
|                 Configuration => {}                                         |
|                 Date => 31 May 2020                                         |
|                 DebuggingMode => false                                      |
|                 Headline => routines for working with normal toric varieties|
|                 HomePage => null                                            |
|                 InfoDirSection => Macaulay2 and its packages                |
|                 Keywords => {Toric Geometry}                                |
|                 OptionalComponentsPresent => null                           |
|                 PackageExports => {Polyhedra, Schubert2, Varieties, Truncati|
|                 PackageImports => {FourierMotzkin, LLLBases}                |
|                 Reload => false                                             |
|                 UseCachedExampleOutput => null                              |
|                 Version => 1.9                                              |
|                                                                             |
|o1 : OptionTable                                                             |
|-----------------------------------------------------------------------------|
|.queensu.ca, HomePage => http://www.mast.queensu.ca/~ggsmith}}}              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
| and related objects                                                         |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ons}                                                                         |
+-----------------------------------------------------------------------------+
|i2 : "1.9" <= opts.Version                                                   |
|                                                                             |
|o2 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * Package -- the class of all packages
  * newPackage -- the preamble of a package
  * loadPackage -- load a package

Ways to use readPackage:
========================

  * "readPackage(Package)"
  * "readPackage(String)"

For the programmer
==================

The object readPackage, is a method function with options.

needsPackage -- load a package if not already loaded
****************************************************

Synopsis
========

  * Usage:
        needsPackage PackageName
  * Inputs:
      * PackageName, a string, the name of the package
  * Optional inputs,:
      * FileName => a string, default value null, the name of
        the file containing the source code of the package, from which it
        should be loaded
      * LoadDocumentation => a Boolean value, default value
        false, whether to load the documentation of the package, too; see
        beginDocumentation,
      * DebuggingMode => a Boolean value, default value null,
        the value of the variable debuggingMode, during
        loading the package; specifying it here overrides the value specified
        as an option to newPackage, by the package itself
      * Configuration => a list, default value {}, the entries are
        options KEY => VALUE overriding the defaults specified in the source
        code of the package and the (possibly updated) values in the file in
        the user's application directory.
      * Reload => a Boolean value, default value null, whether
        to reload the package, if it has been loaded from a different source
        before
  * Outputs:
      * a package, the package requested
  * Consequences:
      * loads the package PackageName by loading the file PackageName.m2 which
        should appear in one of the directories occurring in the list
        path, unless it has already been loaded, in which case it
        ensures that the package's dictionary of exported symbols occurs in
        dictionaryPath, and are thus available to the
        user. In addition, the function needsPackage, is
        applied to each of the packages whose names are specified by the
        newPackage(...,PackageExports=>...), option for the
        requested package. If the variable notify, is set to
        true, then an informational message is displayed after the file is
        loaded.

Description
===========

For example, to load the sample package FirstPackage:

+-----------------------------------------------------------------------------+
|i1 : notify = true                                                           |
|                                                                             |
|o1 = true                                                                    |
+-----------------------------------------------------------------------------+
|i2 : needsPackage "FirstPackage"                                             |
| -- loading FirstPackage.m2                                                  |
| -- opening database /usr/local/lib/Macaulay2/FirstPackage/cache/rawdocumenta|
| -- beginDocumentation: using documentation database, skipping the rest of /u|
| -- package "FirstPackage" loaded                                            |
| -- loaded /usr/local/share/Macaulay2/FirstPackage.m2                        |
|                                                                             |
|o2 = FirstPackage                                                            |
|                                                                             |
|o2 : Package                                                                 |
|-----------------------------------------------------------------------------|
|tion-dcba-8.db                                                               |
|sr/local/share/Macaulay2/FirstPackage.m2                                     |
+-----------------------------------------------------------------------------+
|i3 : needsPackage "FirstPackage"                                             |
|                                                                             |
|o3 = FirstPackage                                                            |
|                                                                             |
|o3 : Package                                                                 |
+-----------------------------------------------------------------------------+

The second time the package was not reloaded.

See also
========

  * packages -- Macaulay2 packages
  * dismiss -- dismiss a package
  * loadPackage -- load a package
  * packages provided with Macaulay2

Ways to use needsPackage:
=========================

  * "needsPackage(String)"

For the programmer
==================

The object needsPackage, is a method function with options.

installPackage -- load and install a package and its documentation
******************************************************************

Synopsis
========

  * Usage:
        installPackage PackageName
  * Inputs:
      * PackageName, a string, or Package, the
        package to install
  * Optional inputs,:
      * FileName => a string, default value null, the name of
        the file containing the source code of the package, from which it
        should be loaded
      * UserMode => a Boolean value, default value null, if
        true, then do not give the -q option to the Macaulay2 executable when
        running examples, thereby allowing it to load the user's
        initialization file, allowing it to load packages
        previously installed in the user's application directory,
        and allowing packages it loads to read their
        configuration files from the user's application directory.
        If false, then do give the option. If
        null, then propagate the option from the current
        commandLine, if one occurs there.
      * DebuggingMode => a Boolean value, default value null,
        whether to enter the debugger, if an error occurs
        during installation; however, if debuggingMode, is
        already false, it will remain so.
      * RerunExamples => a Boolean value, default value false,
        whether to rerun all the examples during installation
      * RunExamples => a Boolean value, default value true,
        whether to run the examples during installation
      * IgnoreExampleErrors => a Boolean value, default value
        false, whether to ignore errors that occur during the running of
        examples during installation
      * CheckDocumentation => a Boolean value, default value
        true, whether to check the package's documentation for consistency and
        completeness
      * MakeDocumentation => a Boolean value, default value
        true, whether to make the documentation for the package during
        installation
      * MakeHTML => a Boolean value, default value true,
        whether to make HTML documentation. This is a form of the documentation
        that can be viewed using a browser.
      * MakeInfo => a Boolean value, default value true,
        whether to make the info pages. This is a form of the documentation
        that can be viewed using the Unix command info or using emacs
      * MakePDF => a Boolean value, default value false,
        whether to make PDF documentation
      * InstallPrefix => a string, default value
        "/home/m2user/.Macaulay2/local/", the installation prefix for
        installation of the files of the package, in case encapsulation is not
        enabled, or for installation of the links to the files, in case
        encapsulation is enabled. The default value is the subdirectory named
        local of the user's application directory.
      * MakeLinks => a Boolean value, default value true,
        whether to make links to the files after installing them, in case
        encapsulation is enabled
      * RemakeAllDocumentation => a Boolean value, default
        value true, whether to regenerate all of the help pages for this
        package. The default action is to rebuild only the html pages of the
        documentation entries that have been changed since the last time the
        package was installed. However, some changes to an entry, such as to
        its headline, will change the html of other pages that cross-reference
        it.
      * CacheExampleOutput => a Boolean value, default value
        null, whether to cache (newer) example output in a subdirectory of the
        auxiliary file directory, named examples for use in a
        future installation. This value, if set to true or false, will override
        any value explicitly specified when newPackage, is
        called. After the directory is created, it will be necessary for the
        user to specify AuxiliaryFiles => true with the newPackage,
        command.
      * SeparateExec => a Boolean value, default value false,
        whether to install the files of the package in two separate directory
        trees, one for the architecture independent files, and one for the
        architecture dependent files
      * Verbose => a Boolean value, default value false,
        whether to display some details of the installation procedure. For even
        more information set debugLevel, to a number greater
        than 0 or a number greater than 5.
  * Outputs:
      * a package, the package that was installed
  * Consequences:
      * The package is installed in a local directory, so that in the future,
        one may simply use loadPackage. Documentation for
        the package is also produced, running any Macaulay2 examples that are
        requested in the package documentation, with the random number seed
        initialized to 0.

Description
===========

The main action of this routine is to generate the documentation of the given
package and install the Macaulay2 package and documentation.

The actual file loaded is PackageName.m2, which should be on the load
path, and should contain a package named PackageName.

In order to accomplish this, several steps are performed (or bypassed,
depending on the values of the optional arguments).

  * load the package, if not already loaded (see loadPackage)
  * determine which help pages have changed since last install
  * run any new or previously failed examples, or all examples, as specified by
    the RerunExamples option
  * generate the html pages, or not, as specified by the MakeHTML option, for
    the modified help pages, or all html pages if RemakeAllDocumentation is set
    to true
  * generate the info pages, or not, as specified by the MakeInfo option
  * install the documentation and package in the location specified by the
    InstallPrefix option
  * place a link to this html documentation in the file index.html in the
    user's application directory,; see
    makePackageIndex,

The current value of prefixPath, is used to determine how to
direct documentation hyperlinks; the link will be directed to the appropriate
file if one is found by searching the trees referred to by prefixPath.
Otherwise, all documentation hyperlinks are relative to positions
within a single tree of directories, as describe by Layout.

It might be necessary to run installPackage, twice if a
package with the same name is already installed: the second installation will
redirect the hyperlinks to the freshly installed documentation, because the
files will have been installed by the first installation. This applies, for
example, to those authors who are developing updates to packages already
included with Macaulay2.

The files of the package are placed in subdirectories of the appropriate prefix
directory as specified by Layout, depending on the value
of the SeparateExec option:

Install paths given SeparateExec => false:
------------------------------------------

  * share/Macaulay2/PackageName.m2,
  * share/info/PackageName.info,
  * lib/Macaulay2/PackageName/,
  * share/Macaulay2/PackageName/, and
  * share/doc/Macaulay2/PackageName/;

Install paths given SeparateExec => true:
-----------------------------------------

  * common/share/Macaulay2/PackageName.m2,
  * common/share/info/PackageName.info,
  * x86_64-Linux-Ubuntu-24.04/lib/Macaulay2/PackageName/,
  * common/share/Macaulay2/PackageName/, and
  * common/share/doc/Macaulay2/PackageName/.

Note that in the latter case, the paths reflect the type of your machine. In
addition, if no errors occurred during running the examples, then an empty file
whose name is lib/Macaulay2/PackageName/.installed or
x86_64-Linux-Ubuntu-24.04/lib/Macaulay2/PackageName/.installed is created, to
signify that installation was completed.

Caveat
======

Links from html files containing documentation to documentation in another
package not yet installed may go to the wrong place, because it is assumed that
the package not yet installed will be installed under the same prefix. By
contrast, if the other package has already been installed under some prefix
occurring in the value of prefixPath, then the correct path
will be used.  To get two packages installed under different prefixes which
refer to each other's documentation correctly, it may be necessary to install
one of them twice.

See also
========

  * Layout -- relative locations of Macaulay2 files
  * packages -- Macaulay2 packages
  * prefixPath -- absolute locations of Macaulay2 files
  * installedPackages
  * uninstallAllPackages
  * uninstallPackage -- uninstall a package and remove
    its documentation

Ways to use installPackage:
===========================

  * "installPackage(Package)"
  * "installPackage(String)"

For the programmer
==================

The object installPackage, is a method function with options.

installedPackages
*****************

Synopsis
========

  * Usage:
        installedPackages()
  * Outputs:
      * a list, the entries are strings containing the names of
        the packages that have been installed in the user's application directory.

See also
========

  * installPackage -- load and install a package and its
    documentation
  * loadedPackages -- the list of loaded packages

For the programmer
==================

The object installedPackages, is a function closure.

uninstallPackage -- uninstall a package and remove its documentation
********************************************************************

Synopsis
========

  * Usage:
        uninstallPackage PackageName
  * Inputs:
      * PackageName, a package, or String, the
        package to uninstall
  * Optional inputs,:
      * InstallPrefix => a string, default value
        "/home/m2user/.Macaulay2/local/", see
        installPackage(...,InstallPrefix=>...), -- load and
        install a package and its documentation
  * Consequences:
      * the links to the files and the files of the specified package created
        by installPackage, in case encapsulation is
        enabled, are removed, for every version of the package.

See also
========

  * packages -- Macaulay2 packages
  * prefixPath -- absolute locations of Macaulay2 files
  * installPackage -- load and install a package and its
    documentation
  * installedPackages
  * uninstallAllPackages

Ways to use uninstallPackage:
=============================

  * "uninstallPackage(Package)"
  * "uninstallPackage(String)"

For the programmer
==================

The object uninstallPackage, is a method function with options.

uninstallAllPackages
********************

Synopsis
========

  * Usage:
        uninstallAllPackages()
  * Consequences:
      * the packages that have been installed in the user's application directory,
        are uninstalled.

See also
========

  * installPackage -- load and install a package and its
    documentation
  * installedPackages
  * uninstallPackage -- uninstall a package and remove
    its documentation

For the programmer
==================

The object uninstallAllPackages, is a
function closure.

importFrom -- import symbols to the current private dictionary
**************************************************************

Synopsis
========

  * Usage:
        importFrom(pkg, {"symbol1", "symbol2"})
  * Inputs:
      * pkg, a package, or a string, the package
        containing the private symbols
      * a string, or a list, of strings,
        corresponding to the private symbols, to export from the
        package
  * Outputs:
      * a list, of symbols,
  * Consequences:
      * package symbols provided in the list will be added to the private
        dictionary, of the current package,
        but will not be exported

Description
===========

This function can be used to import specific symbols from the private
dictionary of another package into the private dictionary of the current package.

+----------------------------+
|i1 : importFrom_Core {"raw"}|
|                            |
|o1 = {raw}                  |
|                            |
|o1 : List                   |
+----------------------------+
|i2 : raw random(ZZ^2, ZZ^2) |
|                            |
|o2 = 8 3                    |
|     1 7                    |
|                            |
|                            |
|o2 : RawMatrix              |
+----------------------------+

To import all private symbols of a package, use debug(Package),
instead. The symbols imported with this function can then be exported using
export, or exportMutable.

See also
========

  * debug(Package) -- open the private dictionary of a package
  * exportFrom -- export symbols from a package's private
    dictionary
  * Dictionary -- the class of all dictionaries

Ways to use importFrom:
=======================

  * "importFrom(Package,List)"
  * "importFrom(Package,String)"
  * "importFrom(String,List)"
  * "importFrom(String,String)"

For the programmer
==================

The object importFrom, is a method function.

use(Package) -- activate a previously dismissed package
*******************************************************

Synopsis
========

  * Function: use,
  * Usage:
        use PACKAGENAME
  * Inputs:
      * PACKAGENAME, which was previously loaded, and then dismissed.
  * Consequences:
      * activates the package, making all of its exported symbols visible
      * runs the function stored under the key
      * symbol use
      *  in the package, if there is one

Description
===========

This function is only necessary after dismissing a package.
+-------------------------------+
|i1 : loadPackage "FirstPackage"|
|                               |
|o1 = FirstPackage              |
|                               |
|o1 : Package                   |
+-------------------------------+
|i2 : firstFunction             |
|                               |
|o2 = firstFunction             |
|                               |
|o2 : MethodFunction            |
+-------------------------------+
|i3 : dismiss FirstPackage      |
|                               |
|o3 = FirstPackage              |
|                               |
|o3 : Package                   |
+-------------------------------+
|i4 : firstFunction             |
|                               |
|o4 = firstFunction             |
|                               |
|o4 : Symbol                    |
+-------------------------------+
|i5 : use FirstPackage          |
|                               |
|o5 = FirstPackage              |
|                               |
|o5 : Package                   |
+-------------------------------+
|i6 : firstFunction             |
|                               |
|o6 = firstFunction             |
|                               |
|o6 : MethodFunction            |
+-------------------------------+

See also
========

  * loadPackage -- load a package
  * dismiss(Package) -- dismiss a package
  * FirstPackage -- an example Macaulay2 package

Ways to use this method:
========================

  * use(Package) -- activate a previously dismissed
    package

check -- perform tests of a package
***********************************

Synopsis
========

  * Usage:
        check pkg
        check(i, pkg)
        check(L, pkg)
  * Inputs:
      * pkg, a package, or String, the package to test
      * i, an integer, the index of a test to run
      * L, a list, containing indices of tests to run, or {} to
        run all tests
  * Optional inputs,:
      * UserMode => a Boolean value, default value null, if
        true, do not use the -q in arguments to the Macaulay2 executable when
        running tests, thereby allowing it to load the user's
        initialization file, allowing it to load packages
        previously installed in the user's application directory,
        and allowing packages it loads to read their
        configuration files from the user's application directory.
        If false, the -q argument is added. If
        null, then add -q if it appears as an option in
        commandLine.
      * Verbose => a Boolean value, default value false, if
        true, then print the output of all failing tests
  * Consequences:
      * the tests in the package pkg are run (in separate Macaulay2 processes,
        with the random number seed initialized to 0), and any errors are
        reported.
      * if i is given, only the i-th test in the package is run and any errors
        are reported.

Description
===========

It is important for package authors to provide tests to ensure that the package
is functioning properly. One provides tests using the TEST,
function following the beginDocumentation, call in
the source of the package.

Optionally, one can store all tests in a tests.m2 directory under the auxiliary
subdirectory of the package and load the file from the main package source
file.

For example, to run the tests for the LLLBases, package
(Lenstra-Lenstra-Lovasz bases), use:

+-----------------------+
|                       |
|needsPackage "LLLBases"|
|check_1 LLLBases       |
|check LLLBases         |
+-----------------------+

Alternatively, if the package is installed somewhere accessible, one can do the
following.

+------------------+
|                  |
|check_1 "LLLBases"|
|check "LLLBases"  |
+------------------+

Caveat
======

Currently, if the package was only partially loaded because the documentation
was obtainable from a database (see beginDocumentation),
then the package will be reloaded, this time completely,
to ensure that all tests are considered; this may affect user objects of types
declared by the package, as they may be not usable by the new instance of the
package. In a future version, either the tests and the documentation will both
be cached, or neither will.

See also
========

  * packages -- Macaulay2 packages
  * creating a package
  * TEST -- add a test for a package
  * installPackage -- load and install a package and its
    documentation
  * loadPackage -- load a package

Ways to use check:
==================

  * "check(List,Package)"
  * "check(List,String)"
  * "check(Package)"
  * "check(String)"
  * "check(ZZ,Package)"
  * "check(ZZ,String)"

For the programmer
==================

The object check, is a method function with options.

debug -- open the private dictionary of a package
*************************************************

Synopsis
========

  * Usage:
        debug pkg
  * Inputs:
      * pkg, a package,
  * Consequences:
      * the private dictionary of the package pkg is added to
        dictionaryPath, so its non-exported symbols are visible
        to the user

Description
===========

For example, the private dictionary for Macaulay2 may be opened using

+---------------+
|i1 : debug Core|
+---------------+

This allows access to the low level ("raw") routines implemented by the
Macaulay2 engine, although this is mainly useful for debugging Macaulay2
itself.

+-------------------------------+
|i2 : R = QQ[a..d];             |
+-------------------------------+
|i3 : raw R                     |
|                               |
|o3 = QQGMP[a,b,c,d,            |
|       DegreeLength => 1,      |
|       Degrees => {1, 1, 1, 1},|
|       Heft => {1},            |
|       MonomialOrder => {      |
|         GRevLex => {1,1,1,1}, |
|         Position => Up        |
|         }                     |
|       ]                       |
|                               |
|o3 : RawRing                   |
+-------------------------------+

See also
========

  * export -- export symbols from a package
  * dictionaryPath

Ways to use debug:
==================

  * "debug(Package)"
  * debug(ZZ) (missing documentation)

For the programmer
==================

The object debug, is a method function.

dismiss -- dismiss a package
****************************

Synopsis
========

  * Usage:
        dismiss pkg
  * Inputs:
      * pkg, a package,
  * Consequences:
      * the dictionary of the package pkg is removed from dictionaryPath,
        so the symbols exported by pkg are no longer available
        for use.

Description
===========

The package itself is still accessible under its name in the
PackageDictionary, and its exported symbols can be made
available again with use.

+-----------------------------------------------------------------------------+
|i1 : newPackage "PKG"                                                        |
|                                                                             |
|o1 = PKG                                                                     |
|                                                                             |
|o1 : Package                                                                 |
+-----------------------------------------------------------------------------+
|i2 : export "x1"                                                             |
|                                                                             |
|o2 = {x1}                                                                    |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : x1=3                                                                    |
|                                                                             |
|o3 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i4 : endPackage "PKG"                                                        |
|                                                                             |
|o4 = PKG                                                                     |
|                                                                             |
|o4 : Package                                                                 |
+-----------------------------------------------------------------------------+
|i5 : dictionaryPath                                                          |
|                                                                             |
|o5 = {PKG.Dictionary, PackageCitations.Dictionary, Varieties.Dictionary,     |
|     ------------------------------------------------------------------------|
|     Truncations.Dictionary, Polyhedra.Dictionary, Saturation.Dictionary,    |
|     ------------------------------------------------------------------------|
|     Elimination.Dictionary, Isomorphism.Dictionary, OnlineLookup.Dictionary,|
|     ------------------------------------------------------------------------|
|     SimpleDoc.Dictionary, InverseSystems.Dictionary,                        |
|     ------------------------------------------------------------------------|
|     ConwayPolynomials.Dictionary, ReesAlgebra.Dictionary,                   |
|     ------------------------------------------------------------------------|
|     TangentCone.Dictionary, Classic.Dictionary, MinimalPrimes.Dictionary,   |
|     ------------------------------------------------------------------------|
|     PrimaryDecomposition.Dictionary, IntegralClosure.Dictionary,            |
|     ------------------------------------------------------------------------|
|     LLLBases.Dictionary, User#"private dictionary", User.Dictionary,        |
|     ------------------------------------------------------------------------|
|     Core.Dictionary, OutputDictionary, PackageDictionary}                   |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : x1                                                                      |
|                                                                             |
|o6 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i7 : dismiss PKG                                                             |
|                                                                             |
|o7 = PKG                                                                     |
|                                                                             |
|o7 : Package                                                                 |
+-----------------------------------------------------------------------------+
|i8 : dictionaryPath                                                          |
|                                                                             |
|o8 = {PackageCitations.Dictionary, Varieties.Dictionary,                     |
|     ------------------------------------------------------------------------|
|     Truncations.Dictionary, Polyhedra.Dictionary, Saturation.Dictionary,    |
|     ------------------------------------------------------------------------|
|     Elimination.Dictionary, Isomorphism.Dictionary, OnlineLookup.Dictionary,|
|     ------------------------------------------------------------------------|
|     SimpleDoc.Dictionary, InverseSystems.Dictionary,                        |
|     ------------------------------------------------------------------------|
|     ConwayPolynomials.Dictionary, ReesAlgebra.Dictionary,                   |
|     ------------------------------------------------------------------------|
|     TangentCone.Dictionary, Classic.Dictionary, MinimalPrimes.Dictionary,   |
|     ------------------------------------------------------------------------|
|     PrimaryDecomposition.Dictionary, IntegralClosure.Dictionary,            |
|     ------------------------------------------------------------------------|
|     LLLBases.Dictionary, User#"private dictionary", User.Dictionary,        |
|     ------------------------------------------------------------------------|
|     Core.Dictionary, OutputDictionary, PackageDictionary}                   |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : x1                                                                      |
|                                                                             |
|o9 = x1                                                                      |
|                                                                             |
|o9 : Symbol                                                                  |
+-----------------------------------------------------------------------------+
|i10 : values PackageDictionary                                               |
|                                                                             |
|o10 = {PrimaryDecomposition, SimpleDoc, SimpleDoc, Polyhedra, OnlineLookup,  |
|      -----------------------------------------------------------------------|
|      Text, Polyhedra, Parsing, ConwayPolynomials, Parsing,                  |
|      -----------------------------------------------------------------------|
|      ConwayPolynomials, LLLBases, PackageCitations, ReesAlgebra,            |
|      -----------------------------------------------------------------------|
|      ReesAlgebra, Truncations, PKG, Truncations, Topcom, PKG, Saturation,   |
|      -----------------------------------------------------------------------|
|      InverseSystems, MinimalPrimes, MinimalPrimes, FourierMotzkin, Core,    |
|      -----------------------------------------------------------------------|
|      Varieties, PrimaryDecomposition, Varieties, OnlineLookup, Text,        |
|      -----------------------------------------------------------------------|
|      IntegralClosure, IntegralClosure, LLLBases, Isomorphism, Isomorphism,  |
|      -----------------------------------------------------------------------|
|      Elimination, PackageCitations, Elimination, TangentCone, Topcom,       |
|      -----------------------------------------------------------------------|
|      TangentCone, User, Classic, Saturation, InverseSystems, Classic,       |
|      -----------------------------------------------------------------------|
|      FourierMotzkin, Core}                                                  |
|                                                                             |
|o10 : List                                                                   |
+-----------------------------------------------------------------------------+
|i11 : use PKG                                                                |
|                                                                             |
|o11 = PKG                                                                    |
|                                                                             |
|o11 : Package                                                                |
+-----------------------------------------------------------------------------+
|i12 : x1                                                                     |
|                                                                             |
|o12 = 3                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * loadPackage -- load a package
  * dictionaryPath
  * PackageDictionary -- the dictionary for names of
    packages
  * use(Package) -- activate a previously dismissed
    package

Ways to use dismiss:
====================

  * "dismiss(Package)"
  * "dismiss(String)"

For the programmer
==================

The object dismiss, is a method function.

options(Package)
****************

Synopsis
========

  * Function: options,

Description
===========

+-----------------------------------------------------------------------------+
|i1 : options Core                                                            |
|                                                                             |
|o1 = OptionTable{Authors => {{Name => Daniel R. Grayson, Email => dan@math.  |
|                 AuxiliaryFiles => false                                     |
|                 CacheExampleOutput => null                                  |
|                 Certification => null                                       |
|                 Configuration => {}                                         |
|                 Date => null                                                |
|                 DebuggingMode => false                                      |
|                 Headline => A computer algebra system designed to support   |
|                 HomePage => http://www.math.uiuc.edu/Macaulay2/             |
|                 InfoDirSection => Macaulay2 and its packages                |
|                 Keywords => {Uncategorized}                                 |
|                 OptionalComponentsPresent => true                           |
|                 PackageExports => {}                                        |
|                 PackageImports => {}                                        |
|                 Reload => true                                              |
|                 UseCachedExampleOutput => false                             |
|                 Version => 1.24.11                                          |
|                                                                             |
|o1 : OptionTable                                                             |
|-----------------------------------------------------------------------------|
|uiuc.edu, HomePage => http://www.math.uiuc.edu/~dan/}, {Name => Michael E.   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|algebraic geometry                                                           |
|-----------------------------------------------------------------------------|
|Stillman, Email => mike@math.cornell.edu, HomePage =>                        |
|-----------------------------------------------------------------------------|
|http://www.math.cornell.edu/People/Faculty/stillman.html}}}                  |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * options(Package)

makePackageIndex -- create an index of installed packages
*********************************************************

Synopsis
========

  * Usage:
        makePackageIndex()
  * Consequences:
      * Creates a file index.html in the ~/.Macaulay2 directory, containing
        links to the documentation for Macaulay2 and all installed packages.

Description
===========

This command may need to be run after installing a package via
installPackage.

This command is run each time the program is started, updating the index file.
Thus, one can simply restart Macaulay2 to obtain the same consequence.

See also
========

  * packages -- Macaulay2 packages

Ways to use makePackageIndex:
=============================

  * "makePackageIndex(List)"
  * "makePackageIndex(Sequence)"

For the programmer
==================

The object makePackageIndex, is a method function with a single argument.

PackageDictionary -- the dictionary for names of packages
*********************************************************

Description
===========

This dictionary is used just for names of packages.

+-----------------------------------------------------------------------------+
|i1 : dictionaryPath                                                          |
|                                                                             |
|o1 = {GlobalDictionary{}, PackageCitations.Dictionary, Varieties.Dictionary, |
|     ------------------------------------------------------------------------|
|     Truncations.Dictionary, Polyhedra.Dictionary, Saturation.Dictionary,    |
|     ------------------------------------------------------------------------|
|     Elimination.Dictionary, Isomorphism.Dictionary, OnlineLookup.Dictionary,|
|     ------------------------------------------------------------------------|
|     SimpleDoc.Dictionary, InverseSystems.Dictionary,                        |
|     ------------------------------------------------------------------------|
|     ConwayPolynomials.Dictionary, ReesAlgebra.Dictionary,                   |
|     ------------------------------------------------------------------------|
|     TangentCone.Dictionary, Classic.Dictionary, MinimalPrimes.Dictionary,   |
|     ------------------------------------------------------------------------|
|     PrimaryDecomposition.Dictionary, IntegralClosure.Dictionary,            |
|     ------------------------------------------------------------------------|
|     LLLBases.Dictionary, Macaulay2Doc.Dictionary, Core.Dictionary,          |
|     ------------------------------------------------------------------------|
|     GlobalDictionary{...1...}, PackageDictionary}                           |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+
|i2 : values PackageDictionary                                                |
|                                                                             |
|o2 = {Macaulay2Doc, PrimaryDecomposition, SimpleDoc, SimpleDoc, Polyhedra,   |
|     ------------------------------------------------------------------------|
|     OnlineLookup, Text, Polyhedra, Parsing, ConwayPolynomials, Parsing,     |
|     ------------------------------------------------------------------------|
|     ConwayPolynomials, LLLBases, PackageCitations, ReesAlgebra, ReesAlgebra,|
|     ------------------------------------------------------------------------|
|     Truncations, Truncations, Topcom, Saturation, InverseSystems,           |
|     ------------------------------------------------------------------------|
|     MinimalPrimes, MinimalPrimes, FourierMotzkin, Core, Varieties,          |
|     ------------------------------------------------------------------------|
|     Macaulay2Doc, PrimaryDecomposition, Varieties, OnlineLookup, Text,      |
|     ------------------------------------------------------------------------|
|     IntegralClosure, IntegralClosure, LLLBases, Isomorphism, Isomorphism,   |
|     ------------------------------------------------------------------------|
|     Elimination, PackageCitations, Elimination, TangentCone, Topcom,        |
|     ------------------------------------------------------------------------|
|     TangentCone, User, Classic, Saturation, InverseSystems, Classic,        |
|     ------------------------------------------------------------------------|
|     FourierMotzkin, Core}                                                   |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * dictionaryPath

For the programmer
==================

The object PackageDictionary, is an instance of the
type GlobalDictionary.

creating a package
******************

Creating a package is the most common way of contributing to Macaulay2.
Packages can contain code for working with objects of a certain category,
generating examples for testing a conjecture, or an implementation of
algorithms introduced in the literature.

There are five parts to a Macaulay2 package
-------------------------------------------

  * the preamble, initiated by newPackage,
  * a list of exported functions and variables, set via export,
    and exportMutable,
  * the code that constitutes the package
  * the documentation for the package, which comes after
    beginDocumentation,
  * a number of tests for the new package, added using TEST,

See an example of a package, for the basic
template for new packages, or packageTemplate (SimpleDoc),
for a utility for generating the skeleton for a new
package.

The name of the package must be the name of the file, without the .m2 suffix.
Thus a package NewMath will be in a file named NewMath.m2. Other sources
required by the package may be stored in a subdirectory named NewMath located
in the same directory as the package.

Documenting and testing a package
---------------------------------

The documentation and tests included in a package inform others about how to
use your package and ensure that your package continues to work with future
versions of Macaulay2. See writing documentation,
for more information.

Distributing a package
----------------------

To add your package to the list of packages distributed with Macaulay2, authors
can submit their package via a pull request to the GitHub repository for
Macaulay2 (see https://github.com/Macaulay2/M2/pulls ).

Before submitting your package, use the installPackage,
and check, functions to ensure there are no errors in the package
documentation and that all the tests pass.

See also
========

  * packages -- Macaulay2 packages
  * writing documentation

Components of a package

an example of a package
***********************

Here is a basic example of a complete package:

+-----------------------------------------------------------------------------+
|-- -*- coding: utf-8 -*-                                                     |
|newPackage(                                                                  |
|    "FirstPackage",                                                          |
|    Version => "1.1",                                                        |
|    Date => "August 5, 2012",                                                |
|    Authors => {                                                             |
|        {Name => "Jane Doe", Email => "doe@math.uiuc.edu", HomePage =>       |
|    Headline => "an example Macaulay2 package",                              |
|    Keywords => {"Documentation"},                                           |
|    DebuggingMode => false                                                   |
|    )                                                                        |
|                                                                             |
|export {"firstFunction"}                                                     |
|                                                                             |
|firstFunction = method(TypicalValue => String)                               |
|firstFunction ZZ := String => n -> if n == 1 then "Hello World!" else "      |
|                                                                             |
|beginDocumentation()                                                         |
|                                                                             |
|doc ///                                                                      |
| Node                                                                        |
|  Key                                                                        |
|   FirstPackage                                                              |
|  Headline                                                                   |
|     an example Macaulay2 package                                            |
|  Description                                                                |
|   Text                                                                      |
|    {\em FirstPackage} is a basic package to be used as an example.          |
|  Caveat                                                                     |
|    Still trying to figure this out.                                         |
|  Subnodes                                                                   |
|    firstFunction                                                            |
| Node                                                                        |
|  Key                                                                        |
|   (firstFunction,ZZ)                                                        |
|   firstFunction                                                             |
|  Headline                                                                   |
|   a silly first function                                                    |
|  Usage                                                                      |
|   firstFunction n                                                           |
|  Inputs                                                                     |
|   n:                                                                        |
|  Outputs                                                                    |
|   :                                                                         |
|    a silly string, depending on the value of {\tt n}                        |
|  Description                                                                |
|   Text                                                                      |
|    Here we show an example.                                                 |
|   Example                                                                   |
|    firstFunction 1                                                          |
|    firstFunction 0                                                          |
|///                                                                          |
|                                                                             |
|TEST ///                                                                     |
|    assert ( firstFunction 2 == "D'oh!" )                                    |
|///                                                                          |
|                                                                             |
|end--                                                                        |
|                                                                             |
|You can write anything you want down here.  I like to keep examples          |
|as I’m developing here.  Clean it up before submitting for                   |
|publication.  If you don't want to do that, you can omit the "end"           |
|above.                                                                       |
|-----------------------------------------------------------------------------|
|"http://www.math.uiuc.edu/~doe/"}},                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|D'oh!"                                                                       |
+-----------------------------------------------------------------------------+

Also see packageTemplate (SimpleDoc), a utility for
generating the skeleton for a new package.

See also
========

  * packages -- Macaulay2 packages
  * newPackage -- the preamble of a package
  * export -- export symbols from a package
  * exportMutable -- export mutable symbols from a
    package
  * beginDocumentation -- start documentation
    section of a package
  * doc (SimpleDoc) -- a simple documentation function
  * TEST -- add a test for a package

currentPackage -- the current package
*************************************

Description
===========

+---------------------+
|i1 : newPackage "Foo"|
|                     |
|o1 = Foo             |
|                     |
|o1 : Package         |
+---------------------+
|i2 : currentPackage  |
|                     |
|o2 = Foo             |
|                     |
|o2 : Package         |
+---------------------+
|i3 : endPackage "Foo"|
|                     |
|o3 = Foo             |
|                     |
|o3 : Package         |
+---------------------+

Authors
=======

  * Daniel R. Grayson (see http://www.math.uiuc.edu/~dan/ ) <dan@math.uiuc.edu>
  * Michael E. Stillman (see
    http://www.math.cornell.edu/People/Faculty/stillman.html )
    <mike@math.cornell.edu>

Version
=======

This documentation describes version 1.24.11 of Macaulay2.

For the programmer
==================

The object currentPackage, is a package.

newPackage -- the preamble of a package
***************************************

Synopsis
========

  * Usage:
        newPackage ( PackageName, ... )
  * Inputs:
      * PackageName, a string, the name of the new package
  * Optional inputs,:
      * Version => a string, default value "0.0", the version
        number of the package. A version number less than 1.0 indicates that
        the package is under development, and the user interface may change.
      * Date => a string, default value null, the date of this
        version of the package
      * InfoDirSection => a string, default value "Macaulay2 and
        its packages", the title of the section in the info page directory
        where the menu entry for this package should be made
      * Headline => a string, default value null, a brief (5-10
        words) description of the package
      * Authors => a list, default value {}, each entry is a list
        of options the form Name => x, Email => x, or HomePage => x, where x is
        a string.
      * Keywords => a list, default value {Uncategorized}, the
        entries are keywords describing the package, used to classify the
        package in the list of packages provided with Macaulay2,
      * HomePage => a string, default value null, the URI
        pointing to the home page of the package, if any
      * DebuggingMode => a Boolean value, default value false,
        whether debuggingMode, should be true during
        package loading.  However, if debuggingMode, is
        already false, it will remain so.
      * AuxiliaryFiles => a Boolean value, default value false,
        whether the package source to be distributed includes a directory for
        auxiliary files, with the same name as the package
      * PackageExports => a list, default value {}, the entries
        are names of other packages to load, both for the user and for the code
        of the new package
      * PackageImports => a list, default value {}, the entries of
        names of other packages to load, just for the code of the new package
      * CacheExampleOutput => a Boolean value, default value
        null, whether installPackage, should cache
        (newer) example output in a subdirectory of the auxiliary file
        directory named examples, for use in a future installation. This value
        can be overridden by a value explicitly specified when
        installPackage, is called. After the directory is
        created, it will necessary for the user also to specify AuxiliaryFiles
        => true.
      * OptionalComponentsPresent => a Boolean value, default
        value null, whether all optional external components of the package are
        present on the system. Unless the user sets this option or
        CacheExampleOutput to true, this option will be initialized to true.
      * UseCachedExampleOutput => a Boolean value, default
        value null, whether installPackage, should copy
        previously cached example output, if it is present and corresponds to
        the current example input for a node, rather than rerunning the
        examples, which might be important if optional external software is not
        present in the system. This is relevant only when CacheExampleOutput
        and AuxiliaryFiles are set to true. Unless set by the user, it is set
        to the negation of the value of OptionalComponentsPresent.
      * Certification => a list, default value null, the
        certification block inserted by the maintainers of Macaulay2 after the
        package has been accepted for publication by a journal, such as The
        Journal of Software for Algebra and Geometry: Macaulay2. Authors should
        not undertake to create such a certification block themselves.
      * Configuration => a list, default value {}, the entries are
        configuration options for the package. The keys and values should be
        constant expressions, such as strings and integers, not incorporating
        symbols to be exported by the package (and not yet defined). The first
        time the package is loaded by the user, unless the -q option is
        specified on the M2 command line, these options will be stored in a
        file in the user's application directory (see
        applicationDirectory). The user can change the
        configuration by editing the file. The user can override the
        configuration settings when loading the package; see
        loadPackage(...,Configuration=>...), and
        needsPackage(...,Configuration=>...). The file will be
        overwritten when a newer version of the package with different
        configuration options is loaded, but a backup will be made and the
        user's settings for the surviving options will be retained.
      * Reload => a Boolean value, default value false, whether
        to reload the package, if it has been loaded before
  * Outputs:
      * a package, the new package
  * Consequences:
      * a package is created

Description
===========

The dictionaries for the symbols in the packages loaded by the user are moved
out of the way to avoid conflicts, so just the standard pre-loaded packages are
visible to the source code of the package.  In addition, the package
SimpleDoc, is made available. If functions from additional
packages are needed by the code in the new package, then needsPackage,
can be used (after the use of newPackage) to provide them. If
functions from additional packages are needed by the user who will load the new
package, then needsPackage, can be used (before the use of
newPackage) to provide them.

+-------------------------------------------------------+
|i1 : newPackage("Foo",                                 |
|         Version => "1.1",                             |
|         Headline => "making Foo",                     |
|         Configuration => { "foo" => 42, "bar" => "x" }|
|         )                                             |
|                                                       |
|o1 = Foo                                               |
|                                                       |
|o1 : Package                                           |
+-------------------------------------------------------+
|i2 : endPackage "Foo"                                  |
|                                                       |
|o2 = Foo                                               |
|                                                       |
|o2 : Package                                           |
+-------------------------------------------------------+

The options can be recovered with options, as follows.

+--------------------------------------------------------------+
|i3 : opts = options Foo                                       |
|                                                              |
|o3 = OptionTable{Authors => {}                               }|
|                 AuxiliaryFiles => false                      |
|                 CacheExampleOutput => null                   |
|                 Certification => null                        |
|                 Configuration => {foo => 42, bar => x}       |
|                 Date => null                                 |
|                 DebuggingMode => false                       |
|                 Headline => making Foo                       |
|                 HomePage => null                             |
|                 InfoDirSection => Macaulay2 and its packages |
|                 Keywords => {Uncategorized}                  |
|                 OptionalComponentsPresent => true            |
|                 PackageExports => {}                         |
|                 PackageImports => {}                         |
|                 Reload => false                              |
|                 UseCachedExampleOutput => false              |
|                 Version => 1.1                               |
|                                                              |
|o3 : OptionTable                                              |
+--------------------------------------------------------------+
|i4 : opts.Headline                                            |
|                                                              |
|o4 = making Foo                                               |
+--------------------------------------------------------------+

Here is a template for a typical newPackage entry in a package.

+------------------------------------------------------------------------+
|                                                                        |
|newPackage("PackageName",                                               |
|        Headline => "one line description",                             |
|        Version => "0.1",                                               |
|        Date => "month XX, 20XX",                                       |
|        Authors => {                                                    |
|            {Name => "author1", Email => "email1", HomePage => "url1"}, |
|            {Name => "author2", Email => "email2", HomePage => "url2"}},|
|        DebuggingMode => false,                                         |
|        HomePage => "http://univ.edu/~user/PackageName/",               |
|        Configuration => {}                                             |
|        )                                                               |
+------------------------------------------------------------------------+

See also
========

  * packages -- Macaulay2 packages
  * creating a package
  * readPackage -- read the package preamble
  * loadPackage -- load a package
  * needsPackage -- load a package if not already loaded

Ways to use newPackage:
=======================

  * "newPackage(String)"

For the programmer
==================

The object newPackage, is a method function with a single argument.

export -- export symbols from a package
***************************************

Synopsis
========

  * Usage:
        export {"symbol1", "symbol2", ...}
  * Inputs:
      * a list, containing strings or options with string keys and
        values belonging to the package
  * Outputs:
      * a list, the list of exported symbols
  * Consequences:
      * the symbols whose names are in the list as strings, which should refer
        to functions or other symbols defined in the package, are made
        available to the user of the package, and are marked non-mutable. The
        strings are converted to symbols with those names in the dictionary of
        the package. An option of the form "name" => "symbol" creates a symbol
        with the name name that is a synonym of the symbol symbol.

Description
===========

A package can contain the code for many functions, only some of which should be
made visible to the user. The function export allows one to specify which
symbols are to be made visible. For an example see an example of a package.

No single-letter symbol should be exported, since such symbols are reserved as
variables for the user.

Use exportMutable, to export symbols whose values the user
is permitted to modify.

Use importFrom, to import private symbols of a package.

See also
========

  * exportFrom -- export symbols from a package's private
    dictionary
  * exportMutable -- export mutable symbols from a
    package
  * importFrom -- import symbols to the current private
    dictionary

Ways to use export:
===================

  * "export(List)"
  * "export(String)"

For the programmer
==================

The object export, is a method function with a single argument.

exportFrom -- export symbols from a package's private dictionary
****************************************************************

Synopsis
========

  * Usage:
        exportFrom(pkg, {"symbol1", "symbol2"})
  * Inputs:
      * pkg, a package, or a string, the package
        containing the symbols
      * a string, or a list, of strings,
        corresponding to the symbols to export
  * Consequences:
      * package symbols provided in the list will be added to the
        dictionary, of the current package,
        and will be exported

Description
===========

This function can be used to export specific symbols from the private
dictionary of another package.

+-----------------------------+
|i1 : exportFrom_Core {"HTML"}|
|                             |
|o1 = {HTML}                  |
|                             |
|o1 : List                    |
+-----------------------------+

See also
========

  * export -- export symbols from a package
  * importFrom -- import symbols to the current private
    dictionary
  * Dictionary -- the class of all dictionaries

Ways to use exportFrom:
=======================

  * "exportFrom(Package,List)"
  * "exportFrom(Package,String)"
  * "exportFrom(String,List)"
  * "exportFrom(String,String)"

For the programmer
==================

The object exportFrom, is a method function.

exportMutable -- export mutable symbols from a package
******************************************************

Synopsis
========

  * Usage:
        exportMutable {"symbol1", "symbol2", ...}
  * Inputs:
      * a list, containing strings interpreted as names of symbols
        belonging to the package
  * Outputs:
      * a list, the list of exported symbols
  * Consequences:
      * the names of symbols in the sequence, which should refer to variables
        defined in the package, are made available to the user of the package,
        in such a way that their values may be modified by the user This
        function is needed much less frequently than export. For
        an example, see an example of a package.
        No single-letter symbol should be exported, as such symbols
        are reserved as variables for the user.Use importFrom,
        to import private symbols of a package.

See also
========

  * export -- export symbols from a package

Ways to use exportMutable:
==========================

  * "exportMutable(List)"
  * "exportMutable(String)"

For the programmer
==================

The object exportMutable, is a method function with a single argument.

beginDocumentation -- start documentation section of a package
**************************************************************

Synopsis
========

  * Usage:
        beginDocumentation()
  * Consequences:
      * Initiates the documentation section of a package. If the documentation
        has previously been processed and stored, then the rest of the file
        after the invocation of beginDocumentation will be skipped. Otherwise
        the packages SimpleDoc, and Text,
        will be loaded and the rest of the file will be loaded.

Description
===========

Documentation for a package, and tests for the package, should be placed after
this point in a package file. This way, documentation can be loaded separately,
Macaulay2 examples in the documentation can be run, and the whole documentation
can be stored in a database.

For an example, see an example of a package.

To write documentation without using the function beginDocumentation, which is
just an optimization, use needsPackage, to load the
packages SimpleDoc, and Text.

See also
========

  * installPackage -- load and install a package and its
    documentation
  * TEST -- add a test for a package
  * check -- perform tests of a package

For the programmer
==================

The object beginDocumentation, is a function closure.

TEST -- add a test for a package
********************************

Synopsis
========

  * Usage:
        TEST s
  * Inputs:
      * s, a string, containing Macaulay2 code;
  * Consequences:
      * registers the string s as a test of the current package.

Description
===========

This function should only occur in the documentation section of a package;
i.e., after beginDocumentation. Use check,
to run all of the tests associated to a package.

For an example, see docExample (SimpleDoc), and an example of a package.

If a test should be skipped when running check, e.g., it is known
to fail under certain circumstances, then the comment -* no-check-flag *- may
be added to s.

Caveat
======

When creating tests, try to ensure that they run relatively quickly.

See also
========

  * assert -- check whether something is true, raise an error if
    not
  * beginDocumentation -- start documentation
    section of a package
  * check -- perform tests of a package

For the programmer
==================

The object TEST, is a keyword.

endPackage -- end a new package
*******************************

Synopsis
========

  * Usage:
        endPackage pkgname
  * Inputs:
      * pkgname, a string, the name of the package
  * Outputs:
      * a package, the new package
  * Consequences:
      * The package named should have been opened with newPackage.
        The package is closed, and the former value of
        dictionaryPath, is restored, with the global dictionary
        (containing the exported symbols) of the package prepended.

Description
===========

A package writer need not call this function explicitly, since the end of file
hook for the file containing the newPackage, command that
opened the package will call endPackage.

+-----------------------------------------------------------------------------+
|i1 : newPackage "Foo"                                                        |
|                                                                             |
|o1 = Foo                                                                     |
|                                                                             |
|o1 : Package                                                                 |
+-----------------------------------------------------------------------------+
|i2 : export "abc"                                                            |
|                                                                             |
|o2 = {abc}                                                                   |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : abc = 3                                                                 |
|                                                                             |
|o3 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i4 : dictionaryPath                                                          |
|                                                                             |
|o4 = {Foo#"private dictionary", Foo.Dictionary, Core.Dictionary,             |
|     ------------------------------------------------------------------------|
|     OutputDictionary, PackageDictionary}                                    |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : endPackage "Foo"                                                        |
|                                                                             |
|o5 = Foo                                                                     |
|                                                                             |
|o5 : Package                                                                 |
+-----------------------------------------------------------------------------+
|i6 : peek oo                                                                 |
|                                                                             |
|o6 = Package{configuration file name => null                                 |
|             Dictionary => Foo.Dictionary                                    |
|             example data files => MutableHashTable{}                        |
|             example inputs => MutableHashTable{}                            |
|             example results => MutableHashTable{}                           |
|             exported mutable symbols => {}                                  |
|             exported symbols => {abc}                                       |
|             loadDepth => 3                                                  |
|             Options => OptionTable{Authors => {}                            |
|                                    AuxiliaryFiles => false                  |
|                                    CacheExampleOutput => null               |
|                                    Certification => null                    |
|                                    Configuration => {}                      |
|                                    Date => null                             |
|                                    DebuggingMode => false                   |
|                                    Headline => null                         |
|                                    HomePage => null                         |
|                                    InfoDirSection => Macaulay2 and its      |
|                                    Keywords => {Uncategorized}              |
|                                    OptionalComponentsPresent => true        |
|                                    PackageExports => {}                     |
|                                    PackageImports => {}                     |
|                                    Reload => false                          |
|                                    UseCachedExampleOutput => false          |
|                                    Version => 0.0                           |
|             package prefix => /usr/local/                                   |
|             PackageIsLoaded => true                                         |
|             pkgname => Foo                                                  |
|             private dictionary => Foo#"private dictionary"                  |
|             processed documentation => MutableHashTable{}                   |
|             raw documentation => MutableHashTable{}                         |
|             source directory => /tmp/M2-2531735-0/90-rundir/                |
|             source file => stdio                                            |
|             test inputs => MutableList{}                                    |
|-----------------------------------------------------------------------------|
|               }                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|        }                                                                    |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|packages                                                                     |
+-----------------------------------------------------------------------------+
|i7 : dictionaryPath                                                          |
|                                                                             |
|o7 = {Foo.Dictionary, PackageCitations.Dictionary, Varieties.Dictionary,     |
|     ------------------------------------------------------------------------|
|     Truncations.Dictionary, Polyhedra.Dictionary, Saturation.Dictionary,    |
|     ------------------------------------------------------------------------|
|     Elimination.Dictionary, Isomorphism.Dictionary, OnlineLookup.Dictionary,|
|     ------------------------------------------------------------------------|
|     SimpleDoc.Dictionary, InverseSystems.Dictionary,                        |
|     ------------------------------------------------------------------------|
|     ConwayPolynomials.Dictionary, ReesAlgebra.Dictionary,                   |
|     ------------------------------------------------------------------------|
|     TangentCone.Dictionary, Classic.Dictionary, MinimalPrimes.Dictionary,   |
|     ------------------------------------------------------------------------|
|     PrimaryDecomposition.Dictionary, IntegralClosure.Dictionary,            |
|     ------------------------------------------------------------------------|
|     LLLBases.Dictionary, User#"private dictionary", User.Dictionary,        |
|     ------------------------------------------------------------------------|
|     Core.Dictionary, OutputDictionary, PackageDictionary}                   |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : abc                                                                     |
|                                                                             |
|o8 = 3                                                                       |
+-----------------------------------------------------------------------------+

This function is called automatically at the end of a file, so package authors
don't need to explicitly call endPackage.

Ways to use endPackage:
=======================

  * "endPackage(String)"

For the programmer
==================

The object endPackage, is a method function.

writing documentation
*********************

Documentation for user defined packages, and Macaulay2 itself
is written using two main methods:

Macaulay2 documentation methods
-------------------------------

  * the document(List), function, using a list-based
    hypertext, markup format;
  * the doc(String) (SimpleDoc), function, using a string-based
    SimpleDoc, format.

It is then formatted via installPackage, as the
documentation built into Macaulay2, the online HTML documentation, and the info
pages. Much of the format and structure of the documentation is automatically
generated. Each documentation entry must be part of a package, and occur after
the beginDocumentation, section of the package.

Documentation templates
-----------------------

Each documentation entry is either an overview topic, or documentation of an
individual feature, such as a symbol, a function name, a function call (that
is, a function name, together with specific types of its arguments), an
optional argument to a function, or a package.

The easiest way to write documentation for an entry is to start with an example
as a template. See the documentation on either of the documentation methods
above for templates and examples.

The documentation writing cycle
-------------------------------

Start with the package that you wish to document, and select one or several of
the above examples or templates. Cycle through the following steps as you
refine your documentation.

  0. Edit your documentation entries as desired
  1. Generate the html pages for your package, using
     installPackage("YourPackage")
  2. Review the generated HTML documentation using viewHelp,
     which displays this page in a browser.

Documentation style conventions
-------------------------------

There are a few stylistic conventions that should be noted. While not hard and
fast rules, keeping these stylistic conventions in mind makes for easier
reading by users.

  * Lowercase is used for all titles, unless a proper noun is being used.
  * Use TO (Text), to reference any Macaulay2 function, option, or
    variable occurring in the documentation as a hyperlink.
  * Inputs, Outputs, and Consequences,
    should not end with periods.

See also
========

  * viewHelp -- view online documentation in a web browser
  * installPackage -- load and install a package and its
    documentation
  * SimpleDoc -- simpler documentation for functions and
    methods

For programmers

hypertext list format
*********************

Documentation text is composed of a list of text and hypertext items. A single
text string, even though it is not a list, is generally accepted as a hypertext
list. Macaulay2 examples may be included in the list using the EXAMPLE,
tag. See Text, for the full list of hypertext types.

Each element of the list may be a text string, or one of the elements below.
The following items are used by themselves:

  * BR (Text) -- line break
  * HR (Text) -- hypertext HR element (horizontal rule)

Items that take a text string (or other hypertext list) as argument:

  * HEADER1 (Text) -- hypertext HEADER1 item
  * HEADER2 (Text) -- hypertext HEADER2 item
  * HEADER3 (Text) -- hypertext HEADER3 item
  * HEADER4 (Text) -- hypertext HEADER4 item
  * HEADER5 (Text) -- hypertext HEADER5 item
  * HEADER6 (Text) -- hypertext HEADER6 item
  * HEADER2 (Text) -- hypertext HEADER2 item
  * PARA (Text) -- hypertext paragraph container
  * SPAN (Text) -- hypertext span
  * ITALIC (Text) -- hypertext italic font
  * TT (Text) -- hypertext TT item
  * EM (Text) -- hypertext EM item
  * PRE (Text) -- preformatted text
  * SUB (Text) -- hypertext subscript
  * SUP (Text) -- hypertext superscript

Items that place hyperlinks into the documentation:

  * HREF (Text) -- hypertext link
  * TO (Text) -- hypertext documentation link
  * TO2 (Text) -- labeled hypertext documentation link
  * TOH (Text) -- hypertext documentation link followed by a
    headline

Other useful hypertext elements:

  * OL (Text) -- hypertext OL item
  * UL (Text) -- hypertext UL item
  * LI (Text) -- hypertext list item
  * DL (Text) -- hypertext DL element
  * DT (Text) -- hypertext DT element
  * DD (Text) -- hypertext DD element
  * CODE (Text) -- hypertext CODE item
  * EXAMPLE -- hypertext EXAMPLE item

Example
=======

For example, the hypertext list:

+-----------------------------------------------------------------------------+
|{  HR{}, "When referring to a ", EM "Macaulay2", " identifier such as ", TT  |
|        ", use the TT element, or use a cross-reference, as in ", TO matrix, |
|        " examples (during ", TO (installPackage,String), ") as illustrated  |
|-----------------------------------------------------------------------------|
|"matrix",                                                                    |
| ".  Incorporate ", EM "Macaulay2",                                          |
|here.", EXAMPLE "matrix{{1,2},{3,4}}", HR{} }                                |
+-----------------------------------------------------------------------------+

when used as the input to document, produces:

-------------------------------------------------------------------------------
When referring to a Macaulay2 identifier such as matrix, use the TT element, or
use a cross-reference, as in matrix.  Incorporate Macaulay2
examples (during installPackage(String)) as illustrated
here.
+------------------------+
|i1 : matrix{{1,2},{3,4}}|
|                        |
|o1 = | 1 2 |            |
|     | 3 4 |            |
|                        |
|              2       2 |
|o1 : Matrix ZZ  <-- ZZ  |
+------------------------+
-------------------------------------------------------------------------------

See also
========

  * html -- convert to HTML format
  * net -- format for printing, as a net
  * info -- convert hypertext to info format
  * Hypertext (Text) -- the class of markup lists used with
    hypertext
  * show(Hypertext) (Text)
  * writing documentation

document -- create a documentation node
***************************************

Synopsis
========

  * Usage:
        document { Key => key, ... }
  * Inputs:
      * a list, with Hypertext (Text),
        String, and special documentation entries as optional
        arguments such as Key => "..." (required)
  * Optional inputs,:
      * Key, => a list, default value null, key of a
        documentation node
      * Headline, => a list, default value null,
        headline of a documentation node
      * BaseFunction, => a list, default value
        null, the basename of a function in a documentation node
      * Usage, => a list, default value null, ways to
        use a function in a documentation node
      * Inputs, => a list, default value null,
        inputs for a function in a documentation node
      * Outputs, => a list, default value null,
        outputs for a function in a documentation node
      * Consequences, => a list, default value
        null, side-effects of a function in a documentation node
      * Acknowledgement, => a list, default
        value null, acknowledgements listed in a documentation node
      * Contributors, => a list, default value
        null, non-author contributors listed in a documentation node
      * References, => a list, default value
        null, references listed in a documentation node
      * Caveat, => a list, default value null,
        warnings or limitations listed in a documentation node
      * SeeAlso, => a list, default value null,
        cross-references to other documentation nodes
      * Subnodes, => a list, default value null, a
        menu of documentation nodes
      * SourceCode, => a list, default value
        null, sources displayed in a documentation node
      * ExampleFiles, => a list, default value
        null, data files corresponding to a documentation node
  * Consequences:
      * formatted documentation is created and stored in the current package,

Description
===========

There are two basic types of documentation:

  0. Documenting a function or a method, as in resolution(Module).
  1. documenting an overview or functions with methods, as in chain complexes,
     or resolution, respectively.

The headings Usage, BaseFunction,
Inputs, Outputs, and Consequences,
are useful only for documentation of the first type, as well as
in a call to SYNOPSIS.

Templates for using the document(List), method
--------------------------------------------------------------

  * package documentation template
  * function documentation template
  * optional argument documentation template
  * overview documentation template

Here is a basic template:

+-----------------------------------------------------------------------------+
|    document {                                                               |
|        Key          => {myFunc, (myFunc, MyType), [myFunc, MyOption], ...}, |
|        Headline     => "one line description of myFunc", -- not needed for  |
|        BaseFunction => myFunc, -- usually not needed                        |
|        Usage        => "myFunc x",                                          |
|        Inputs       => { inputs, ... },                                     |
|        Outputs      => { outputs, ... },                                    |
|        SourceCode   => { METHOD1, ... }, -- usually not needed              |
|        Consequences => { side-effects, ... },                               |
|        "A list of strings containing names of files in the auxiliary        |
|        directory of the package can go here; the files will be visible      |
|        in the current directory while example code is run.",                |
|        ExampleFiles => {"datafile1", "datafile2"},                          |
|        "There can be explanatory prose here in the form of a hypertext list |
|        EXAMPLE lines ///                                                    |
|          m2code                                                             |
|          m2code                                                             |
|          m2code                                                             |
|        ///,                                                                 |
|        "There can be explanatory prose here in the form of a hypertext list |
|        Caveat       => {"warning"},                                         |
|        SeeAlso      => {"other things"},                                    |
|        Subnodes     => {                                                    |
|            "subheading a",                                                  |
|            TO "node 1",                                                     |
|            TO "node 2",                                                     |
|            "subheading b",                                                  |
|            TO "node 3",                                                     |
|            ...                                                              |
|            },                                                               |
|        }                                                                    |
|-----------------------------------------------------------------------------|
|overviews                                                                    |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|.",                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|.",                                                                          |
+-----------------------------------------------------------------------------+

Other Functions generating hypertext list format, that you may use:
------------------------------------------------------------------------------------------------

  * SYNOPSIS -- a standardized synopsis for use in
    documentation nodes
  * EXAMPLE -- hypertext EXAMPLE item

See also
========

  * writing documentation
  * hypertext -- prepare hypertext for display

Ways to use document:
=====================

  * "document(List)"

For the programmer
==================

The object document, is a method function with a single argument.

Documentation templates based on the hypertext list format

Special documentation keywords

package documentation template
******************************

+-----------------------------------------------------------------------------+
|document {                                                                   |
|        Key      => PackageName,                                             |
|        Headline => "one line description",                                  |
|        "There can be explanatory prose here in the form of a hypertext      |
|        EXAMPLE {                                                            |
|            "m2code",                                                        |
|            "m2code",                                                        |
|            "m2code"},                                                       |
|        "There can be explanatory prose here in the form of a hypertext      |
|        Acknowledgement => {} -- a hypertext list                            |
|        Contributors => {} -- a hypertext list                               |
|        References => {} -- a hypertext list                                 |
|        Caveat => {"warning"}                                                |
|        Subnodes => {                                                        |
|            TO functionName1,                                                |
|            TO functionName2 -- and so on                                    |
|            }                                                                |
|        }                                                                    |
|-----------------------------------------------------------------------------|
|list.",                                                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|list.",                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * writing documentation
  * hypertext list format

function documentation template
*******************************

+-----------------------------------------------------------------------------+
|document {                                                                   |
|        Key => {                                                             |
|             functionName,                                                   |
|            (functionName, argumentClass1, argumentClass2, ...)},            |
|        Headline     => "one line description",                              |
|        Usage        => "usage",                                             |
|        Inputs       => {}, -- each input is a hypertext list                |
|        Outputs      => {}, -- each output is a hypertext list               |
|        Consequences => {}, -- each effect is a hypertext list               |
|        "There can be explanatory prose here in the form of a hypertext      |
|        EXAMPLE {                                                            |
|            "m2code",                                                        |
|            "m2code",                                                        |
|            "m2code"},                                                       |
|        "There can be explanatory prose here in the form of a hypertext      |
|        Caveat => {"warning"}                                                |
|        }                                                                    |
|-----------------------------------------------------------------------------|
|list.",                                                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|list.",                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * writing documentation
  * hypertext list format

optional argument documentation template
****************************************

+-----------------------------------------------------------------------------+
|document {                                                                   |
|        Key => {                                                             |
|             OptionName,                                                     |
|            [functionName, OptionName]},                                     |
|        Headline     => "one line description",                              |
|        Usage        => "usage",                                             |
|        Inputs       => {}, -- each input is a hypertext list                |
|        Consequences => {}, -- each effect is a hypertext list               |
|        "There can be explanatory prose here in the form of a hypertext      |
|        EXAMPLE {                                                            |
|            "m2code",                                                        |
|            "m2code",                                                        |
|            "m2code"},                                                       |
|        "There can be explanatory prose here in the form of a hypertext      |
|        Caveat => {"warning"}                                                |
|        }                                                                    |
|-----------------------------------------------------------------------------|
|list.",                                                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|list.",                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * writing documentation
  * hypertext list format

overview documentation template
*******************************

+-----------------------------------------------------------------------------+
|document {                                                                   |
|        Key      => "description of this page",                              |
|        Headline => "one line description",                                  |
|        "There can be explanatory prose here in the form of a hypertext      |
|        EXAMPLE {                                                            |
|            "m2code",                                                        |
|            "m2code",                                                        |
|            "m2code"},                                                       |
|        "There can be explanatory prose here in the form of a hypertext      |
|        Caveat => {"warning"}                                                |
|        }                                                                    |
|-----------------------------------------------------------------------------|
|list.",                                                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|list.",                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * writing documentation
  * hypertext list format

Key -- key of a documentation node
**********************************

Synopsis
========

  * Usage:
        document { Key => key, ... }
  * Consequences:
      * specifies the name under which the documentation is stored

Description
===========

The document key is the name of the node, specifically the one that allows
users to find the documentation for the desired command. Some node names,
rather than being strings, are sequences of Macaulay2 objects that refer to
specific method functions. If one is documenting a function of Macaulay2, the
key will just be the function's name, as in the documentation for
resolution.

+-------------------+
|                   |
|Key => {resolution}|
+-------------------+

However, if one is documenting a method for a function, then the key will have
a different form, as in the documentation for resolution(Module).

+-----------------------------+
|                             |
|Key => {(resolution, Module)}|
+-----------------------------+

If one is documenting an optional argument to a function, then the key has a
different form still, as in resolution(...,SyzygyLimit=>...).

+----------------------------------+
|                                  |
|Key => {[resolution, SyzygyLimit]}|
+----------------------------------+

Finally, if one is documenting an overview of a group of functions or a
package, as in chain complexes, then one would set up a
document key of the form:

+--------------------------+
|                          |
|Key => {"chain complexes"}|
+--------------------------+

Caveat
======

No two documentation nodes may have the same key or even a key that is a
synonym for a key which is already used. However, sometimes there is a need for
several documentation nodes to have the same key. This happens when a command
that needs to be documented is a synonym for another already documented
command. In this case the synonym's key should be stated in quotation marks. As
an example, look at the documentation for SUBSECTION (Text),
and HEADER2 (Text), in Text.m2 (see
common/share/Macaulay2/Text.m2 ).

See also
========

  * TO (Text) -- hypertext documentation link

Functions with optional argument named Key:
===========================================

  * "document(...,Key=>...)"

For the programmer
==================

The object Key, is a symbol.

Headline -- headline of a documentation node
********************************************

Synopsis
========

  * Usage:
        document { Key => key, Headline => "one line description", ... }
  * Consequences:
      * the headline string will be used to annotate itemized lists of
        cross-references to the documentation Key,

Description
===========

The headline of a documentation node, gives a brief, half line, description of
the thing being documented. As an example, the headline for this documentation
node was obtained with the code:

+------------------------------------------------------+
|                                                      |
|Headline => "make a headline for a documentation node"|
+------------------------------------------------------+

See also
========

  * TOH (Text) -- hypertext documentation link followed by a
    headline

Functions with optional argument named Headline:
================================================

  * "document(...,Headline=>...)"
  * "newPackage(...,Headline=>...)" -- see newPackage, -- the
    preamble of a package

For the programmer
==================

The object Headline, is a symbol.

BaseFunction -- the basename of a function in a documentation node
******************************************************************

Description
===========

The BaseFunction entry gives the function that uses the feature being
documented.

Here is a sample usage of this entry:

+----------------------+
|                      |
|BaseFunction => myFunc|
+----------------------+

Functions with optional argument named BaseFunction:
====================================================

  * "document(...,BaseFunction=>...)"
  * "SYNOPSIS(...,BaseFunction=>...)" -- see SYNOPSIS, -- a
    standardized synopsis for use in documentation nodes

For the programmer
==================

The object BaseFunction, is a symbol.

Usage -- ways to use a function in a documentation node
*******************************************************

Synopsis
========

  * Usage:
        document { ... , Usage => "usage", ... }

Description
===========

The Usage entry should give a formal example showing the usage of the function.
The variables used in this formal example should be the ones used in the
Inputs, and Outputs, sections of the documentation. Here
is the code for the Usage entry of the method matrix(List),:

+-------------------+
|                   |
|Usage => "matrix v"|
+-------------------+

Here is the code for the Usage entry of the method resolution(Module),:

+------------------------------+
|                              |
|Usage => "resolution M\nres M"|
+------------------------------+

This option also can be used within a SYNOPSIS, section.

See also
========

  * Inputs -- inputs for a function in a documentation node
  * Outputs -- outputs for a function in a documentation node

Functions with optional argument named Usage:
=============================================

  * "SYNOPSIS(...,Usage=>...)" -- see SYNOPSIS, -- a
    standardized synopsis for use in documentation nodes
  * "document(...,Usage=>...)"

For the programmer
==================

The object Usage, is a symbol.

Inputs -- inputs for a function in a documentation node
*******************************************************

Synopsis
========

  * Usage:
        document { ... , Inputs => { inputs, ... }, ... }

Description
===========

The entries should consist of items in one of the following forms.

  * hypertext
  * class
  * symbolname
  * class => hypertext
  * symbolname => class
  * symbolname => hypertext
  * symbolname => class => hypertext

As an example, here is the Inputs entry of the method resolution(Ideal),:

+---------------------------------------------------------------+
|                                                               |
|Inputs => { "I" => { "an ideal in a ring ", TT "R", ", say" } }|
+---------------------------------------------------------------+

Here is an example of the Inputs entry of the function sin,:

+------------------------+
|                        |
|Inputs => { "x" => RR },|
+------------------------+

See also
========

  * Outputs -- outputs for a function in a documentation node
  * Usage -- ways to use a function in a documentation node

Functions with optional argument named Inputs:
==============================================

  * "document(...,Inputs=>...)"
  * "SYNOPSIS(...,Inputs=>...)" -- see SYNOPSIS, -- a
    standardized synopsis for use in documentation nodes

For the programmer
==================

The object Inputs, is a symbol.

Outputs -- outputs for a function in a documentation node
*********************************************************

Synopsis
========

  * Usage:
        document { ... , Outputs => { outputs, ... }, ... }

Description
===========

The entries should consist of items in one of the following forms.

  * hypertext
  * class => hypertext (or null)
  * symbolname => hypertext (or null)
  * symbolname => class => hypertext (or null)

As an example, here is the Outputs entry of the method resolution(Ideal),:

+-----------------------------------------------------------------------------+
|Outputs => { {"a resolution of ", TT "R/I", " by projective ", TT "R",       |
|-----------------------------------------------------------------------------|
|"-modules" } }                                                               |
+-----------------------------------------------------------------------------+

Note that the hypertext list needs to be bounded by { and } as there is only
one output for resolution(Ideal). Without the
braces, multiple outputs are defined. Note also that the Type, of
the output is automatically added in this case.

Here is an example of the Outputs entry of the function sin,:

+---------------------------------------------+
|                                             |
|Outputs => { { "the sine of ", TT "x", "" } }|
+---------------------------------------------+

See also
========

  * Inputs -- inputs for a function in a documentation node
  * Usage -- ways to use a function in a documentation node

Functions with optional argument named Outputs:
===============================================

  * "document(...,Outputs=>...)"
  * "SYNOPSIS(...,Outputs=>...)" -- see SYNOPSIS, -- a
    standardized synopsis for use in documentation nodes

For the programmer
==================

The object Outputs, is a symbol.

Consequences -- side-effects of a function in a documentation node
******************************************************************

Synopsis
========

  * Usage:
        document { ... , Consequences => { "side-effects" }, ... }

Description
===========

Here is where one documents effects of a function that are not return values.
As an example here is the Consequences entry for the documentation node
Headline,:

+-------------------------------------------------------------------------+
|                                                                         |
|Consequences => {                                                        |
|        { "the headline string will be used to annotate itemized         |
|            lists of cross-references to the documentation ", TO "Key" }}|
+-------------------------------------------------------------------------+

Functions with optional argument named Consequences:
====================================================

  * "document(...,Consequences=>...)"
  * "SYNOPSIS(...,Consequences=>...)" -- see SYNOPSIS, -- a
    standardized synopsis for use in documentation nodes

For the programmer
==================

The object Consequences, is a symbol.

Acknowledgement -- acknowledgements listed in a documentation node
******************************************************************

Synopsis
========

  * Usage:
        document { ... , Acknowledgements => {"NSF grant number"}, ... }

Description
===========

This part of the documentation can be used to acknowledge funding sources and
collaborators.

See also
========

  * Contributors -- non-author contributors listed in a
    documentation node

Functions with optional argument named Acknowledgement:
=======================================================

  * "document(...,Acknowledgement=>...)"

For the programmer
==================

The object Acknowledgement, is a symbol.

Contributors -- non-author contributors listed in a documentation node
**********************************************************************

Synopsis
========

  * Usage:
        document { ... , Contributors => {"previous authors"}, ... }

Description
===========

This part of the documentation can be used to list contributors and previous
authors to the package who are no longer maintainers for it.

See also
========

  * Acknowledgement -- acknowledgements listed in a
    documentation node

Functions with optional argument named Contributors:
====================================================

  * "document(...,Contributors=>...)"

For the programmer
==================

The object Contributors, is a symbol.

References -- references listed in a documentation node
*******************************************************

Synopsis
========

  * Usage:
        document { ... , References => {"bibliography"}, ... }

Description
===========

This part of the documentation can be used to list references for the package.

Functions with optional argument named References:
==================================================

  * "document(...,References=>...)"

For the programmer
==================

The object References, is a symbol.

Caveat -- warnings or limitations listed in a documentation node
****************************************************************

Synopsis
========

  * Usage:
        document { ... , Caveat => {"warning"}, ... }

Description
===========

This part of the documentation serves to highlight pitfalls for the user.

Functions with optional argument named Caveat:
==============================================

  * "document(...,Caveat=>...)"

For the programmer
==================

The object Caveat, is a symbol.

SeeAlso -- cross-references to other documentation nodes
********************************************************

Synopsis
========

  * Usage:
        document { ... , SeeAlso => { ... }, ... }

Description
===========

This option inserts into a documentation page a sentence instructing the reader
to see some other topics.

The entries may have the special forms used with TO (Text). As an
example, here is the code for the SeeAlso part of a documentation node
referencing this node.

+--------------------------------+
|                                |
|SeeAlso => {[document, SeeAlso]}|
+--------------------------------+

See also
========

  * TOH (Text) -- hypertext documentation link followed by a
    headline
  * Subnodes -- a menu of documentation nodes

Functions with optional argument named SeeAlso:
===============================================

  * "document(...,SeeAlso=>...)"

For the programmer
==================

The object SeeAlso, is a symbol.

Subnodes -- a menu of documentation nodes
*****************************************

Synopsis
========

  * Usage:
        document { ... , Subnodes => { ... }, ... }
  * Consequences:
      * the documentation subnodes listed will appear as descendents of this
        node in the documentation tree

Description
===========

This option inserts into a documentation page a menu of subnodes and defines
how the tree structure of the documentation is constructed. This is relevant
when printing the documentation.

Example of usage as an optional argument to document(List),
===========================================================================

+---------------------------------+
|                                 |
|Subnodes => {                    |
|        "An example of subnodes",|
|        TO "a link name",        |
|        TO "another link name"   |
|        },                       |
+---------------------------------+

Example of usage as a keyword in doc(String) (SimpleDoc),
===================================================================

When used as a main section of a documentation node, Subnodes can be used as
follows:

+-------------------------------------------------+
|                                                 |
|Subnodes                                         |
|    :Heading 1                                   |
|      myFunction                                 |
|      "a link name"                              |
|      :A subheading about @TO "mySecondFunction"@|
|        mySecondFunction                         |
|    :Heading 2                                   |
|      "another link name"                        |
+-------------------------------------------------+

See also
========

  * TOH (Text) -- hypertext documentation link followed by a
    headline
  * doc(String) (SimpleDoc) -- a simple documentation function

Functions with optional argument named Subnodes:
================================================

  * "document(...,Subnodes=>...)"

For the programmer
==================

The object Subnodes, is a symbol.

SourceCode -- sources displayed in a documentation node
*******************************************************

Description
===========

This option inserts the source code of the listed functions into a
documentation page.

As an example, here is the code for the SourceCode part of the documentation
node for variety(SheafOfRings) (Varieties).

+---------------------------------------+
|                                       |
|SourceCode => {(variety, SheafOfRings)}|
+---------------------------------------+

See also
========

  * code -- display source code

Functions with optional argument named SourceCode:
==================================================

  * "document(...,SourceCode=>...)"

For the programmer
==================

The object SourceCode, is a symbol.

ExampleFiles -- data files corresponding to a documentation node
****************************************************************

Description
===========

This option lists filenames of data files in the auxiliary directory which
should be made available in the directory where the example code is run.

Here is a sample usage of this entry:

+------------------------------------------+
|                                          |
|ExampleFiles => {"datafile1", "datafile2"}|
+------------------------------------------+

See also
========

  * newPackage(...,AuxiliaryFiles=>...) -- the preamble of a
    package

Functions with optional argument named ExampleFiles:
====================================================

  * "document(...,ExampleFiles=>...)"

For the programmer
==================

The object ExampleFiles, is a symbol.

EXAMPLE -- hypertext EXAMPLE item
*********************************

Synopsis
========

  * Usage:
        EXAMPLE x
  * Inputs:
      * x, a string, a visible list, or an
        instance of the type PRE (Text), containing strings or
        objects of class PRE (Text),
  * Outputs:
      * an instance of the type TABLE (Text), a table containing
        the examples

Description
===========

If the table is included in the input provided to document,
the input string will be evaluated by installPackage, and
the result will be displayed in the documentation. Each object of class
PRE (Text), will be inserted unchanged into the documentation as example
output. For example, the code

EXAMPLE { "1+1" }

produces a display that looks like this:

+--------+
|i1 : 1+1|
|        |
|o1 = 2  |
+--------+

See also
========

  * examples -- list the examples in documentation
  * hypertext -- prepare hypertext for display
  * document -- create a documentation node
  * installPackage -- load and install a package and its
    documentation

Ways to use EXAMPLE:
====================

  * "EXAMPLE(String)"
  * "EXAMPLE(VisibleList)"

For the programmer
==================

The object EXAMPLE, is a method function with a single argument.

SYNOPSIS -- a standardized synopsis for use in documentation nodes
******************************************************************

Synopsis
========

  * Usage:
        SYNOPSIS ( ..., Usage => "...", ... )
  * Inputs:
      * a list, with Hypertext (Text),
        String, and special documentation entries as optional
        arguments such as Usage => "..." (required)
  * Optional inputs,:
      * BaseFunction => a function, default value null, see
        document(...,BaseFunction=>...), -- the basename of
        a function in a documentation node
      * Heading => a list, default value "Synopsis", see
        document(...,Headline=>...), -- specifies a subheading for
        the synopsis
      * Usage => a list, default value "", see
        document(...,Usage=>...), -- ways to use a function in a
        documentation node
      * Inputs => a list, default value {}, see
        document(...,Inputs=>...), -- inputs for a function in a
        documentation node
      * Outputs => a list, default value {}, see
        document(...,Outputs=>...), -- outputs for a function in a
        documentation node
      * Consequences => a list, default value {}, see
        document(...,Consequences=>...), -- side-effects of a
        function in a documentation node
  * Outputs:
      * a markup list (Text), usable as an input of
        document(List),

Description
===========

This function prepares a standardized synopsis in hypertext for use in
documentation nodes. Here is an empty template for use with SYNOPSIS.

+------------------------------+
|                              |
|SYNOPSIS (                    |
|        BaseFunction => fn,   |
|        Heading      => "",   |
|        Usage        => "",   |
|        Inputs       => {},   |
|        Outputs      => {},   |
|        Consequences => {},   |
|        PARA { ... },         |
|        EXAMPLE lines " ... ")|
+------------------------------+

The options are used just as with document. Here is an example
of its use.

+-----------------------------------------------------------------------------+
|SYNOPSIS {                                                                   |
|        Heading => "using binary methods for method functions",              |
|        Usage   => "f(x,y)",                                                 |
|        Inputs  => {                                                         |
|            "f" => { "a method function" },                                  |
|            "x" => { "an object of type ", TT "X" },                         |
|            "y" => { "an object of type ", TT "Y" }},                        |
|        Outputs => {                                                         |
|            { "the previously installed method for ", TT "f(X, Y)", " is call|
|                ", and the return value is returned. If no such method has be|
|                searches for a method for ", TT "f(X',Y')", ", where ", TT "X|
|                " and ", TT "Y'", " is an ancestor of ", TT "Y", "(see ", TO |
|        "The second line of the following example illustrates the syntax abov|
|        using ", TO "source", ", which happens to be a method function.",    |
|        EXAMPLE lines ///                                                    |
|          source(String, String) := peek;                                    |
|          source("foo", "bar")///,                                           |
|        PARA "The same syntax works for 3 or 4 arguments."}                  |
|-----------------------------------------------------------------------------|
|ed with arguments ", TT "(x, y)",                                            |
|en installed, then Macaulay2                                                 |
|'", " is an ancestor of ", TT "X",                                           |
|"inheritance", " for details)."}},                                           |
|e,                                                                           |
+-----------------------------------------------------------------------------+

See the Synopsis keyword in doc(String) (SimpleDoc), for usage as a
keyword in that format.

Ways to use SYNOPSIS:
=====================

  * "SYNOPSIS(List)"
  * "SYNOPSIS(Sequence)"
  * "SYNOPSIS(Thing)"

For the programmer
==================

The object SYNOPSIS, is a method function with a single argument.

documentation keys
******************

The Macaulay2 documentation is linked together by cross-references from one
documentation node to another. Each node is identified by a string, which is
the title of the node. Some nodes, such as this one, have titles that are
simply invented by the author. Others have titles that are manufactured in a
certain way from the aspect of the program being documented, for the sake of
uniformity.

For example, the title of the node describing resolutions of modules is
"resolution Module". The corresponding key is (resolution, Module), and it is
the job of the function makeDocumentTag, to convert keys to
titles.

Types of documentation keys
---------------------------

  * "a string"
  * s a symbol
  * (f,X) a method function or unary operator f that accepts an argument of
    type X
  * (f,X,Y) a method function or binary operator f that accepts 2 arguments, of
    types X and Y
  * (f,X,Y,Z) a method function f that accepts 3 arguments, of types X, Y, and
    Z
  * (f,X,Y,Z,T) a method function f that accepts 4 arguments, of types X, Y, Z
    and T
  * [f,A] a function f with an optional named A
  * (NewOfFromMethod,X,Y,Z) the method for new X of Y from Z
  * (NewOfMethod,X,Y) the method for new X of Y
  * (NewFromMethod,X,Z) the method for new X from Z
  * (NewMethod,X) the method for new X
  * ((symbol ++, symbol =), X,Y) the method for assignment X ++ Y = ...
  * (homology,X) the method for HH X
  * (homology,ZZ,X) the method for HH_ZZ X
  * (cohomology,ZZ,X) the method for HH^ZZ X
  * (homology,ZZ,X,Y) the method for HH_ZZ (X,Y)
  * (cohomology,ZZ,X,Y) the method for HH^ZZ (X,Y)
  * (E,ZZ,X) the method for E_ZZ X or E^ZZ X, where E is a scripted functor
  * (E,ZZ,X,Y) the method for E_ZZ (X,Y) or E^ZZ (X,Y), where E is a scripted
    functor
+----------------------------------------------------------+
|i1 : makeDocumentTag "some title"                         |
|                                                          |
|o1 = User :: some title                                   |
|                                                          |
|o1 : DocumentTag                                          |
+----------------------------------------------------------+
|i2 : makeDocumentTag (symbol ++, Module, Module)          |
|                                                          |
|o2 = Macaulay2Doc :: Module ++ Module                     |
|                                                          |
|o2 : DocumentTag                                          |
+----------------------------------------------------------+
|i3 : makeDocumentTag ((symbol _, symbol =), Symbol, Thing)|
|                                                          |
|o3 = Macaulay2Doc :: Symbol _ Thing = Thing               |
|                                                          |
|o3 : DocumentTag                                          |
+----------------------------------------------------------+
|i4 : makeDocumentTag (Tor,ZZ,Module,Module)               |
|                                                          |
|o4 = Macaulay2Doc :: Tor_ZZ(Module,Module)                |
|                                                          |
|o4 : DocumentTag                                          |
+----------------------------------------------------------+

DocumentTag -- the class of all document tags
*********************************************

Description
===========

This class is mainly for internal use, in constructing documentation.

+----------------------------------------------------------+
|i1 : makeDocumentTag (res, Module)                        |
|                                                          |
|o1 = Macaulay2Doc :: resolution(Module)                   |
|                                                          |
|o1 : DocumentTag                                          |
+----------------------------------------------------------+
|i2 : peek oo                                              |
|                                                          |
|o2 = DocumentTag{Format => resolution(Module)}            |
|                 Key => (resolution, Module)              |
|                 Package => Macaulay2Doc                  |
|                 RawDocumentation => null                 |
+----------------------------------------------------------+
|i3 : makeDocumentTag (koszul, ZZ, Matrix)                 |
|                                                          |
|o3 = Macaulay2Doc :: koszul(ZZ,Matrix)                    |
|                                                          |
|o3 : DocumentTag                                          |
+----------------------------------------------------------+
|i4 : peek oo                                              |
|                                                          |
|o4 = DocumentTag{Format => koszul(ZZ,Matrix)}             |
|                 Key => (koszul, ZZ, Matrix)              |
|                 Package => Macaulay2Doc                  |
|                 RawDocumentation => null                 |
+----------------------------------------------------------+
|i5 : makeDocumentTag [res, PairLimit]                     |
|                                                          |
|o5 = Macaulay2Doc :: resolution(...,PairLimit=>...)       |
|                                                          |
|o5 : DocumentTag                                          |
+----------------------------------------------------------+
|i6 : peek oo                                              |
|                                                          |
|o6 = DocumentTag{Format => resolution(...,PairLimit=>...)}|
|                 Key => [resolution, PairLimit]           |
|                 Package => Macaulay2Doc                  |
|                 RawDocumentation => null                 |
+----------------------------------------------------------+

Methods that use a document tag:
================================

  * "format(DocumentTag)"
  * "locate(DocumentTag)"
  * "makeDocumentTag(DocumentTag)"
  * examples(DocumentTag) (missing documentation)
  * "help(DocumentTag)" -- see help, -- view documentation nodes
  * "infoHelp(DocumentTag)" -- see infoHelp, -- view
    documentation in Info format
  * "package(DocumentTag)" -- see package, -- get containing
    package
  * "viewHelp(DocumentTag)" -- see viewHelp, -- view online
    documentation in a web browser

For the programmer
==================

The object DocumentTag, is a type, with
ancestor classes HashTable, < Thing.

parallel programming with threads and tasks
*******************************************

The simplest way to run computations in parallel is to use parallelApply.
This works like apply(BasicList,Function),
except that it uses all your cores, and
always returns a List.

+----------------------------------------------------------+
|i1 : parallelApply(1..10, n -> n!)                        |
|                                                          |
|o1 = {1, 2, 6, 24, 120, 720, 5040, 40320, 362880, 3628800}|
|                                                          |
|o1 : List                                                 |
+----------------------------------------------------------+

There is some overhead to parallelism, so this will only speed things up for a
big computation. If the list is long, it will be split into chunks for each
core, reducing the overhead. But the speedup is still limited by the different
threads competing for memory, including cpu caches; it is like running
Macaulay2 on a computer that is running other big programs at the same time. We
can see this using elapsedTime.

+----------------------------------------------------+
|i2 : L = random toList (1..10000);                  |
+----------------------------------------------------+
|i3 : elapsedTime         apply(1..100, n -> sort L);|
| -- .560209s elapsed                                |
+----------------------------------------------------+
|i4 : elapsedTime parallelApply(1..100, n -> sort L);|
| -- .141207s elapsed                                |
+----------------------------------------------------+

You will have to try it on your examples to see how much they speed up.

Warning: Threads computing in parallel can give wrong answers if their code is
not "thread safe", meaning they make modifications to memory without ensuring
the modifications get safely communicated to other threads. (Thread safety can
slow computations some.) Currently, modifications to Macaulay2 variables and
mutable hash tables are thread safe, but not changes inside mutable lists.
Also, access to external libraries such as singular, etc., may not currently be
thread safe.

The rest of this document describes how to control parallel tasks more
directly.

The task system schedules functions and inputs to run on a preset number of
threads. The number of threads to be used is given by the variable
allowableThreads, and may be examined and changed as
follows. (see allowableThreads, is temporarily increased if
necessary inside parallelApply.)

+-------------------------------------------+
|i5 : allowableThreads                      |
|                                           |
|o5 = 5                                     |
+-------------------------------------------+
|i6 : allowableThreads = maxAllowableThreads|
|                                           |
|o6 = 7                                     |
+-------------------------------------------+

To run a function in another thread use schedule, as in the
following example.

+--------------------------------------------+
|i7 : R = ZZ/101[x,y,z];                     |
+--------------------------------------------+
|i8 : I = (ideal vars R)^2                   |
|                                            |
|             2             2        2       |
|o8 = ideal (x , x*y, x*z, y , y*z, z )      |
|                                            |
|o8 : Ideal of R                             |
+--------------------------------------------+
|i9 : dogb = I -> () -> res quotient module I|
|                                            |
|o9 = dogb                                   |
|                                            |
|o9 : FunctionClosure                        |
+--------------------------------------------+
|i10 : f = dogb I                            |
|                                            |
|o10 = f                                     |
|                                            |
|o10 : FunctionClosure                       |
+--------------------------------------------+
|i11 : t = schedule f                        |
|                                            |
|o11 = <<task, created>>                     |
|                                            |
|o11 : Task                                  |
+--------------------------------------------+

Note that schedule, returns a task, not the result of the
computation, which will be accessible only after the task has completed the
computation.

+-----------------------+
|i12 : t                |
|                       |
|o12 = <<task, created>>|
|                       |
|o12 : Task             |
+-----------------------+

Use isReady, to check whether the result is available
yet.

+---------------+
|i13 : isReady t|
|               |
|o13 = false    |
+---------------+

To wait for the result and then retrieve it, use taskResult.

+--------------------------------------+
|i14 : taskResult t                    |
|                                      |
|       1      6      8      3         |
|o14 = R  <-- R  <-- R  <-- R  <-- 0   |
|                                      |
|      0      1      2      3      4   |
|                                      |
|o14 : ChainComplex                    |
+--------------------------------------+
|i15 : assert instance(oo,ChainComplex)|
+--------------------------------------+

It is possible to make a task without starting it running, using
createTask.

+-----------------------+
|i16 : t' = createTask f|
|                       |
|o16 = <<task, created>>|
|                       |
|o16 : Task             |
+-----------------------+
|i17 : t'               |
|                       |
|o17 = <<task, created>>|
|                       |
|o17 : Task             |
+-----------------------+

Start it running with schedule.

+-----------------------------------+
|i18 : schedule t';                 |
+-----------------------------------+
|i19 : t'                           |
|                                   |
|o19 = <<task, created>>            |
|                                   |
|o19 : Task                         |
+-----------------------------------+
|i20 : taskResult t'                |
|                                   |
|       1      6      8      3      |
|o20 = R  <-- R  <-- R  <-- R  <-- 0|
|                                   |
|      0      1      2      3      4|
|                                   |
|o20 : ChainComplex                 |
+-----------------------------------+

One may use addStartTask, to specify that
one task is to be started after another one finishes.  In the following
example, G will start after F finishes.

+-----------------------------------------+
|i21 : F = createTask(() -> "result of F")|
|                                         |
|o21 = <<task, created>>                  |
|                                         |
|o21 : Task                               |
+-----------------------------------------+
|i22 : G = createTask(() -> "result of G")|
|                                         |
|o22 = <<task, created>>                  |
|                                         |
|o22 : Task                               |
+-----------------------------------------+
|i23 : addStartTask(F,G)                  |
+-----------------------------------------+
|i24 : schedule F                         |
|                                         |
|o24 = <<task, created>>                  |
|                                         |
|o24 : Task                               |
+-----------------------------------------+
|i25 : taskResult F                       |
|                                         |
|o25 = result of F                        |
+-----------------------------------------+
|i26 : taskResult G                       |
|                                         |
|o26 = result of G                        |
+-----------------------------------------+

Use addCancelTask, to specify that the
completion of one task triggers the cancellation of another, by means of an
interrupt exception.

Use addDependencyTask, to schedule a
task, but to ensure that it will not run until one or more other tasks finish
running.

Using the functions above, essentially any parallel functionality needed can be
created.

Low level C API functionality using the same scheduler also exists in the
Macaulay2/system directory. It works essentially the same way as the Macaulay2
interface.

See also
========

  * parallelism in engine computations
    -- parallelism in engine computations
  * elapsedTime -- time a computation including time
    elapsed

parallelApply -- apply a function to each element in parallel
*************************************************************

Synopsis
========

  * Usage:
        parallelApply(L,f)
  * Inputs:
      * L, a basic list,
      * f, a function,
  * Optional inputs,:
      * Strategy => See null, or a string, default value
        null
  * Outputs:
      * a list, or a basic list, If the
        Strategy, option is null, then this behaves like
        toList apply(L,f), with the result computed in parallel in chunks using
        all cores. If it is the string "raw", then this behaves like
        apply(apply(L, e -> schedule(f, e)), taskResult).

Description
===========

If the option Strategy is given the string "raw", then a separate task is
created for each element of L. L is not split into chunks, see
allowableThreads, is used unchanged, and the result has the
same class as L.   Normally the default strategy (Strategy => null) is more
efficient.

See parallel programming with threads and tasks,
for more information and an important warning about
thread safety.

Ways to use parallelApply:
==========================

  * "parallelApply(BasicList,Function)"

For the programmer
==================

The object parallelApply, is a method function with options.

createTask -- create a task
***************************

Synopsis
========

  * Usage:
        createTask(f,x)
        createTask f
  * Inputs:
      * f, a function,
      * x, a thing,
  * Outputs:
      * a task, which when scheduled, will apply the function f to
        the argument x.  In the second form, where x is not specified, it is
        take to be ().

Description
===========

+------------------------+
|i1 : f = x -> 2^x       |
|                        |
|o1 = f                  |
|                        |
|o1 : FunctionClosure    |
+------------------------+
|i2 : t = createTask(f,3)|
|                        |
|o2 = <<task, created>>  |
|                        |
|o2 : Task               |
+------------------------+
|i3 : schedule t         |
|                        |
|o3 = <<task, created>>  |
|                        |
|o3 : Task               |
+------------------------+
|i4 : taskResult t       |
|                        |
|o4 = 8                  |
+------------------------+

Ways to use createTask:
=======================

  * "createTask(Function)"
  * "createTask(Function,Thing)"

For the programmer
==================

The object createTask, is a compiled function.

addCancelTask(Task,Task) -- specify that the completion of one task triggers the cancellation of another
********************************************************************************************************

Synopsis
========

  * Function: addCancelTask,
  * Usage:
        addCancelTask(t,u)
  * Inputs:
      * t, a task,
      * u, a task,
  * Consequences:
      * when the task t is finished, then the task u will be cancelled

Ways to use this method:
========================

  * addCancelTask(Task,Task) -- specify
    that the completion of one task triggers the cancellation of another

addDependencyTask(Task,Task) -- schedule a task, but ensure that it will not run until another task finishes
************************************************************************************************************

Synopsis
========

  * Function: addDependencyTask,
  * Usage:
        addDependencyTask(t,u)
  * Inputs:
      * t, a task,
      * u, a task,
  * Consequences:
      * the task t will be scheduled for execution, but execution will not
        begin until the task u finishes

Description
===========

+-----------------------------------------------------------+
|i1 : for i to 5 do t_i = createTask(() -> i)               |
+-----------------------------------------------------------+
|i2 : for i from 1 to 5 do addDependencyTask(t_i, t_(i - 1))|
+-----------------------------------------------------------+
|i3 : schedule t_0                                          |
|                                                           |
|o3 = <<task, created>>                                     |
|                                                           |
|o3 : Task                                                  |
+-----------------------------------------------------------+
|i4 : taskResult t_5                                        |
|                                                           |
|o4 = 5                                                     |
+-----------------------------------------------------------+

Ways to use this method:
========================

  * addDependencyTask(Task,Task), --
    schedule a task, but ensure that it will not run until another task
    finishes

addStartTask(Task,Task) -- schedule a task upon completion of another
*********************************************************************

Synopsis
========

  * Function: addStartTask,
  * Usage:
        addStartTask(t,u)
  * Inputs:
      * t, a task,
      * u, a task,
  * Consequences:
      * After task t finishes, task u will be scheduled for execution.

Description
===========

+-------------------------+
|i1 : f = () -> "f value";|
+-------------------------+
|i2 : g = () -> "g value";|
+-------------------------+
|i3 : F = createTask f    |
|                         |
|o3 = <<task, created>>   |
|                         |
|o3 : Task                |
+-------------------------+
|i4 : G = createTask g    |
|                         |
|o4 = <<task, created>>   |
|                         |
|o4 : Task                |
+-------------------------+
|i5 : addStartTask(F,G)   |
+-------------------------+
|i6 : schedule F          |
|                         |
|o6 = <<task, created>>   |
|                         |
|o6 : Task                |
+-------------------------+
|i7 : taskResult F        |
|                         |
|o7 = f value             |
+-------------------------+
|i8 : taskResult G        |
|                         |
|o8 = g value             |
+-------------------------+

Ways to use this method:
========================

  * addStartTask(Task,Task) -- schedule a
    task upon completion of another

schedule -- schedule a task for execution
*****************************************

Synopsis
========

  * Usage:
        schedule(f,x)
        schedule f
        schedule t
  * Inputs:
      * f, a function,
      * x, a thing,
      * t, a task,
  * Outputs:
      * a new task computing the value of the f(x), or, if x is not provided,
        then of f(). Alternatively, the task t, created previously with
        createTask, is scheduled for execution.

Description
===========

The computation proceeds in the background, in a thread.  The status of the
task can be observed by printing t.  When the computation is finished, as can
be detected with isReady(Task), the final value can
be retrieved with taskResult(Task).

If notify, is set to true, then useful messages are
printed when the task changes state.

+------------------------+
|i1 : f = x -> 2^x       |
|                        |
|o1 = f                  |
|                        |
|o1 : FunctionClosure    |
+------------------------+
|i2 : t = createTask(f,3)|
|                        |
|o2 = <<task, created>>  |
|                        |
|o2 : Task               |
+------------------------+
|i3 : schedule t         |
|                        |
|o3 = <<task, created>>  |
|                        |
|o3 : Task               |
+------------------------+
|i4 : taskResult t       |
|                        |
|o4 = 8                  |
+------------------------+
|i5 : u = schedule(f,4)  |
|                        |
|o5 = <<task, created>>  |
|                        |
|o5 : Task               |
+------------------------+
|i6 : taskResult u       |
|                        |
|o6 = 16                 |
+------------------------+

Ways to use schedule:
=====================

  * "schedule(Function)"
  * "schedule(Function,Thing)"
  * "schedule(Task)"

For the programmer
==================

The object schedule, is a compiled function.

isReady(Task) -- whether a task is finished
*******************************************

Synopsis
========

  * Function: isReady,
  * Usage:
        isReady t
  * Inputs:
      * t,
  * Outputs:
      * whether the task t has finished executing and a return value is
        available

Description
===========

The return value can be retrieved with taskResult(Task).

Ways to use this method:
========================

  * isReady(Task) -- whether a task is finished

taskResult(Task) -- retrieve the value returned by a task
*********************************************************

Synopsis
========

  * Function: taskResult,
  * Usage:
        taskResult t
  * Inputs:
      * t,
  * Outputs:
      * the value returned by the function provided to
        schedule(Function), when the task was started. See
        taskResult(Task), will first wait for the task to
        finish if necessary.  If the task is cancelled, an error will be
        signaled.
  * Consequences:
      * The field in t where the return value is stored is set to null,
        and the task is considered to have completely terminated.
        Attempting to fetch the return value a second time will signal an
        error.

Ways to use this method:
========================

  * taskResult(Task) -- retrieve the value
    returned by a task

cancelTask(Task) -- stop a task
*******************************

Synopsis
========

  * Function: cancelTask,
  * Usage:
        cancelTask t
  * Inputs:
      * t,
  * Consequences:
      * The task t is interrupted by setting a flag.  Eventually it will stop.

Description
===========

+----------------------------------------------+
|i1 : n = 0                                    |
|                                              |
|o1 = 0                                        |
+----------------------------------------------+
|i2 : t = schedule(() -> while true do n = n+1)|
|                                              |
|o2 = <<task, created>>                        |
|                                              |
|o2 : Task                                     |
+----------------------------------------------+
|i3 : sleep 1                                  |
|                                              |
|o3 = 0                                        |
+----------------------------------------------+
|i4 : t                                        |
|                                              |
|o4 = <<task, running>>                        |
|                                              |
|o4 : Task                                     |
+----------------------------------------------+
|i5 : n                                        |
|                                              |
|o5 = 711773                                   |
+----------------------------------------------+
|i6 : sleep 1                                  |
|                                              |
|o6 = 0                                        |
+----------------------------------------------+
|i7 : t                                        |
|                                              |
|o7 = <<task, running>>                        |
|                                              |
|o7 : Task                                     |
+----------------------------------------------+
|i8 : n                                        |
|                                              |
|o8 = 1458396                                  |
+----------------------------------------------+
|i9 : isReady t                                |
|                                              |
|o9 = false                                    |
+----------------------------------------------+
|i10 : cancelTask t                            |
+----------------------------------------------+
|i11 : sleep 2                                 |
|stdio:2:25:(3):[1]: error: interrupted        |
|                                              |
|o11 = 0                                       |
+----------------------------------------------+
|i12 : t                                       |
|                                              |
|o12 = <<task, canceled>>                      |
|                                              |
|o12 : Task                                    |
+----------------------------------------------+
|i13 : n                                       |
|                                              |
|o13 = 1458571                                 |
+----------------------------------------------+
|i14 : sleep 1                                 |
|                                              |
|o14 = 0                                       |
+----------------------------------------------+
|i15 : n                                       |
|                                              |
|o15 = 1458571                                 |
+----------------------------------------------+
|i16 : isReady t                               |
|                                              |
|o16 = false                                   |
+----------------------------------------------+

Ways to use this method:
========================

  * cancelTask(Task) -- stop a task

isCanceled(Task) -- whether a task has been canceled
****************************************************

Synopsis
========

  * Function: isCanceled,
  * Usage:
        isCanceled t
  * Inputs:
      * t,
  * Outputs:
      * whether the task t has been canceled

Description
===========

+------------------------------------------------+
|i1 : n = 0                                      |
|                                                |
|o1 = 0                                          |
+------------------------------------------------+
|i2 : t = schedule(() -> while true do n = n + 1)|
|                                                |
|o2 = <<task, created>>                          |
|                                                |
|o2 : Task                                       |
+------------------------------------------------+
|i3 : sleep 1                                    |
|                                                |
|o3 = 0                                          |
+------------------------------------------------+
|i4 : isCanceled t                               |
|                                                |
|o4 = false                                      |
+------------------------------------------------+
|i5 : sleep 1                                    |
|                                                |
|o5 = 0                                          |
+------------------------------------------------+
|i6 : cancelTask t                               |
+------------------------------------------------+
|i7 : sleep 2                                    |
|stdio:2:25:(3):[1]: error: interrupted          |
|                                                |
|o7 = 0                                          |
+------------------------------------------------+
|i8 : isCanceled t                               |
|                                                |
|o8 = true                                       |
+------------------------------------------------+

See also
========

  * parallel programming with threads and tasks
  * cancelTask -- stop a task

Ways to use this method:
========================

  * isCanceled(Task) -- whether a task has been
    canceled

setIOExclusive -- exclusive I/O for the current thread
******************************************************

Synopsis
========

  * Usage:
        setIOExclusive()
        setIOExclusive f
  * Inputs:
      * f, a file,
  * Consequences:
      * the current thread becomes the only one permitted to use the file f, or
        if no file is given, the files stdio, and stderr.

See also
========

  * parallel programming with threads and tasks
  * setIOUnSynchronized -- unsynchronized I/O for
    threads
  * setIOSynchronized -- synchronized I/O for threads
  * getIOThreadMode -- get I/O thread mode

For the programmer
==================

The object setIOExclusive, is a compiled function.

setIOSynchronized -- synchronized I/O for threads
*************************************************

Synopsis
========

  * Usage:
        setIOSynchronized()
        setIOSynchronized f
        getIOThreadMode
  * Inputs:
      * f, a file,
  * Consequences:
      * threads are permitted to use the file f, or if no file is given, see
        stdio, and stderr, to output complete lines only

Caveat
======

this function is experimental

See also
========

  * parallel programming with threads and tasks
  * setIOUnSynchronized -- unsynchronized I/O for
    threads
  * setIOExclusive -- exclusive I/O for the current
    thread
  * getIOThreadMode -- get I/O thread mode

For the programmer
==================

The object setIOSynchronized, is a compiled function.

setIOUnSynchronized -- unsynchronized I/O for threads
*****************************************************

Synopsis
========

  * Usage:
        setIOUnSynchronized()
        setIOUnSynchronized f
        getIOThreadMode
  * Inputs:
      * f, a file,
  * Consequences:
      * threads are permitted to use the file f, or if no file is given, see
        stdio, and stderr, in an unregulated manner

See also
========

  * parallel programming with threads and tasks
  * setIOSynchronized -- synchronized I/O for threads
  * setIOExclusive -- exclusive I/O for the current
    thread

For the programmer
==================

The object setIOUnSynchronized, is a compiled function.

threadLocal -- create a symbol whose value in one thread is not shared with others
**********************************************************************************

Synopsis
========

  * Usage:
        threadLocal foo
  * Outputs:
      * a new symbol, whose name is "foo", for example, whose values in each
        thread will be independent of each other, with initial value
        null,

Description
===========

+-----------------------------------------+
|i1 : threadLocal x                       |
|                                         |
|o1 = x                                   |
|                                         |
|o1 : Symbol                              |
+-----------------------------------------+
|i2 : x = 1                               |
|                                         |
|o2 = 1                                   |
+-----------------------------------------+
|i3 : t = schedule ( () -> ( x = 2 ; x ) )|
|                                         |
|o3 = <<task, created>>                   |
|                                         |
|o3 : Task                                |
+-----------------------------------------+
|i4 : taskResult t                        |
|                                         |
|o4 = 2                                   |
+-----------------------------------------+
|i5 : x                                   |
|                                         |
|o5 = 1                                   |
+-----------------------------------------+

For the programmer
==================

The object threadLocal, is a keyword.

allowableThreads -- the current maximum number of simultaneously running tasks
******************************************************************************

Synopsis
========

  * Usage:
        allowableThreads = n
  * Consequences:
      * The number of threads devoted to computation of tasks is set to n.  The
        number includes the main thread, but not the threads started
        independently by the garbage collector.  Thus the maximum number of
        background tasks running simultaneously will be n-1.  The value of n
        should be not larger than the value of maxAllowableThreads.

See also
========

  * parallel programming with threads and tasks

For the programmer
==================

The object allowableThreads, is an integer.

maxAllowableThreads -- the maximum possible number of simultaneously running tasks
**********************************************************************************

Synopsis
========

  * Usage:
        maxAllowableThreads
  * Outputs:
      * an integer, the maximum number to which
        allowableThreads, can be set

Description
===========

+------------------------+
|i1 : maxAllowableThreads|
|                        |
|o1 = 7                  |
+------------------------+

See also
========

  * parallel programming with threads and tasks

For the programmer
==================

The object maxAllowableThreads, is an integer.

Task -- the class of all tasks
******************************

Functions and methods returning a task:
=======================================

  * "createTask(Function)" -- see createTask, -- create a
    task
  * "createTask(Function,Thing)" -- see createTask, -- create
    a task
  * "schedule(Function)" -- see schedule, -- schedule a task
    for execution
  * "schedule(Function,Thing)" -- see schedule, -- schedule a
    task for execution
  * "schedule(Task)" -- see schedule, -- schedule a task for
    execution

Methods that use a task:
========================

  * addCancelTask(Task,Task) -- specify
    that the completion of one task triggers the cancellation of another
  * addDependencyTask(Task,Task), --
    schedule a task, but ensure that it will not run until another task
    finishes
  * addStartTask(Task,Task) -- schedule a
    task upon completion of another
  * cancelTask(Task) -- stop a task
  * isCanceled(Task) -- whether a task has been
    canceled
  * isReady(Task) -- whether a task is finished
  * taskResult(Task) -- retrieve the value
    returned by a task

For the programmer
==================

The object Task, is a type, with ancestor class
Thing.

system facilities
*****************

Loading files:

Echoing characters:

Dumping and restoring the state of the system:

Interface to the operating system:

Variables with information about the state of the current process:

Dealing with the garbage collector:

autoload -- arrange for a function to be loaded automatically
*************************************************************

Synopsis
========

  * Usage:
        autoload(f,x)
  * Inputs:
      * f
      * x
  * Consequences:
      * arranges for a function named f to be automatically loaded from the
        file x the first time it is used. This is accomplished by creating a
        suitable function that will load the file and assigning the function to
        f.

Description
===========

+-----------------------------------------------------------------------------+
|i1 : fn = temporaryFileName()                                                |
|                                                                             |
|o1 = /tmp/M2-2533189-0/0                                                     |
+-----------------------------------------------------------------------------+
|i2 : fn << "f = x -> x+1\n" << close                                         |
|                                                                             |
|o2 = /tmp/M2-2533189-0/0                                                     |
|                                                                             |
|o2 : File                                                                    |
+-----------------------------------------------------------------------------+
|i3 : autoload(f,fn)                                                          |
+-----------------------------------------------------------------------------+
|i4 : code f                                                                  |
|                                                                             |
|o4 = /usr/local/share/Macaulay2/Core/autoload.m2:8:17-13:11:                 |
|     --source code:                                                          |
|          sym <- f := x -> (                                                 |
|               load filename;                                                |
|               if f === value sym                                            |
|               then error("symbol '", toString sym, "' didn't acquire a new  |
|               (value sym) x                                                 |
|               );                                                            |
|     | symbol    class            value                                      |
|     | ------    -----            -----                                      |
|     | f         FunctionClosure  FunctionClosure[/home/m2user/src/macaulay2 |
|     | sym       Symbol           f                                          |
|     | filename  String           "/tmp/M2-2533189-0/0"                      |
|-----------------------------------------------------------------------------|
|value in file '", filename, "'");                                            |
|                                                                             |
|                                                                             |
|               location of symbol                                            |
|               ------------------                                            |
|/M2/M2/Ma.  /usr/local/share/Macaulay2/Core/autoload.m2:8:12-8:13            |
|               /usr/local/share/Macaulay2/Core/autoload.m2:6:28-6:31         |
|               /usr/local/share/Macaulay2/Core/autoload.m2:6:32-6:40         |
+-----------------------------------------------------------------------------+
|i5 : f 4                                                                     |
|                                                                             |
|o5 = 5                                                                       |
+-----------------------------------------------------------------------------+
|i6 : removeFile fn                                                           |
+-----------------------------------------------------------------------------+

Ways to use autoload:
=====================

  * "autoload(Symbol,String)"

For the programmer
==================

The object autoload, is a method function.

initialization file
*******************

The file init.m2 is loaded automatically when the program is started, if it
exists.

On most systems the file is sought in the directory $HOME/.Macaulay2/, where
$HOME is replaced by the path to the user's home directory.

Under Mac OS X, the file is sought instead in the directory
$HOME/Library/Application Support/Macaulay2/.

If the user wants a file called, say, start.m2 in the current directory to be
loaded automatically when the program is started, then the following line of
code can be placed in the file init.m2.

if fileExists "start.m2" then load(currentDirectory()|"start.m2")

Warning: former versions of the program would also load a file named init.m2
found in the current directory.

input -- read Macaulay2 commands and echo
*****************************************

Synopsis
========

  * Usage:
        input fn
  * Inputs:
      * fn, a string,
  * Consequences:
      * reads and executes the commands found in the file whose name is
        contained in the string fn, echoing the input, printing the values, and
        incrementing the line number

Description
===========

The file is sought in the directory containing the file currently being loaded,
if any, and then along the path, unless the name of the file
begins with /, ~/, $, or !. If the file begins with ./ or ../, then it looks
instead in the directory of the file currently being loaded (see
currentFileDirectory).  If no file is being loaded it
will look in the current directory (see currentDirectory).

If one of the top level expressions in the file evaluates to the symbol
end, the reading of the file is stopped at that point.

If an error occurs while evaluating the expressions in the file, reading is
stopped.

See also
========

  * path -- list of directories to look in
  * needs -- read Macaulay2 commands if necessary
  * load -- read Macaulay2 commands

For the programmer
==================

The object input, is a function closure.

load -- read Macaulay2 commands
*******************************

Description
===========

load "f" -- reads and executes Macaulay2 expressions found in the file named f.

The file is sought in the directory containing the file currently being loaded,
if any, and then along the path, unless the name of the file
begins with /, $, or !. If the file begins with ./ or ../, then it looks
instead in the directory of the file currently being loaded (see
currentFileDirectory).  If no file is being loaded it
will look in the current directory (see currentDirectory).

The file is read without echoing the input, printing the values, or
incrementing the line number.

If one of the top level expressions in the file evaluates to the symbol
end, the reading of the file is stopped at that point.

If the variable notify, is set to true, then an informational
message is displayed after the file is loaded.

See also
========

  * path -- list of directories to look in
  * needs -- read Macaulay2 commands if necessary
  * input -- read Macaulay2 commands and echo
  * notify -- whether to notify the user when a file is loaded

For the programmer
==================

The object load, is a function closure.

needs -- read Macaulay2 commands if necessary
*********************************************

Synopsis
========

  * Usage:
        needs "f"
  * Consequences:
      * The file named f is loaded with load, if it hasn't been
        loaded yet; if it has changed since the last time it was loaded, it
        will be loaded again, from the same location as the time before,
        without searching along the path.

Description
===========

If the variable notify, is set to true, then an informational
message is displayed after the file is loaded.

For the programmer
==================

The object needs, is a function closure.

end -- stop loading a file
**************************

Synopsis
========

  * Usage:
        end
  * Consequences:
      * This symbol, encountered at top level, causes loading of the current
        input file to be stopped.
      * Alternatively, in the debugger it causes the current code to be
        abandoned, and the debugger to be re-entered one level further up.  If
        there are no more suspended levels of execution, then control is
        returned to the top level.

Description
===========

+-------------------------------------+
|i1 : load "Macaulay2Doc/demo3.m2"    |
|hi                                   |
+-------------------------------------+
|i2 : get loadedFiles#(#loadedFiles-1)|
|                                     |
|o2 = print hi                        |
|     end                             |
|     print ho                        |
+-------------------------------------+

Here is an example of its use in the debugger.

+-----------------------------------------------------------------------------+
|i3 : load "Macaulay2Doc/demo1.m2"                                            |
+-----------------------------------------------------------------------------+
|i4 : g 2                                                                     |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|8:10-8:13: --source code:                                                    |
|     b := 1/x;                                                               |
|-----------------------------------------------------------------------------|
|error: division by zero                                                      |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
|ii5 : end                                                                    |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:13:11:(3):[1]: --entering   |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|13:10-13:16: --source code:                                                  |
|     d := f(y-2);                                                            |
|-----------------------------------------------------------------------------|
|debugger (type help to see debugger commands)                                |
+-----------------------------------------------------------------------------+
|ii6 : end                                                                    |
+-----------------------------------------------------------------------------+
|i7 : g 3                                                                     |
|                                                                             |
|     7                                                                       |
|o7 = -                                                                       |
|     2                                                                       |
|                                                                             |
|o7 : QQ                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * needs -- read Macaulay2 commands if necessary
  * load -- read Macaulay2 commands
  * input -- read Macaulay2 commands and echo

For the programmer
==================

The object end, is a symbol.

clearEcho -- turn off echoing
*****************************

Description
===========

clearEcho stdio -- turn off echoing of characters typed to the standard input.

For the programmer
==================

The object clearEcho, is a compiled function.

setEcho -- turn on echoing
**************************

Description
===========

setEcho stdio -- turn on echoing of characters typed to the standard input.

For the programmer
==================

The object setEcho, is a compiled function.

top level loop
**************

The top level evaluation loop of the interpreter contains hooks so the user can
control how printing of the results of evaluation is done.  If the result is
null, then nothing is printed.  Otherwise, the appropriate method
associated with the symbol Print, is applied to perform the
printing, unless the printing is to be suppressed, as indicated by a semicolon
at the end of the statement, in which case the NoPrint, method
is applied.

See also
========

  * Print -- top level method for printing results
  * NoPrint -- top level method for non-printing results
  * BeforePrint -- top level method applied before printing
    results
  * AfterEval -- top level method applied after evaluation
  * AfterPrint -- top level method applied after printing
  * AfterNoPrint -- top level method applied after not
    printing

capture -- evaluate Macaulay2 code and capture the output
*********************************************************

Synopsis
========

  * Usage:
        (err, output) := capture str
  * Inputs:
      * str, a net, a list, or a string,
        the Macaulay2 code to be evaluated
  * Optional inputs,:
      * UserMode => a Boolean value, default value true,
        indicates whether currently loaded packages and exported symbols should
        be accessible while str is being evaluated.
      * PackageExports => a list, default value null, of packages
        to be loaded before evaluating str.  The current package, as given by
        Macaulay2Doc, will be included.
  * Outputs:
      * err, a Boolean value, whether the evaluation was
        interrupted because of an error
      * output, a string, the result of the evaluation

Description
===========

This function evaluates the given Macaulay2 code within the same process in
order to speed up tasks such as generating example results or checking the
package tests.

+-----------------------------------------------------------------------------+
|i1 : (err, output) = capture examples(resolution, Ideal)                     |
|                                                                             |
|o1 = (false,                                                                 |
|             i1 : -- examples for tag: resolution(Ideal)                     |
|                  -- /usr/local/share/Macaulay2/                             |
|                  R = ZZ[a..d]                                               |
|                                                                             |
|             o1 = R                                                          |
|                                                                             |
|             o1 : PolynomialRing                                             |
|                                                                             |
|             i2 : I = ideal(a,b,c,d)                                         |
|                                                                             |
|             o2 = ideal (a, b, c, d)                                         |
|                                                                             |
|             o2 : Ideal of R                                                 |
|                                                                             |
|             i3 : C = res I                                                  |
|                                                                             |
|                   1      4      6      4      1                             |
|             o3 = R  <-- R  <-- R  <-- R  <-- R  <-- 0                       |
|                                                                             |
|                  0      1      2      3      4      5                       |
|                                                                             |
|             o3 : ChainComplex                                               |
|                                                                             |
|             i4 : C_2                                                        |
|                                                                             |
|                   6                                                         |
|             o4 = R                                                          |
|                                                                             |
|             o4 : R-module, free, degrees {6:2}                              |
|                                                                             |
|             i5 : C.dd_2                                                     |
|                                                                             |
|             o5 = {1} | -b 0  -c 0  0  -d |                                  |
|                  {1} | a  -c 0  0  -d 0  |                                  |
|                  {1} | 0  b  a  -d 0  0  |                                  |
|                  {1} | 0  0  0  c  b  a  |                                  |
|                                                                             |
|                          4      6                                           |
|             o5 : Matrix R  <-- R                                            |
|                                                                             |
|             i6 :                                                            |
|     ------------------------------------------------------------------------|
|                                )                                            |
|                                                                             |
|     Macaulay2Doc/doc10.m2:256:0                                             |
|                                                                             |
|o1 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i2 : assert not err                                                          |
+-----------------------------------------------------------------------------+

If UserMode => false given, the dictionaries available to the user will not be
affected by the evaluation and collectGarbage, is called
afterwards.

Errors occurred while evaluating str do not cause an error outside of capture.

+-----------------------------------------------------------------------------+
|i3 : (err, output) = capture /// stderr << "Checking a false statement:" <<  |
|                                                                             |
|o3 = (true,                                                            )     |
|            i1 :  stderr << "Checking a false statement:" << endl; 1/0       |
|            Checking a false statement:                                      |
|            currentString:1:51:(3):[3]: error: division by zero              |
|                                                                             |
|                                                                             |
|o3 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|endl; 1/0 ///                                                                |
+-----------------------------------------------------------------------------+
|i4 : assert err                                                              |
+-----------------------------------------------------------------------------+

Certain examples or tests might not be compatible with capture. In such cases,
use the string -* no-capture-flag *- somewhere within str so that the code is
run in a separate Macaulay2 subprocess instead.

See also
========

  * check -- perform tests of a package
  * examples -- list the examples in documentation

Ways to use capture:
====================

  * "capture(List)"
  * "capture(Net)"
  * "capture(String)"
  * capture(TestInput) (missing documentation)

For the programmer
==================

The object capture, is a method function with options.

restart -- restart Macaulay2
****************************

Synopsis
========

  * Usage:
        restart
  * Consequences:
      * the program will be restarted from the beginning

Description
===========

Functions previously registered with addEndFunction, will
be called before the current instance of the program terminates.  Then the
program will be invoked afresh, as described in Invoking the program.

For the programmer
==================

The object restart, is a command.

addEndFunction -- add an ending function
****************************************

Synopsis
========

  * Usage:
        addEndFunction f
  * Inputs:
      * f, a function,
  * Consequences:
      * When the program is about the exit, the function f will be called, with
        no arguments.

For the programmer
==================

The object addEndFunction, is a function closure.

alarm -- set an alarm
*********************

Synopsis
========

  * Usage:
        alarm n
  * Inputs:
      * n, an integer,
  * Consequences:
      * the alarm will be sounded after n seconds; it can be intercepted with
        try,

Description
===========

If n is zero, then no alarm is scheduled, and any previously scheduled alarm is
cancelled. Any pending alarm will be cancelled when any other error occurs, or
when the top level loop offers an input prompt to the user.

The value returned is the number of seconds remaining until any previously
scheduled alarm was due to be delivered, or zero if there was no previously
scheduled alarm.

This command may interfere with time, or sleep, on
some systems.

For the programmer
==================

The object alarm, is a compiled function.

currentDirectory -- current working directory
*********************************************

Synopsis
========

  * Usage:
        currentDirectory()
  * Outputs:
      * the complete path to the current directory, together with an extra
        slash

Description
===========

+--------------------------------------------------------------------+
|i1 : currentDirectory()                                             |
|                                                                    |
|o1 = /home/m2user/src/macaulay2/M2/M2/BUILD/doug/Macaulay2/packages/|
|     Macaulay2Doc-temporary/                                        |
+--------------------------------------------------------------------+

If a component of the path to the current directory no longer exist, an error
will be signalled.

See also
========

  * changeDirectory -- change the current working
    directory

For the programmer
==================

The object currentDirectory, is a compiled function.

exec -- execute another program
*******************************

Synopsis
========

  * Usage:
        exec argv

Description
===========

exec argv  uses the 'exec' operating system call to start up another program,
replacing the current Macaulay2 process. Here argv is a string, or a sequence
or list of strings to be passed as arguments to the new process.  The first
string is the name of the executable file.

For the programmer
==================

The object exec, is a compiled function.

exit -- exit the program
************************

Description
===========

exit n -- terminates the program and returns n as return code.
exit -- terminates the program and returns 0 as return code.

Files are flushed and closed.  Functions registered with addEndFunction,
are called, unless a nonzero return value has been provided.
Another way to exit is to type the end of file character, which is typically
set to Control-D in unix systems, and is Control-Z under Windows.

See also
========

  * quit -- quit the program

For the programmer
==================

The object exit, is a command.

fork -- fork the process
************************

Synopsis
========

  * Usage:
        fork()
  * Outputs:
      * When successful, it returns the process id of the child in the parent,
        and returns 0 in the child.  When unsuccessful, it returns -1.

Description
===========

Platforms that do not have a built-in fork() function will always return -1.

Warning: in multithreaded programs like Macaulay2, very few operations can be
safely done in the child.  This is especially true when the user has been
parallel programming with threads and tasks.
Even allocating memory in the child may hang the process.

For the programmer
==================

The object fork, is a compiled function.

getenv -- get value of environment variable
*******************************************

Description
===========

getenv s yields the value associated with the string s in the environment.

+------------------+
|i1 : getenv "HOME"|
|                  |
|o1 = /home/m2user |
+------------------+

Ways to use getenv:
===================

  * "getenv(String)"

For the programmer
==================

The object getenv, is a compiled function.

processID -- the process identifier
***********************************

Synopsis
========

  * Usage:
        processID()
  * Outputs:
      * an integer, the process identifier of the current Macaulay2
        process

Description
===========

+----------------+
|i1 : processID()|
|                |
|o1 = 2531735    |
+----------------+

See also
========

  * groupID -- the process group identifier
  * setGroupID -- set the process group identifier

For the programmer
==================

The object processID, is a compiled function.

path -- list of directories to look in
**************************************

Description
===========

A list of strings containing names of directories in which load,
input, loadPackage, needsPackage,
and installPackage, should seek files.
These strings are simply concatenated with the filename being sought, so should
include a terminal slash.  One further directory is implicitly searched first:
the directory containing the current input file; when input is coming from the
standard input, that directory is the current directory of the process.

After the core Macaulay2 files are loaded, unless the command line option -q is
encountered, the following subdirectories will be prepended to the path, based
on the value of the applicationDirectory, for your
system.

     /home/m2user/.Macaulay2/code/
     /home/m2user/.Macaulay2/local/share/Macaulay2/
+------------------------------------------------------+
|i1 : stack path                                       |
|                                                      |
|o1 = ./                                               |
|     ../../../../../Macaulay2/packages/               |
|     ../../../usr-dist/common/share/Macaulay2/        |
+------------------------------------------------------+
|i2 : path = append(path, "~/resolutions/"); stack path|
|                                                      |
|o3 = ./                                               |
|     ../../../../../Macaulay2/packages/               |
|     ../../../usr-dist/common/share/Macaulay2/        |
|     ~/resolutions/                                   |
+------------------------------------------------------+

For the programmer
==================

The object path, is a list.

quit -- quit the program
************************

Description
===========

quit -- terminates the program and returns 0 as return code.

Files are flushed and closed.  Another way to exit is to type the end of file
character, which is typically set to Control-D in unix systems, and is
Control-Z under MS-DOS.

See also
========

  * exit -- exit the program

For the programmer
==================

The object quit, is a command.

run -- run an external command
******************************

Synopsis
========

  * Usage:
        run s
  * Inputs:
      * s, a string, a command understandable by the operating
        system
  * Outputs:
      * an integer, the return code

Description
===========

The process is run in the same process group, so signals invoked by control
characters at the terminal will go both to it and to Macaulay2.

Under Linux and Mac OS, the return code is 256 times the exit status code of
the command, if the command exited normally; by convention, an exit status code
of 0 indicates error free execution or the Boolean value true, an exit status
code of 1 indicates an error or the Boolean value false; if the command
terminated in response to a signal or fault, the signal number (in the range
1-126) is returned, added to 128 if a core dump was created; if the shell
(command interpreter) could not be executed, then 127 is returned.  Signal
numbers typically include 2 for interrupt, 3 for quit, 6 for abort, 9 for kill,
11 for segmentation fault, and 15 for termination.  For details, see the man
page of the libc routine system().

For the programmer
==================

The object run, is a compiled function.

sleep -- sleep for a while
**************************

Description
===========

sleep n -- sleeps for n seconds.

See also
========

  * nanosleep -- sleep for a given number of nanoseconds

For the programmer
==================

The object sleep, is a compiled function.

nanosleep -- sleep for a given number of nanoseconds
****************************************************

Description
===========

nanosleep n -- sleeps for n nanoseconds.
+------------------------------------+
|i1 : elapsedTime nanosleep 500000000|
| -- .500092s elapsed                |
|                                    |
|o1 = 0                              |
+------------------------------------+

See also
========

  * sleep -- sleep for a while

For the programmer
==================

The object nanosleep, is a compiled function.

Time -- the class of all timing results
***************************************

Description
===========

Time is the class of all timing results.  Each timing result is a basic list,
of the form {t,v}, where t is the number of seconds of cpu
time used, and v is the value of the expression.

See also
========

  * timing -- time a computation
  * time -- time a computation
  * cpuTime -- seconds of cpu time used since Macaulay2 began
  * elapsedTiming -- time a computation using time
    elapsed
  * elapsedTime -- time a computation including time
    elapsed

Functions and methods returning a timing result:
================================================

  * timing -- time a computation

For the programmer
==================

The object Time, is a type, with ancestor classes
BasicList < Thing.

time -- time a computation
**************************

Synopsis
========

  * Usage:
        time e

Description
===========

time e evaluates e, prints the amount of cpu time used, and returns the value
of e.  The time used by the the current thread and garbage collection during
the evaluation of e is also shown.
+-------------------------------------------------------+
|i1 : time 3^30                                         |
| -- used 9.055e-06s (cpu); 5.125e-06s (thread); 0s (gc)|
|                                                       |
|o1 = 205891132094649                                   |
+-------------------------------------------------------+

See also
========

  * timing -- time a computation
  * cpuTime -- seconds of cpu time used since Macaulay2 began
  * elapsedTiming -- time a computation using time
    elapsed
  * elapsedTime -- time a computation including time
    elapsed

For the programmer
==================

The object time, is a keyword.

timing -- time a computation
****************************

Description
===========

timing e evaluates e and returns a list of type Time, of the form
{t,v}, where t is the number of seconds of cpu timing used, and v is the value
of the expression.

The default method for printing such timing results is to display the timing
separately in a comment below the computed value.
+--------------------------------------+
|i1 : timing 3^30                      |
|                                      |
|o1 = 205891132094649                  |
|     -- .000006763 seconds            |
|                                      |
|o1 : Time                             |
+--------------------------------------+
|i2 : peek oo                          |
|                                      |
|o2 = Time{.000006763, 205891132094649}|
+--------------------------------------+

See also
========

  * Time -- the class of all timing results
  * time -- time a computation
  * cpuTime -- seconds of cpu time used since Macaulay2 began
  * elapsedTiming -- time a computation using time
    elapsed
  * elapsedTime -- time a computation including time
    elapsed

For the programmer
==================

The object timing, is a keyword.

elapsedTime -- time a computation including time elapsed
********************************************************

Synopsis
========

  * Usage:
        elapsedTime e

Description
===========

elapsedTime e evaluates e, prints the amount of time elapsed, and returns the
value of e.
+------------------------+
|i1 : elapsedTime sleep 1|
| -- 1.0001s elapsed     |
|                        |
|o1 = 0                  |
+------------------------+

See also
========

  * elapsedTiming -- time a computation using time
    elapsed
  * cpuTime -- seconds of cpu time used since Macaulay2 began
  * GCstats -- information about the status of the garbage
    collector
  * parallel programming with threads and tasks
  * parallelism in engine computations
    -- parallelism in engine computations

For the programmer
==================

The object elapsedTime, is a keyword.

elapsedTiming -- time a computation using time elapsed
******************************************************

Description
===========

elapsedTiming e evaluates e and returns a list of type Time, of the
form {t,v}, where t is the number of seconds of time elapsed, and v is the
value of the expression.

The default method for printing such timing results is to display the timing
separately in a comment below the computed value.
+--------------------------+
|i1 : elapsedTiming sleep 1|
|                          |
|o1 = 0                    |
|     -- 1.0001 seconds    |
|                          |
|o1 : Time                 |
+--------------------------+
|i2 : peek oo              |
|                          |
|o2 = Time{1.0001, 0}      |
+--------------------------+

See also
========

  * Time -- the class of all timing results
  * elapsedTime -- time a computation including time
    elapsed
  * cpuTime -- seconds of cpu time used since Macaulay2 began
  * timing -- time a computation
  * time -- time a computation

For the programmer
==================

The object elapsedTiming, is a keyword.

wait -- wait for child process
******************************

Description
===========

wait i waits for the completion of child process with process id i.
wait f waits for the input file to have some input ready.
wait s waits for at least one of the files in the list s of input files to be
ready, and return the list of positions corresponding to ready files.
wait v checks whether the processes whose id's are in the list v of integers
have terminated, and returns a list containing the status codes for those
processes that have terminated.  A value of -1 in the list indicates an error
for that process id, and a value of -2 in the list indicates that the process
is still running.

For the programmer
==================

The object wait, is a compiled function.

commandLine -- the command line arguments
*****************************************

Synopsis
========

  * Usage:
        commandLine

Description
===========

A constant whose value is the list of arguments passed to the interpreter,
including argument 0, the name of the program.

See also
========

  * scriptCommandLine -- the command line arguments
    to be used when running a script

For the programmer
==================

The object commandLine, is a list.

environment -- the environment variables
****************************************

Description
===========

A constant whose value is the list containing the environment strings for the
process.

For the programmer
==================

The object environment, is a list.

version -- information about this version of the program
********************************************************

Synopsis
========

  * Usage:
        version
  * Consequences:
      * a hash table, describing this version of the program

Description
===========

The values stored in this hash table depend on the source code version the
architecture for which the program was compiled, and the libraries (both static
and dynamic) against which the program is linked.
+-----------------------------------------------------------------------------+
|i1 : version                                                                 |
|                                                                             |
|o1 = HashTable{"architecture" => x86_64                                      |
|               "boost version" => 1_83                                       |
|               "build" => x86_64-pc-linux-gnu                                |
|               "compile node name" => mixtuppa                               |
|               "compile time" => Nov  1 2024, 10:16:34                       |
|               "compiler" => gcc 13.2.0                                      |
|               "configure arguments" =>  '--with-system-gc' '--with-         |
|               "eigen version" => 3.4.0                                      |
|               "endianness" => dcba                                          |
|               "executable extension" =>                                     |
|               "factory version" => 4.3.2                                    |
|               "fflas_ffpack version" => 2.5.0                               |
|               "flint version" => 3.0.1                                      |
|               "frobby version" => 0.9.5                                     |
|               "gc version" => 8.2.6                                         |
|               "gdbm version" => GDBM version 1.23. 04/02/2022               |
|               "git branch" => master                                        |
|               "git description" => release-1.24.11                          |
|               "gmp version" => 6.3.0                                        |
|               "host" => x86_64-pc-linux-gnu                                 |
|               "issue" => Ubuntu-24.04                                       |
|               "lapack version" => 3.12.0                                    |
|               "libffi version" => 3.4.6                                     |
|               "M2 name" => M2                                               |
|               "M2 suffix" =>                                                |
|               "machine" => x86_64-Linux-Ubuntu-24.04                        |
|               "mathic version" => 1.0                                       |
|               "mathicgb version" => 1.0                                     |
|               "memtailor version" => 1.0                                    |
|               "mpfi version" => 1.5.3                                       |
|               "mpfr version" => 4.2.1                                       |
|               "mpsolve version" => 3.2.1                                    |
|               "mysql version" => not present                                |
|               "normaliz version" => 3.10.2                                  |
|               "ntl version" => 11.5.1                                       |
|               "operating system release" => 6.8.0-47-generic                |
|               "operating system" => Linux                                   |
|               "packages" => Style FirstPackage Macaulay2Doc Parsing         |
|               "pointer size" => 8                                           |
|               "python version" => 3.12.3                                    |
|               "readline version" => 8.2                                     |
|               "scscp version" => not present                                |
|               "tbb version" => 2021.11                                      |
|               "VERSION" => 1.24.11                                          |
|                                                                             |
|o1 : HashTable                                                               |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|system-memtailor' '--with-system-mathic' '--with-system-mathicgb'            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
| Classic Browse Benchmark Text SimpleDoc PackageTemplate Saturation          |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|PrimaryDecomposition FourierMotzkin Dmodules WeylAlgebras HolonomicSystems   |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|BernsteinSato Depth Elimination GenericInitialIdeal IntegralClosure          |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|HyperplaneArrangements LexIdeals Markov NoetherNormalization Points          |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ReesAlgebra Regularity SchurRings SymmetricPolynomials SchurFunctors         |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|SimplicialComplexes LLLBases TangentCone ChainComplexExtras Varieties        |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Schubert2 PushForward LocalRings PruneComplex BoijSoederberg BGG Bruns       |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|InvolutiveBases ConwayPolynomials EdgeIdeals FourTiTwo StatePolytope         |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Polyhedra Truncations Polymake gfanInterface PieriMaps Normaliz Posets XML   |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|OpenMath SCSCP RationalPoints MapleInterface ConvexInterface SRdeformations  |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|NumericalAlgebraicGeometry BeginningMacaulay2 FormalGroupLaws Graphics       |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|WeylGroups HodgeIntegrals Cyclotomic Binomials Kronecker Nauty               |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ToricVectorBundles ModuleDeformations PHCpack SimplicialDecomposability      |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|BooleanGB AdjointIdeal Parametrization Serialization NAGtypes                |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|NormalToricVarieties DGAlgebras Graphs GraphicalModels BIBasis KustinMiller  |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Units NautyGraphs VersalDeformations CharacteristicClasses RandomIdeals      |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|RandomObjects RandomPlaneCurves RandomSpaceCurves RandomGenus14Curves        |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|RandomCanonicalCurves RandomCurves TensorComplexes MonomialAlgebras QthPower |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|EliminationMatrices EllipticIntegrals Triplets                               |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|CompleteIntersectionResolutions EagonResolution MCMApproximations            |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|MultiplierIdeals InvariantRing QuillenSuslin EnumerationCurves               |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Book3264Examples Divisor EllipticCurves HighestWeights MinimalPrimes Bertini |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|TorAlgebra Permanents BinomialEdgeIdeals TateOnProducts LatticePolytopes     |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|FiniteFittingIdeals HigherCIOperators LieTypes ConformalBlocks M0nbar        |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|AnalyzeSheafOnP1 MultiplierIdealsDim2 RunExternalM2 NumericalSchubertCalculus|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ToricTopology Cremona Resultants VectorFields SLPexpressions Miura           |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ResidualIntersections Visualize EquivariantGB ExampleSystems RationalMaps    |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|FastMinors RandomPoints SwitchingFields SpectralSequences SectionRing        |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|OldPolyhedra OldToricVectorBundles K3Carpets ChainComplexOperations          |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|NumericalCertification PhylogeneticTrees MonodromySolver ReactionNetworks    |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|PackageCitations NumericSolutions GradedLieAlgebras InverseSystems Pullback  |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|EngineTests SVDComplexes RandomComplexes CohomCalg Topcom Triangulations     |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ReflexivePolytopesDB AbstractToricVarieties Licenses TestIdeals              |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|FrobeniusThresholds Seminormalization AlgebraicSplines TriangularSets Chordal|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Tropical SymbolicPowers Complexes GroebnerWalk RandomMonomialIdeals Matroids |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|NumericalImplicitization NonminimalComplexes CoincidentRootLoci              |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|RelativeCanonicalResolution RandomCurvesOverVerySmallFiniteFields            |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|StronglyStableIdeals SLnEquivariantMatrices CorrespondenceScrolls NCAlgebra  |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|SpaceCurves ExteriorIdeals ToricInvariants SegreClasses                      |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|SemidefiniteProgramming SumsOfSquares MultiGradedRationalMap                 |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|AssociativeAlgebras VirtualResolutions Quasidegrees DiffAlg                  |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|DeterminantalRepresentations FGLM SpechtModule SchurComplexes                |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|SimplicialPosets SlackIdeals PositivityToricBundles SparseResultants         |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|DecomposableSparseSystems MixedMultiplicity PencilsOfQuadrics ThreadedGB     |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|AdjunctionForSurfaces VectorGraphics GKMVarieties MonomialIntegerPrograms    |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|NoetherianOperators Hadamard StatGraphs GraphicalModelsMLE EigenSolver       |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|MultiplicitySequence ResolutionsOfStanleyReisnerRings NumericalLinearAlgebra |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ResLengthThree MonomialOrbits MultiprojectiveVarieties SpecialFanoFourfolds  |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|RationalPoints2 SuperLinearAlgebra SubalgebraBases AInfinity                 |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|LinearTruncations ThinSincereQuivers Python BettiCharacters Jets             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|FunctionFieldDesingularization HomotopyLieAlgebra TSpreadIdeals RealRoots    |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ExteriorModules K3Surfaces GroebnerStrata QuaternaryQuartics                 |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|CotangentSchubert OnlineLookup MergeTeX Probability Isomorphism CodingTheory |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|WhitneyStratifications JSON ForeignFunctions GeometricDecomposability        |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|PseudomonomialPrimaryDecomposition PolyominoIdeals MatchingFields            |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|CellularResolutions SagbiGbDetection A1BrouwerDegrees                        |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|QuadraticIdealExamplesByRoos TerraciniLoci MatrixSchubert RInterface         |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|OIGroebnerBases PlaneCurveLinearSeries Valuations SchurVeronese VNumber      |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|TropicalToric MultigradedBGG AbstractSimplicialComplexes                     |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|MultigradedImplicitization Msolve Permutations SCMAlgebras                   |
|-----------------------------------------------------------------------------|
|                   }                                                         |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|NumericalSemigroups                                                          |
+-----------------------------------------------------------------------------+

For the programmer
==================

The object version, is a hash table.

collectGarbage -- collect the garbage in memory
***********************************************

Synopsis
========

  * Usage:
        collectGarbage()
  * Consequences:
      * garbage is collected

See also
========

  * GC garbage collector

For the programmer
==================

The object collectGarbage, is a compiled function.

registerFinalizer -- register a string that will be displayed when an object is garbage collected
*************************************************************************************************

Synopsis
========

  * Usage:
        registerFinalizer(x,str)
  * Inputs:
      * x, a thing,
      * str, a string,
  * Consequences:
      * A finalizer is registered with the garbage collector to print a string
        when that object is collected as garbage

Description
===========

+-----------------------------------------------------------------------------+
|i1 : for i from 1 to 9 do (x := 0 .. 10000 ; registerFinalizer(x, "--        |
|-----------------------------------------------------------------------------|
|finalizing sequence #"|i|" --"))                                             |
+-----------------------------------------------------------------------------+
|i2 : collectGarbage()                                                        |
|--finalization: (1)[0]: -- finalizing sequence #1 --                         |
|--finalization: (2)[2]: -- finalizing sequence #3 --                         |
|--finalization: (3)[3]: -- finalizing sequence #4 --                         |
|--finalization: (4)[6]: -- finalizing sequence #7 --                         |
|--finalization: (5)[1]: -- finalizing sequence #2 --                         |
|--finalization: (6)[7]: -- finalizing sequence #8 --                         |
|--finalization: (7)[4]: -- finalizing sequence #5 --                         |
|--finalization: (8)[8]: -- finalizing sequence #9 --                         |
|--finalization: (9)[5]: -- finalizing sequence #6 --                         |
+-----------------------------------------------------------------------------+

Caveat
======

This function should mainly be used for debugging.  Having a large number of
finalizers might degrade the performance of the program.  Moreover, registering
two or more objects that are members of a circular chain of pointers for
finalization will result in a memory leak, with none of the objects in the
chain being freed, even if nothing else points to any of them.

See also
========

  * collectGarbage -- collect the garbage in memory

Ways to use registerFinalizer:
==============================

  * registerFinalizer(Thing,String) (missing documentation)

For the programmer
==================

The object registerFinalizer, is a method function.

debugging
*********

Macaulay2 has a debugger.
  * the debugger
Here are some other debugging tools.
  * assert -- check whether something is true, raise an error if
    not
  * benchmark -- accurate timing of execution
  * browse (Browse) -- browse the contents of an object
  * code -- display source code
  * current -- the pseudocode that produced an error
  * currentFileName -- the current source file
  * pseudocode -- produce the pseudocode for a function
  * disassemble -- disassemble a pseudocode or function
  * edit -- edit source code
  * error -- deliver error message
  * errorDepth -- set the error printing depth
  * flagLookup -- flag a symbol
  * listLocalSymbols -- display of local symbols and
    their values
  * listUserSymbols -- display the user's symbols
  * locate -- locate source code
  * methods -- list methods
  * on -- trace a function each time it's run
  * peek -- examine contents of an object
  * peek' -- examine contents of an object
  * profile -- profile a function
  * shield -- shield evaluation from interrupts
  * showStructure -- display parent structure
  * showUserStructure -- show parent structure for
    those types defined by user
  * try -- catch an error
  * userSymbols -- a list of the user's symbols

packages provided with Macaulay2
********************************

Here is a list of the packages that are distributed with Macaulay2. The ones
that have been refereed and published are marked with a star.

Algebraic Geometry
==================

  * Cremona, a gold star -- rational maps between
    projective varieties
  * HyperplaneArrangements -- manipulating
    finite sets of hyperplanes
  * Jets, a gold star -- compute jets of various algebraic,
    geometric and combinatorial objects
  * K3Surfaces -- Explicit constructions of K3 surfaces
  * NumericalSemigroups -- Compute the Apery
    set and invariants of a numerical semigroup ring
  * PencilsOfQuadrics -- Clifford Algebra of a
    pencil of quadratic forms
  * SpecialFanoFourfolds, a gold star --
    Hodge-special fourfolds
  * Varieties -- routines for working with affine and
    projective varieties and coherent sheaves on them
  * WhitneyStratifications -- Compute
    Whitney Statifications Algebraically & Stratifies Maps

Algebraic Number Theory
=======================

  * Cyclotomic -- cyclotomic fields
  * EllipticCurves -- group law on elliptic curves
    (and counting points with brute force methods)
  * LLLBases -- Lenstra-Lenstra-Lovasz bases

Algebraic Statistics
====================

  * GraphicalModels, a gold star -- discrete and
    Gaussian graphical models
  * GraphicalModelsMLE, a gold star -- maximum
    likelihood estimates for graphical statistical models
  * Markov -- Markov ideals arising from Bayesian networks
    in statistics
  * MultigradedImplicitization, --
    solving implicitization problems using multigradings
  * Probability, a gold star -- basic probability
    functions
  * StatGraphs -- Graphs specific for algebraic
    statistics

Applied Algebraic Geometry
==========================

  * AlgebraicSplines -- splines on simplicial
    complexes, polytopal complexes, and graphs
  * PhylogeneticTrees, a gold star -- invariants
    for group-based phylogenetic models
  * ReactionNetworks -- reaction networks

Coding Theory
=============

  * CodingTheory, a gold star -- tools for coding
    theory

Combinatorial Commutative Algebra
=================================

  * AbstractSimplicialComplexes, --
    Abstract Simplicial Complexes
  * MonomialOrbits -- Orbit representatives of
    monomial ideals
  * PolyominoIdeals -- binomial ideals of
    collections of cells
  * ResolutionsOfStanleyReisnerRings
    -- Comparing resolutions of
    Stanley-Reisner rings and computing various systems of parameters
  * SimplicialComplexes, a gold star --
    exploring abstract simplicial complexes within commutative algebra
  * SimplicialDecomposability, a gold
    star -- various decomposability routines for simplicial complexes
  * SimplicialPosets -- constructing Stanley
    simplicial poset rings
  * SRdeformations -- deformations of
    Stanley-Reisner rings and related computations

Combinatorics
=============

  * MatrixSchubert -- functions for investigating
    ASM and matrix Schubert varieties
  * NumericalSemigroups -- Compute the Apery
    set and invariants of a numerical semigroup ring
  * Permutations -- functions for working with
    permutations
  * Posets, a gold star -- partially ordered sets (posets)
  * SymmetricPolynomials -- symmetric
    polynomials
  * Triangulations -- triangulations of polyhedra
    and point sets

Commutative Algebra
===================

  * A1BrouwerDegrees, a gold star -- A1-Brouwer
    degree computations
  * AdjointIdeal -- adjoint ideals of plane curves
    and related computations
  * AInfinity -- AInfinity structures on free
    resolutions
  * AnalyzeSheafOnP1 -- decompose a Sheaf on P1
  * BettiCharacters, a gold star -- finite group
    characters on free resolutions and graded modules
  * BGG -- Bernstein-Gelfand-Gelfand correspondence
  * Binomials, a gold star -- specialized routines for
    binomial ideals
  * BoijSoederberg -- Betti diagram operations
    useful for investigating the Boij-Soederberg conjectures
  * Bruns -- make a 3-generator ideal with an "any"
    resolution
  * CellularResolutions -- cellular
    resolutions of monomial ideals
  * Chordal -- routines that exploit chordal structure
  * CompleteIntersectionResolutions
    -- Analyzing Resolutions over a
    Complete Intersection
  * ConformalBlocks, a gold star -- for conformal
    block divisors
  * CorrespondenceScrolls -- correspondence
    scrolls
  * Depth -- aids in computations related to depth
  * DeterminantalRepresentations, a
    gold star -- determinantal representations
  * DGAlgebras -- Data type for DG algebras
  * DiffAlg, a gold star -- specialized routines for
    differential forms
  * Divisor, a gold star -- Weil divisors
  * EagonResolution -- Compute the Eagon
    Resolution of the residue field
  * Elimination -- elimination of variables
  * EliminationMatrices -- resultants
  * EnumerationCurves -- Enumeration of rational
    curves via torus actions
  * ExteriorIdeals, a gold star -- monomial ideals
    over exterior algebras
  * ExteriorModules, a gold star -- monomial
    modules over exterior algebras
  * FiniteFittingIdeals -- Fitting ideals of
    finite modules
  * FrobeniusThresholds, a gold star --
    F-thresholds
  * FunctionFieldDesingularization,
    -- desingularization of function fields
  * GenericInitialIdeal -- find the generic
    initial ideal of a given ideal
  * GeometricDecomposability, a gold star
    -- checking whether ideals are geometrically vertex decomposable
  * GroebnerStrata -- computing Groebner loci in
    Hilbert schemes
  * Hadamard -- Hadamard products of projective
    subvarieties
  * HigherCIOperators -- higher CI operators
  * HodgeIntegrals, a gold star -- Hodge integrals
    on the moduli space of curves
  * IntegralClosure -- integral closure
  * InverseSystems -- equivariant Macaulay inverse
    systems
  * Isomorphism -- Probabilistic test of isomorphism
    between modules
  * K3Carpets -- K3 double structure on scrolls
  * Kronecker -- Kronecker and rational normal forms
  * KustinMiller, a gold star -- unprojection and the
    Kustin-Miller complex construction
  * LexIdeals -- lexicographic-type monomial ideals
  * LinearTruncations, a gold star -- find the
    multigraded truncations that give linear resolutions
  * LocalRings -- operations over a local ring R_p
  * M0nbar -- calculations for divisors and F-curves on the
    moduli space of stable n-pointed genus zero curves
  * MatrixSchubert -- functions for investigating
    ASM and matrix Schubert varieties
  * MCMApproximations -- MCM approximations and
    complete intersections
  * MinimalPrimes -- minimal primes and radical
    routines for ideals
  * Miura -- arithmetic of Miura curves
  * MixedMultiplicity, a gold star -- Mixed
    Multiplicities of ideals
  * MonomialAlgebras, a gold star -- monomial
    algebras
  * MonomialIntegerPrograms -- using
    integer programming for fast computations with monomial ideals
  * MultigradedBGG -- the multigraded BGG
    correspondence and differential modules
  * MultigradedImplicitization, --
    solving implicitization problems using multigradings
  * MultiGradedRationalMap -- degree and
    birationality of multi-graded rational maps
  * MultiplicitySequence, a gold star --
    computing the multiplicity sequence of an ideal
  * NoetherianOperators, a gold star --
    algorithms for computing local dual spaces and sets of Noetherian operators
  * NoetherNormalization -- place an ideal in
    Noether normal position
  * NonminimalComplexes -- non-minimal strands
    of a non-minimal resolution of a homogeneous module
  * NumericalSemigroups -- Compute the Apery
    set and invariants of a numerical semigroup ring
  * OIGroebnerBases -- OI-modules over Noetherian
    polynomial OI-algebras
  * Parametrization -- rational parametrization of
    rational plane curves and related computations
  * PencilsOfQuadrics -- Clifford Algebra of a
    pencil of quadratic forms
  * Permanents -- permanents of a matrix
  * PrimaryDecomposition -- primary
    decomposition and associated primes routines
  * PruneComplex -- pruning chain complexes over
    polynomial and local rings
  * PseudomonomialPrimaryDecomposition,
    a gold star -- Primary
    decomposition of square free pseudomonomial ideals
  * Pullback -- pullback of rings
  * PushForward -- push forwards of finite ring maps
  * QthPower -- An implementation of the Qth-Power
    algorithm for computing integral closures
  * Quasidegrees, a gold star -- quasidegrees and
    graded local cohomology
  * QuillenSuslin, a gold star -- the Quillen-Suslin
    algorithm for bases of projective modules
  * RationalMaps, a gold star -- rational maps between
    varieties
  * RationalPoints -- find the common zeroes of a
    set of polynomials with coefficients in a finite field
  * RationalPoints2 -- find the rational points on
    a variety
  * ReesAlgebra, a gold star -- Rees algebras
  * Regularity -- Castelnuovo-Mumford regularity of a
    homogeneous ideal
  * RelativeCanonicalResolution, a gold
    star -- the relative canonical resolution for g-nodal canonical curves with
    a fixed g^1_k
  * ResidualIntersections -- conditions
    associated to residual intersection theory
  * Resultants, a gold star -- resultants,
    discriminants, and Chow forms
  * SagbiGbDetection -- finding term orders for
    which the given generators of an ideal/algebra form a Gröbner/SAGBI basis
  * Saturation -- quotient, saturation, and annihilator
    routines for ideals and modules
  * SCMAlgebras -- sequentially Cohen-Macaulay modules
    or ideals
  * SectionRing -- the section ring of a Weil Divisor
  * Seminormalization, a gold star --
    seminormalization of rings
  * SlackIdeals -- Slack ideals of polytopes and
    matroids
  * SparseResultants, a gold star -- computations
    with sparse resultants
  * StronglyStableIdeals, a gold star --
    studying strongly stable ideals related to Hilbert polynomials
  * SubalgebraBases, a gold star -- Canonical
    subalgebra bases (aka SAGBI/Khovanskii bases)
  * SVDComplexes -- SVD (singular value
    decomposition) of a complex over the reals and related functions
  * SwitchingFields -- Switch Base Fields and
    Obtain Natural Maps
  * SymbolicPowers, a gold star -- symbolic powers
  * TangentCone -- tangent cones
  * TateOnProducts -- Tate resolutions on products
    of projective spaces
  * TensorComplexes -- multilinear algebra with
    labeled bases
  * TestIdeals, a gold star -- singularities in positive
    characteristic
  * TriangularSets -- triangular decompositions of
    ideals
  * Triplets -- triplets of degree sequences and
    associated Betti diagrams and cohomology tables
  * Truncations -- truncation of a module
  * TSpreadIdeals -- t-spread ideals of a polynomial
    ring
  * Valuations -- implementation of valuations for
    rings
  * VectorFields -- vector fields
  * VirtualResolutions, a gold star -- Methods
    for virtual resolutions on products of projective spaces

Complex Analytic Geometry
=========================

  * EllipticIntegrals -- uniformization of
    elliptic curves

Convex Geometry
===============

  * FourierMotzkin -- convex hulls and polar cones
  * LatticePolytopes -- lattice polytopes
  * OldPolyhedra, a gold star -- convex polyhedra
  * Polyhedra, a gold star -- convex polyhedra
  * ReflexivePolytopesDB -- simple access to
    Kreuzer-Skarke database of reflexive polytopes of dimensions 3 and 4
  * StatePolytope -- the state polytope of an ideal

D-modules
=========

  * BernsteinSato -- Bernstein-Sato
  * Dmodules -- D-modules
  * HolonomicSystems -- Holonomic Systems
  * MultiplierIdeals, a gold star -- multiplier
    ideals, log canonical thresholds, and jumping numbers
  * MultiplierIdealsDim2 -- multiplier ideals
    in 2-dimensional rings
  * WeylAlgebras -- D-modules

Deformation Theory
==================

  * ModuleDeformations, a gold star -- versal
    deformations of maximal Cohen-Macaulay modules
  * VersalDeformations, a gold star -- versal
    deformations and local Hilbert schemes

Documentation
=============

  * BeginningMacaulay2 -- Mathematicians'
    Introduction to Macaulay2
  * FirstPackage -- an example Macaulay2 package
  * Macaulay2Doc -- Macaulay2 documentation
  * PackageTemplate -- an example Macaulay2
    package
  * SimpleDoc -- a simple documentation function
  * Style -- style sheets and images for the documentation
  * Text -- documentation and hypertext
  * VNumber -- compute v-number of homogeneous ideals and
    v-function of monomial ideals

Edge Ideals
===========

  * BinomialEdgeIdeals -- binomial edge ideals
  * EdgeIdeals, a gold star -- edge ideals

Equivariant Cohomology
======================

  * GKMVarieties -- computations with GKM manifolds
    and moment graphs

Examples and Random Objects
===========================

  * ExampleSystems -- database of polynomial
    systems
  * Points -- sets of points
  * QuadraticIdealExamplesByRoos, --
    Examples of Quadratic Ideals with Embedding Dimension Four by Jan-Erik Roos
  * QuaternaryQuartics -- code to support the
    paper 'Quaternary Quartic Forms and Gorenstein Rings'
  * RandomCanonicalCurves -- Construction of
    random smooth canonical curves up to genus 14
  * RandomComplexes -- random complexes over
    fields or the integers
  * RandomCurves -- random curves
  * RandomCurvesOverVerySmallFiniteFields
    -- general canonical curves of
    genus <= 15 over fields with small characteristic
  * RandomGenus14Curves -- random smooth
    curves of genus 14
  * RandomIdeals -- creating random ideals of various
    sorts
  * RandomMonomialIdeals, a gold star --
    Erdos-Renyi-type random monomial ideals
  * RandomObjects -- a framework for making random
    objects in algebraic geometry
  * RandomPlaneCurves -- random plane curves
  * RandomPoints, a gold star -- find a point in a
    given variety over a finite field
  * RandomSpaceCurves -- random smooth space
    curves
  * SpaceCurves, a gold star -- space curves

Flag Varieties
==============

  * GKMVarieties -- computations with GKM manifolds
    and moment graphs
  * MatchingFields -- Toric degenerations of flag
    varieties via matching fields
  * NumericalSchubertCalculus, --
    numerical methods in Schubert Calculus

Graph Theory
============

  * Chordal -- routines that exploit chordal structure
  * GraphicalModels, a gold star -- discrete and
    Gaussian graphical models
  * Graphs -- graphs and directed graphs (digraphs)
  * Nauty, a gold star -- interface to nauty
  * NautyGraphs -- interface to nauty (Graphs fork)
  * StatGraphs -- Graphs specific for algebraic
    statistics

Graphics
========

  * Graphics -- create graphics
  * VectorGraphics -- producing SVG graphics
  * Visualize -- interactive visualization and
    manipulation of combinatorial objects in a browser

Groebner Basis Algorithms
=========================

  * BIBasis -- involutive Pommaret basis in a Boolean ring
  * BooleanGB -- Groebner bases for ideals in Boolean
    polynomial quotient rings
  * EquivariantGB -- Equivariant Groebner bases and
    related algorithms
  * FGLM -- Groebner bases via the FGLM algorithm
  * GroebnerWalk -- Groebner bases via the Groebner
    walk
  * InvolutiveBases -- Methods for Janet bases and
    Pommaret bases in Macaulay 2
  * Msolve -- interface to the msolve library for solving
    multivariate polynomial systems using Groebner Bases
  * ThreadedGB, a gold star -- Compute a Groebner basis
    using the classical Buchberger with multiple threads

Group Theory
============

  * ConwayPolynomials -- a database of Conway
    polynomials
  * FormalGroupLaws -- commutative formal group
    laws
  * InvariantRing, a gold star -- invariants of group
    actions

Homological Algebra
===================

  * ChainComplexExtras -- some additional
    ChainComplex Functions
  * ChainComplexOperations -- sym2, wedge2,
    chi2 of a ChainComplex
  * Complexes -- beta testing new version of chain
    complexes
  * HighestWeights, a gold star -- decompose free
    resolutions and graded modules with a semisimple Lie group action
  * Isomorphism -- Probabilistic test of isomorphism
    between modules
  * NonminimalComplexes -- non-minimal strands
    of a non-minimal resolution of a homogeneous module
  * PruneComplex -- pruning chain complexes over
    polynomial and local rings
  * ResLengthThree -- Multiplication in free
    resolutions of length three
  * SchurComplexes, a gold star -- Schur functors of
    complexes
  * SchurFunctors -- Schur modules and maps between
    them
  * SpectralSequences -- spectral sequences
  * SVDComplexes -- SVD (singular value
    decomposition) of a complex over the reals and related functions
  * TorAlgebra, a gold star -- classification of local
    rings based on multiplication in homology
  * Varieties -- routines for working with affine and
    projective varieties and coherent sheaves on them
  * VirtualResolutions, a gold star -- Methods
    for virtual resolutions on products of projective spaces

Homotopy Theory
===============

  * A1BrouwerDegrees, a gold star -- A1-Brouwer
    degree computations

Interfaces
==========

  * Bertini -- interface to Bertini
  * CohomCalg -- interface to cohomCalg software for
    computing sheaf cohomology of line bundles on toric varieties
  * CoincidentRootLoci -- coincident root loci
  * ConvexInterface -- interface to Convex
  * ForeignFunctions -- foreign function
    interface
  * FourTiTwo -- Interface to 4ti2
  * gfanInterface -- interface to Anders Jensen's
    Gfan software
  * MapleInterface -- interface to Maple
  * Msolve -- interface to the msolve library for solving
    multivariate polynomial systems using Groebner Bases
  * Nauty, a gold star -- interface to nauty
  * NautyGraphs -- interface to nauty (Graphs fork)
  * NCAlgebra -- data types for noncommutative algebras
  * Normaliz, a gold star -- interface to Normaliz in
    Macaulay2
  * PHCpack, a gold star -- interface to PHCpack
  * Polymake -- interfacing with polymake
  * Python -- interface to Python
  * RInterface -- interface to R for statistical
    computing
  * SemidefiniteProgramming, --
    semidefinite programming
  * StatePolytope -- the state polytope of an ideal
  * Topcom -- interface to the topcom software package
    which in particular computes triangulations

Intersection Theory
===================

  * AbstractToricVarieties -- links
    abstract simplicial (normal) toric varieties to Schubert2
  * Book3264Examples -- examples to accompany the
    eponymous book by Eisenbud and Harris
  * CharacteristicClasses, a gold star -- CSM
    and Segre classes and the Euler characteristic for subschemes of smooth
    complete toric varieties
  * CotangentSchubert, a gold star -- Cotangent
    Schubert calculus
  * Schubert2 -- characteristic classes for varieties
    without equations
  * SegreClasses -- Segre class computations for
    containment of varieties and Fulton-MacPherson intersection products

Lie Groups and Lie Algebras
===========================

  * GradedLieAlgebras, a gold star --
    computations in graded Lie algebras
  * HighestWeights, a gold star -- decompose free
    resolutions and graded modules with a semisimple Lie group action
  * HomotopyLieAlgebra -- Homotopy Lie algebra
  * LieTypes, a gold star -- common types and methods for
    Lie groups and Lie algebras
  * WeylGroups -- root systems and Weyl groups

Linear Algebra
==============

  * FastMinors, a gold star -- faster linear algebra
    operations
  * LLLBases -- Lenstra-Lenstra-Lovasz bases
  * SuperLinearAlgebra -- computations related
    to supermatrices

Matroids
========

  * GKMVarieties -- computations with GKM manifolds
    and moment graphs
  * HyperplaneArrangements -- manipulating
    finite sets of hyperplanes
  * Matroids, a gold star -- computations with matroids
  * SlackIdeals -- Slack ideals of polytopes and
    matroids

Miscellaneous
=============

  * Benchmark -- standard Macaulay2 benchmarks
  * Browse -- a method for browsing and examining Macaulay2
    data structures
  * EngineTests -- a test suite for the Macaulay2
    engine
  * Licenses -- licensing of Macaulay2
  * PackageCitations -- citation of Macaulay2
    packages
  * Units -- units conversion and physical constants
  * XML -- an XML parser

Noncommutative Algebra
======================

  * AssociativeAlgebras -- Noncommutative
    algebra
  * NCAlgebra -- data types for noncommutative algebras

Numerical Algebraic Geometry
============================

  * Bertini -- interface to Bertini
  * DecomposableSparseSystems, a gold
    star -- Solving decomposable sparse systems
  * EigenSolver -- polynomial system solver via
    eigen-computations
  * EllipticIntegrals -- uniformization of
    elliptic curves
  * MonodromySolver -- solving polynomial systems
    via monodromy
  * NAGtypes -- types used in Numerical Algebraic
    Geometry
  * NoetherianOperators, a gold star --
    algorithms for computing local dual spaces and sets of Noetherian operators
  * NumericalAlgebraicGeometry, a gold
    star -- numerical algebraic geometry
  * NumericalCertification -- numerical
    certification
  * NumericalImplicitization, a gold star
    -- numerical invariants of images of varieties
  * NumericalSchubertCalculus, --
    numerical methods in Schubert Calculus
  * NumericSolutions -- solving systems of
    polynomial equalities
  * PHCpack, a gold star -- interface to PHCpack
  * SLPexpressions -- straight line programs and
    algebraic circuits

Numerical Linear Algebra
========================

  * NumericalLinearAlgebra -- numerically
    compute local dual space and Hilbert functions

Projective Algebraic Geometry
=============================

  * AdjunctionForSurfaces -- Adjunction for
    Surfaces
  * Isomorphism -- Probabilistic test of isomorphism
    between modules
  * MultiprojectiveVarieties, a gold star
    -- multi-projective varieties and multi-rational maps
  * PlaneCurveLinearSeries -- Linear series
    on the normalization of a plane curve
  * SchurVeronese, a gold star -- Data for Veronese
    embeddings of projective space
  * TerraciniLoci -- Terracini loci of projective
    varieties

Real Algebraic Geometry
=======================

  * CoincidentRootLoci -- coincident root loci
  * RealRoots -- symbolically exploring, counting, and
    locating real solutions to general polynomial systems
  * SemidefiniteProgramming, --
    semidefinite programming
  * SumsOfSquares, a gold star -- sums of squares

Representation Theory
=====================

  * DeterminantalRepresentations, a
    gold star -- determinantal representations
  * InvariantRing, a gold star -- invariants of group
    actions
  * PieriMaps, a gold star -- maps between
    representations of the general linear group based on the Pieri formulas
  * SchurComplexes, a gold star -- Schur functors of
    complexes
  * SchurFunctors -- Schur modules and maps between
    them
  * SchurRings -- representation rings of general
    linear groups and of symmetric groups
  * SLnEquivariantMatrices -- file
    ancillary to the paper "A construction of equivariant bundles on the space
    of symmetric forms"
  * SpechtModule -- invariants for permutation groups
  * SymmetricPolynomials -- symmetric
    polynomials

System
======

  * Classic -- a classic Macaulay parser
  * JSON -- JSON encoding and decoding
  * MergeTeX -- Run Macaulay2 code inside a LaTeX file
  * OnlineLookup -- Look up mathematical information
    online
  * OpenMath -- OpenMath for Macaulay2
  * Parsing -- a framework for creating recursive descent
    parsers
  * RunExternalM2 -- run Macaulay2 functions outside
    the current Macaulay2 process
  * SCSCP -- SCSCP for Macaulay2
  * Serialization -- reversible conversion of all
    Macaulay2 objects to strings

Toric Geometry
==============

  * AbstractToricVarieties -- links
    abstract simplicial (normal) toric varieties to Schubert2
  * CohomCalg -- interface to cohomCalg software for
    computing sheaf cohomology of line bundles on toric varieties
  * GKMVarieties -- computations with GKM manifolds
    and moment graphs
  * NormalToricVarieties -- routines for
    working with normal toric varieties and related objects
  * OldToricVectorBundles, a gold star --
    vector bundles on toric varieties
  * PositivityToricBundles -- check
    positivity of toric vector bundles
  * ThinSincereQuivers -- Construction of flow
    polytopes and their associated quivers
  * ToricInvariants -- Euclidean distance degrees,
    polar degrees, and Chern-Mather classes of toric varieties
  * ToricTopology -- toric topology
  * ToricVectorBundles, a gold star -- vector
    bundles on toric varieties

Tropical Geometry
=================

  * Tropical -- computations in tropical geometry
  * TropicalToric, a gold star -- tropical methods
    for toric intersection theory

See also
========

  * packages -- Macaulay2 packages
  * authors of Macaulay2 packages

authors of Macaulay2 packages
*****************************

The following people have authored packages that are distributed with
Macaulay2:

Hirotachi Abo, Michael Adamer, Ashleigh Adams, Tair Akhmejanov, Davide
Alberelli, Ayah Almousa, Colin Alstad, Luca Amata, Carlos Amendola, Katie
Ansaldi, Elizabeth Arnold, Hector Baños, Fereshteh Bahadorykhalily, Taylor
Ball, Maya Banks, Mary Barker, Roberto Barrera, Brett Barwick, Dan Bates, Erin
Bela, Christine Berkesch, David Berlekamp, Daniel Irving Bernstein, René
Birkner, Sankhaneel Bisui, Janko Boehm, Mats Boij, Alberto F. Boix, Adam
Boocher, Christian Bopp, Ada Boralevi, Nikita Borisov, Viktoriia Borovik,
Alessio Borzì, Nicolás Botbol, Hans-Christian Graf v. Bothmer, C.J. Bott,
Thomas Brazelton, Michael K. Brown, Juliette Bruce, Taylor Brysiewicz, Jack
Burkart, Michael Burr, Laurent Busé, Nathaniel Bushek, Andrew Bydlon, Michael
Byrd, Baptiste Calmès, Baptiste Calmes, Abraham Martin del Campo, Eduardo
Camps, Edward Carter, Justin Chen, Henry Chimal-Dzul, Lars Winther Christensen,
Yairon Cid-Ruiz, Diego Cifuentes, Carmelo Cisto, Oliver Clarke, Andrew Conner,
Shelby Cox, Charley Crissman, Marilena Crupi, Mike Cummings, Joseph Cummings,
Ferran Dachs-Cadefau, Aaron Dall, Hiep Dang, Ruth Davidson, Eduardo Torres
Davila, Wolfram Decker, Graham Denham, Papri Dey, Michael DiPasquale, Jane Doe,
Eliana Duarte, Manuel Dubinsky, Timothy Duff, David Eisenbud, Drew Ellingson,
Thomas Enkosky, Daniel Erman, Frenly Espino, Chris Eur, Daniele Faenzi, Luigi
Ferraro, Antonino Ficarra, Gunnar Floystad, Chris Francisco, Federico Galetto,
Patricio Gallardo, Francesco Galuppi, Francesca Gandini, Jordy Lopez Garcia,
Florian Geiss, Courtney George, Courtney Gibbons, Kriti Goel, Leah Gold, Steve
Goldstein, Tara Gomes, Sean Grate, Daniel R. Grayson, Nathan Grieve, Eloisa
Grifo, Elizabeth Gross, Tom Hagedorn, Zhaobo Han, Marc Harkonen, Corey Harris,
Pamela Harris, S. Hamid Hassanzadeh, Thomas Hawes, Lauren Cranton Heller,
Martin Helmer, Daniel Hernández, Ben Hersey, Cvetelina Hill, Chris Hillar,
Franziska Hinkelmann, Andreas Hochenegger, Andrew Hoefel, Michael Hoff,
Benjamin Hollering, Bradford Hovinen, Hang Huang, Daoji Huang, Amy Huang,
Genevieve Hummel, Craig Huneke, Nicholas Iammarino, David Cook II, Nathan
Ilten, Alexandru Iosif, Iman Bahmani Jafarloo, Rizwan Jahangir, Caroline
Jansen, Delio Jaramillo-Velez, Anders Nedergaard Jensen, Zhan Jiang, Parker
Joncus, Kristine Jones, Christine Jost, Zhibek Kadyrsizova, Gesa Kaempf, Thomas
Kahle, Gregorz Kapustka, Michal Kapustka, Fatemeh Tarashi Kashani, Lars
Kastner, Mordechai Katzman, Joe Kileel, Yeongrak Kim, Youngsu Kim, Patricia
Klein, Kathlen Kohn, Daniel Kosmas, Jakob Kröker, Robert Krone, Olga
Kuznetsova, Clas Löfwall, Adam LaClair, Sara Lamboglia, Robert Laudone, Ernesto
Lax, Jackson Leaman, Kisun Lee, Paolo Lella, Douglas A. Leonard, Anton Leykin,
Colby Long, Michael Loper, Hiram H. Lopez, Joel Louwsma, Anders Lundman, Samuel
Lundqvist, Yuyuan Luo, Antonio Macchia, Diane Maclagan, Sarasij Maitra, Sara
Malec, Devlin Mallory, Kelly Maluccio, Sonja Mapes, Stefano Marseglia, Boyana
Martinova, Cesar Massri, Matthew Mastroeni, Joseph McDonough, Laura Menini,
Ariel Molinuevo, Jonathan Montaño, Han-Bom Moon, Frank Moore, Michael Morrow,
Maral Mostafazadehfard, Harshit J Motwani, Vivek Mukundan, Francesco Navarra,
Navid Nemati, Thai Nguyen, Xianglong Ni, Jonathan Niño, Nathan Nichols, Max
Nitsche, Augustine O'Keefe, Alessandro Oneto, Wern Juin Gabriel Ong, Richard
Osborn, Tomas Pajdla, Stavros Papadakis, Pablo A. Parrilo, Ethan Partida, Dylan
Peifer, Matthew Perkins, Michael Perlman, Lars Petersen, Viktor Petrov, Sonja
Petrovic, Helfried Peyrl, Brian Pike, Erika Pirnes, Roser Homs Pons, Sorin
Popescu, Corrado Possieri, Luis David Garcia Puente, Federico Quallbrunn,
Claudiu Raicu, Ritvik Ramkumar, Kristian Ranestad, Daniel Robertz, Elina
Robeva, Marcus Robinson, Jose Israel Rodriguez, Dan Roozemond, Sudeshna Roy,
Yairon Cid Ruiz, Steven V Sam, Alessio Sammartano, Pierpaola Santarsiero, Joao
Pedro Santos, Sasha   Zotine, Mahrud Sayrafi, Hal Schenck, Frank-Olaf Schreyer,
Karl Schwede, Alexandra Seceleanu, Bernard Serbinowski, Emanuele Sgroi, Elima
Shehu, Lily Silverstein, Deepak Sireeshan, Joseph W. Skelton, Gregory G. Smith,
Ben Smith, Daniel Smolkin, Dan Smolkin, Bart Snapp, Aleksandra Sobieska,
Christof Soeger, Jeff Sommars, Jieao Song, Ivan Soprunov, Frank Sottile,
Prashanth Sridhar, Gustav Sædén Ståhl, Giovanni Staglianò, Dumitru Stamate,
Nathaniel Stapleton, Despina Stasi, Avi Steiner, AJ Stewart, Michael E.
Stillman, Branden Stone, Stein A. Strømme, Alexander I. Suciu, Seth Sullivant,
Joe Suzuki, Dave Swinarski, David Swinarski, Andrew Tawfeek, Amelia Taylor,
Zach Teitler, Pedro Teixeira, Antonio Tornambe, Doug Torrance, Alvise Trevisan,
Paolo Tripoli, Harrison Tsai, Ettore Teixeira Turatti, Adam Van Tuyl, Ravi
Vakil, Jim Vallandingham, Keller VandeBogert, Mauricio Velasco, Oana Veliche,
Alan A. Veliz-Cuba, German Vera, J. K. Verma, Jan Verschelde, Thanh Vu, Robert
Walker, Elise Walker, Gwyn Whieldon, Jay White, Amy Wiebe, Dane Wilburne,
Tobias Windisch, Emily Witt, Carolyn Yackel, Thomas Yahl, Jay Yang, Zhaoning
Yang, Stephanie Yang, Yuhui (Wei) Yao, Teresa Yu, Josephine Yu, Beihui Yuan,
Monica Yun, Magdalena Zajaczkowska, Sara Jamshidi Zelenberg, Mengyuan Zhang,
Tanner Zielinski, Mikhail Zinin, Paul Zinn-Justin, Jacob Zoromski, Alexandre
Zotine.

See also
========

  * creating a package
  * packages provided with Macaulay2

changes to Macaulay2, by version
********************************

changes, 1.24.11
****************

  * packages that have been published and certified:
      * a gold star A1BrouwerDegrees, a package
        by Nikita Borisov, Thomas Brazelton, Frenly Espino, Tom Hagedorn,
        Zhaobo Han, Jordy Lopez Garcia, Joel Louwsma, Wern Juin Gabriel Ong,
        and Andrew Tawfeek for A1-Brouwer degree computations, has been
        published.
      * a gold star SpecialFanoFourfolds, a
        package by Giovanni Staglianò for Hodge-special fourfolds, has been
        published.
      * a gold star SubalgebraBases, a package by
        Michael Burr, Oliver Clarke, Timothy Duff, Jackson Leaman, Nathan
        Nichols, and Elise Walker for Canonical subalgebra bases (aka
        SAGBI/Khovanskii bases), has been published.
  * new packages:
      * AbstractSimplicialComplexes, a
        package by Nathan Grieve for abstract simplicial complexes, has been
        added.
      * Msolve, a package by Martin Helmer, Mike Stillman,
        and Anton Leykin for interfacing with the msolve library for solving
        multivariate polynomial systems using Groebner Bases, has been added.
      * MultigradedImplicitization, a
        package by Joseph Cummings and Benjamin Hollering for solving
        implicitization problems using multigradings, has been added.
      * NumericalSemigroups, a package by
        David Eisenbud and Frank-Olaf Schreyer for computing the Apery set and
        invariants of a numerical semigroup ring, has been added.
      * Permutations, a package by Sean Grate for
        functions for working with permutations, has been added.
      * SCMAlgebras, a package by Ernesto Lax for
        sequentially Cohen-Macaulay modules or ideals, has been added.
  * improved packages:
      * A1BrouwerDegrees, has been updated to
        version 1.1 with bug fixes and improved documentation.
      * AssociativeAlgebras, has been updated
        to version 0.9 with new functions related to derivation-quotient
        algebras, superpotentials, and Nakayama automorphisms of m-Koszul
        Artin-Schelter regular algebras.
      * ForeignFunctions, has been updated to
        version 0.4 with improved documentation.
      * Jets, has been updated to version 1.2 with
        improvements and new methods for principal jets.
      * LieTypes, has been updated to version 0.82 with
        bug fixes, improved documentation, and a new method, see zeroModule (LieTypes).
      * PositivityToricBundles, has been
        updated to version 1.9 with bug fixes and a new method, see
        wellformedBundleFiltrations (PositivityToricBundles).
      * Probability, has been updated to version 0.5
        with improved documentation.
      * Seminormalization, has been updated to
        version 0.22 with several improvements.
      * TerraciniLoci, has been updated to version
        0.2 with minor updates.
      * Triangulations, has been updated to version
        0.2 with a bug fix.
      * VectorGraphics, has been updated to version
        1.1 with several improvements.
      * Visualize, has been updated to version 1.6 with
        improvements to the JavaScript code.
  * functionality added or improved:
      * A new function headlines, is now available for viewing
        a table of documentation headlines from a list produced by
        methods, about, or apropos.
      * It is now possible to construct an empty matrix by passing an empty
        list to matrix.
      * LUdecomposition, now supports empty real and
        complex matrices.
      * The version, hash table now contains a "git branch" key.
      * The version number displayed in the startup banner now includes git
        information.
      * copyright, is now a command that displays
        the Copyright and license, documentation.
      * A number of improvements have been made to methods dealing with
        MonomialIdeal, objects.
      * The function remove, which previously had no return
        value, now returns the value that was removed.
      * The function changeDirectory, for changing the
        working directory, has been added.
      * Many numerical functions that previously did not accept CC,
        or RRi, arguments now do.
      * The functions selectKeys, selectValues,
        and selectPairs,
        for selecting from hash tables have been added.
      * It is now possible to edit the list of packages that are loaded when
        Macaulay2 starts up by modifying the list Core#"preloaded packages" in
        init.m2.
      * The classes Constant, InfiniteNumber,
        and IndeterminateNumber, are
        now all subclasses of Number.
      * Hash codes are now unsigned 64-bit integers, vastly reducing the
        probability of running out when creating new types.
      * It is now possible to compare GroebnerBasis,
        objects using ==.
      * Items in the "ways to use" section of documentation pages are now
        formatted using KBD (Text).
      * It is now possible to use try, with then, but
        without else.
      * When running Macaulay2 without the --no-readline option, command
        history is now saved between sessions.  This history can be found in
        the file history.m2 in the applicationDirectory.
      * The error message is now more informative when a key is not found in a
        hash table.
      * New methods for scalar division, e.g., see Matrix / Number,
        have been added.
      * The restriction on promotion/lifting has been relaxed so one can
        promote/lift between any two rings, and apply this to fraction fields
        and tensor products.
  * functionality changed in a way that could break code:
      * The behavior of basis, over tower rings has changed.
        Previously basis was computed over the most recent coefficient ring,
        but now it is computed over the first coefficient ring. Previous
        behavior can be mimicked by passing the option basis(..., Variables =>
        gens R).
      * Testing equality of zero modules using ==, so that two zero
        modules are equal if they are equal as cosets.  The only implication is
        that zero submodules of any free module are now the same, but zero
        submodules of arbitrary modules are only the same if they have the same
        ambient module.
      * The syntactic sugar T OP= f for installing augmented assignment methods,
        has been removed.
      * TEST, is now a keyword instead of a method function.  It
        functionality remains essentially unchanged.  However, its
        FileName, option has been removed.  Use TEST get(...) instead
        when storing the code for a test in a file.

changes, 1.24.05
****************

  * packages that have been published and certified:
      * a gold star CotangentSchubert, a package
        by Paul Zinn-Justin for Cotangent Schubert calculus, has been
        published.
      * a gold star GeometricDecomposability,
        a package by Mike Cummings and Adam Van
        Tuyl to check whether ideals are geometrically vertex decomposable, has
        been published.
      * a gold star InvariantRing, a package by
        Luigi Ferraro, Federico Galetto, Francesca Gandini, Hang Huang, Thomas
        Hawes, Matthew Mastroeni, and Xianglong Ni for invariants of group
        actions, has been published.
      * a gold star MultiplicitySequence, a
        package by Justin Chen, Youngsu Kim, and Jonathan Montaño for computing
        the multiplicity sequence of an ideal, has been published.
      * a gold star Probability, a package by Doug
        Torrance for basic probability functions, has been published.
      * a gold star TropicalToric, a package by
        Alessio Borzì on tropical methods for toric intersection theory, has
        been published.
  * new packages:
      * MultigradedBGG, a package by Maya Banks,
        Michael K. Brown, Tara Gomes, Prashanth Sridhar, Eduardo Torres Davila,
        and Sasha    Zotine for the multigraded BGG correspondence and
        differential modules, has been added.
      * TropicalToric, a package by Alessio Borzì on
        tropical methods for toric intersection theory, has been added.
      * VNumber, a package by Antonino Ficarra and
        Emanuele Sgroi to compute v-number of homogeneous ideals and v-function
        of monomial ideals, has been added.
  * improved packages:
      * Many FourTiTwo, methods now have a
        Precision, option for setting the integer precision used by
        4ti2.
      * GeometricDecomposability, has been
        updated to version 1.4.1 with minor updates.
      * NumericalAlgebraicGeometry, has
        been updated to version 1.24 with small updates.
      * PositivityToricBundles, has been
        updated to version 1.7, adding several new methods, fixing bugs, and
        updating the documentation and tests.
      * ToricVectorBundles, has been updated to
        version 1.2 with updated documentation.
      * WhitneyStratifications, has been
        updated to version 2.03, adding new routines to stratify algebraic maps
        to the package. The update also includes several performance
        improvements and bug fixes.
  * functionality added or improved:
      * It is now possible to create a fraction field of an iterated polynomial
        ring using frac.
      * A number of new operators have been added that may be used for defining
        methods.  See ^!, _!, ^~, _~,
        see ^>, ^>=, ^<, ^<=,
        _>, _>=, _<, _<=,
        |_, and |_=.
      * A number of improvements have been made to parallelization. In
        particular:
          * The function getIOThreadMode, has been added
            for determining the current I/O thread mode.
          * The functions setIOExclusive,
            setIOSynchronized, and
            setIOUnSynchronized, now also accept a file as
            an argument.
          * The default I/O thread mode has been changed from 0
            (unsynchronized) to 1 (synchronized).
          * Much of the code (e.g., reading mutable hash tables) is now thread
            safe.
          * The output of GCstats, has been improved.
          * The initial heap size used by the garbage collector has been
            increased and the free space divisor has been decreased.
          * The taskResult, function now waits
            until a task is finished before returning its result.
          * The parallelApply, function has been added for
            applying a function to a list in parallel.
          * The output when using the time, keyword now includes
            the time used by the current thread and in garbage collection.
          * The keyword threadVariable has been renamed to threadLocal,
            although the former still exists as a synonym.
        See parallel programming with threads and tasks,
        for more.
      * The hash counter for mutable hash tables increases much more slowly,
        decreasing the likelihood of overflowing.
      * The take, function will now accept a two-element list as
        its second element if the class of the first element has a
        iterator, method installed.
      * Broken links to the Journal of Software for Algebra and Geometry (see
        https://msp.org/jsag/ ) have been fixed in the documentation for older
        certified packages.
      * The documentation page for each certified package now includes its DOI.
      * The union (Posets), function has been added for sets.
      * The intersect, and intersection,
        functions now work for sets.
      * Creating integer quotient rings using ZZ/n now works when n is large
        and/or composite.
      * The syntax g \\ f as a synonym for f // g when f and g are matrices has
        been deprecated.  It will be replaced in the next release.
      * Modules may now be compared using <, <=, >,
        and >=, by their ranks and degrees.  In particular,
        lists of modules may now be sorted.
      * The method homomorphism(Vector), was added for
        getting the homomorphism from an element of a Hom module.
      * The method random(Module), was added for
        generating random elements of modules.
      * The method all(BasicList), was
        added for checking if all elements of a list of booleans are true.
      * The method position(ZZ,Function), was added for finding
        the smallest index for which a function returns true.

changes, 1.23
*************

  * packages that have been published and certified:
      * a gold star BettiCharacters, a package by
        Federico Galetto for finite group characters on free resolutions and
        graded modules, has been published.
      * a gold star FastMinors, a package by Boyana
        Martinova, Marcus Robinson, Karl Schwede, and Yuhui (Wei) Yao for
        faster linear algebra operations, has been published.
      * a gold star MixedMultiplicity, a package
        by Kriti Goel, Vivek Mukundan, Sudeshna Roy, and J. K. Verma for Mixed
        Multiplicities of ideals, has been published.
      * a gold star RandomPoints, a package by
        Sankhaneel Bisui, Zhan Jiang, Sarasij Maitra, Thai Nguyen, Frank-Olaf
        Schreyer, and Karl Schwede for find a point in a given variety over a
        finite field, has been published.
      * a gold star SimplicialComplexes, a
        package by Gregory G. Smith, Ben Hersey, and Alexandre Zotine for
        exploring abstract simplicial complexes within commutative algebra, has
        been published.
  * new packages:
      * The package Dmodules, is now an umbrella package
        which, for compatibility with old code, loads WeylAlgebras,
        see HolonomicSystems, and
        BernsteinSato. The new addition
        WeylAlgebras, contains basic constructors and
        methods for working with Weyl algebras which used to be in the
        Dmodules, package.
      * The package Varieties, has been added to
        encapsulate existing and new functionality for working with affine and
        projective varieties and coherent sheaves on them. The package adds
        support for maps of coherent sheaves.
      * A1BrouwerDegrees, a package by Nikita
        Borisov, Thomas Brazelton, Frenly Espino, Tom Hagedorn, Zhaobo Han,
        Jordy Lopez Garcia, Joel Louwsma, Andrew Tawfeek, and Wern Juin Gabriel
        Ong for for working with A1-Brouwer degree computations, has been
        added.
      * AdjunctionForSurfaces, a package by
        Frank-Olaf Schreyer for Adjunction for Surfaces, has been added.
      * MatrixSchubert, a package by Ayah Almousa,
        Sean Grate, Daoji Huang, Patricia Klein, Adam LaClair, Yuyuan Luo, and
        Joseph McDonough for functions for investigating ASM and matrix
        Schubert varieties, has been added.
      * OIGroebnerBases, a package by Michael
        Morrow for OI-modules over Noetherian polynomial OI-algebras, has been
        added.
      * PlaneCurveLinearSeries, a package
        by David Eisenbud for Linear series on the normalization of a plane
        curve, has been added.
      * QuadraticIdealExamplesByRoos,
        a package by David Eisenbud, Michael Perlman, Ritvik Ramkumar, Deepak
        Sireeshan, Aleksandra Sobieska, Teresa Yu, and Jacob Zoromski for
        Examples of Quadratic Ideals with Embedding Dimension Four by Jan-Erik
        Roos, has been added.
      * RInterface, a package by Doug Torrance for
        interface to R for statistical computing, has been added.
      * TerraciniLoci, a package by Francesco
        Galuppi, Pierpaola Santarsiero, Doug Torrance, and Ettore Teixeira
        Turatti for Terracini loci of projective varieties, has been added.
      * Valuations, a package by Michael Burr, Colin
        Alstad, Michael Byrd, Ethan Partida, Shelby Cox, Courtney George, and
        Oliver Clarke for implementation of valuations for rings, has been
        added.
  * functionality added or improved:
      * Most flexible binary operators now have a corresponding augmented assignment,
        operator.  For example, x += 1 is
        equivalent to x = x + 1.
      * A new type, see AtomicInt, has been introduced providing
        atomic operations for use in parallel programs.
      * The null coalescing operator ??, has been added to the
        Macaulay2 language.
      * A polynomial f may now be evaluated at a ring element or sequence of
        ring elements x using f(x).  The existing syntax, f[x], has been
        deprecated and may be removed in a future release. See
        RingElement Sequence.
      * The method isMember(RingElement,Ideal),
        has been added to test membership in
        an ideal.
      * When given just a module and no integer, see hilbertFunction,
        will now a return a function that accepts integers and
        returns the corresponding values of the Hilbert function of the module.
      * Torsion is now taken into account when adding, subtracting, and
        negating matrices.
      * The source and target modules of a matrix will now be printed when both
        are free and/or have been assigned to global variables.  Previously,
        they were only printed when both were free.
      * If a module in a chain complex has been assigned to a global variable,
        then that variable will appear when the complex is printed, unless it
        is a free module.
      * Several improvements have been made to vector, for
        constructing elements of modules.
      * It is now possible to view the code of a function defined on the
        standard input using code.
      * The particular subclass of Function, is now displayed
        when a function that has not been assigned to a global variable is
        printed.
      * The "standalone" class is now used by showTex, so that the
        size of the resulting document will match the size of the object being
        viewed.
      * Several new escape sequences have been added for strings:  \a (for
        audible bell), \e and \E (for escape), \v (for vertical tab), and \x
        (for indicating a character using its ASCII encoding in hexadecimal).
        See ".
      * Both exportFrom, and importFrom,
        now accept either a string or Package, object as their
        first argument and either a string or a list of strings as their second
        argument.
      * FLINT, version 3 is now supported.
      * libatomic_ops has been dropped as a dependency and has been replaced
        with C11 and C++11 standard atomic operations.
      * Some computations in the engine (e.g. minimal betti diagrams and
        Groebner bases over associative algebras), can now take advantage of
        multiple CPU cores, see parallelism in engine computations.
  * emacs updates:
      * Indentation in the Macaulay2 major mode is now more consistent with
        other Emacs majors modes.  For example, it now respects the Electric
        Indent minor mode.  In particular, it is possible to toggle whether
        code is automatically indented after pressing "Return" by running M-x
        electric-indent-mode.
      * The Macaulay2 Interaction major mode now respects the
        comint-use-prompt-regexp variable.  This controls how many lines are
        sent to Macaulay2 when pressing "Return" after scrolling up to previous
        input.  If the variable is set to t, then one line will be sent.  If it
        is set to nil (the default), then the entire input field will be sent.
      * The function M2-send-to-program (which is bound to "F11" by default),
        is now only intended to be called from the Macaulay2 major mode.  A new
        function, M2-send-input-or-get-input-from-demo-buffer has been added
        (and bound to "F11") for the Macaulay2 Interaction major mode.  The
        user experience should remain unchanged.

changes, 1.22
*************

  * packages that have been published and certified:
      * a gold star GraphicalModelsMLE, a
        package by Carlos Amendola, Luis David Garcia Puente, Roser Homs Pons,
        Olga Kuznetsova, Harshit J Motwani, Elina Robeva, and David Swinarski,
        for maximum likelihood estimates for graphical statistical models, has
        been published.
      * a gold star LinearTruncations, a package
        by Lauren Cranton Heller, David Eisenbud, and Navid Nemati for finding
        multigraded truncations that give linear resolutions, has been
        published.
      * a gold star RationalMaps, a package by Karl
        Schwede, Daniel Smolkin, S. Hamid Hassanzadeh, and C. J. Bott, for
        working with rational maps, has been published.
      * a gold star PseudomonomialPrimaryDecomposition,
        a package by Alan A.
        Veliz-Cuba for primary decomposition of square free pseudomonomial
        ideals, has been published.
      * a gold star NoetherianOperators, a
        package by Robert Krone, Justin Chen, Marc Harkonen, Yairon Cid-Ruiz,
        and Anton Leykin, for numerically computing local dual spaces, Hilbert
        functions, and Noetherian operators, has been published.
      * a gold star Jets, a package by Federico Galetto and
        Nicholas Iammarino, for computing jets of various algebraic, geometric
        and combinatorial objects, has been published.
  * new packages:
      * HolonomicSystems, a package by Mahrud
        Sayrafi, Christine Berkesch, Anton Leykin, and Harrison Tsai for
        holonomic systems, has been added.  The code was originally in the
        Dmodules package.
      * BernsteinSato, a package by Anton Leykin and
        Harrison Tsai for Bernstein-Sato, has been added.  The code was
        originally in the Dmodules package.
      * PolyominoIdeals, a package by Carmelo
        Cisto, Francesco Navarra, and Rizwan Jahangir for binomial ideals of
        collections of cells, has been added.
      * MatchingFields, a package by Oliver Clarke
        for matching fields, has been added.
      * CellularResolutions, a package by Jay
        Yang and Aleksandra Sobieska for cellular resolutions of monomial
        ideals, has been added.
      * SagbiGbDetection, a package by Viktoriia
        Borovik, Timothy Duff, and Elima Shehu for verifying whether the given
        generators of an ideal form the Gr"obner basis or whether the given
        generators of a finitely generated subalgebra of a polynomial ring are
        the SAGBI basis, has been added.
  * functionality added:
      * A RingMap, object may now be raised to the 0th power if
        its source, and target, agree.
      * Matrices may now be joined with any type of number (not just integers)
        using |, and ||.
      * The html documentation now syntax highlights Macaulay2 code by default
        using Prism (see https://prismjs.com/ ).
      * Some improvements have been made to findProgram, and
        runProgram.
      * A specific test from a package may now be specified using
        tests(ZZ,Package).
      * The html documentation now uses the HTML5 specification.
  * functionality changed in a way that could break code:
      * The functions member and mutable have been renamed to isMember,
        and isMutable, respectively.  The old names
        still exist as synonyms, but they may be removed in a future release.
      * Raising a matrix to the 0th power will now raise an error if the
        source, and target, do not agree.
      * The value of a class's 1 key (used internally for getting
        multiplicative identities) should now be a function that takes an
        instance of the class and returns the multiplicative identity rather
        than the multiplicative identity itself.
      * The function urlEncode, has been moved from the
        OnlineLookup, package to Core, and its
        behavior has been slightly modified.
  * emacs updates:
      * Several new functions have been added to for sending code to an M2
        process, and the code that is sent is now highlighted briefly as a
        visual indicator.  Refer to the "Macaulay2" dropdown menu in Emacs for
        more.
      * File locations that appear in Macaulay2 Interaction buffers are now
        handled using Compilation mode (see
        https://www.gnu.org/software/emacs/manual/html_node/emacs/Compilation-
        Mode.html ).
      * Macaulay2 is now supported in Org Mode using ob-M2 (see
        https://github.com/d-torrance/ob-M2 ).

changes, 1.21
*************

  * new packages:
      * Triangulations, a package by Mike Stillman
        for triangulations of polyhedra and point sets, has been added.
      * WhitneyStratifications, a package
        by Martin Helmer for computing Whitney stratifications algebraically,
        has been added.
      * JSON, a package by Doug Torrance for JSON encoding
        and decoding, has been added.
      * ForeignFunctions, a package by Doug
        Torrance for providing a foreign function interface, has been added.
      * GeometricDecomposability, a
        package by Mike Cummings and Adam Van Tuyl for determining whether
        ideals are geometrically vertex decomposable, has been added.
      * PseudomonomialPrimaryDecomposition,
        a package by Alan A.
        Veliz-Cuba for primary decomposition of square free pseudomonomial
        ideals, has been added.
  * improved packages:
      * The package BettiCharacters, has been
        updated to version 2.0, which introduces character tables,
        decompositions, and other methods for characters. The GradedCharacter
        type has been removed, and the Character type has been modified to
        accommodate both homological and internal grading in a simplified
        format.
  * functionality added:
      * New methods, see iterator, and next, and a new
        class, see Iterator, have been added to allow iteration
        over any Macaulay2 object.
      * for, loops, as well as the methods scan,
        apply, select, fold,
        accumulate, take, and join, now
        work with any iterable object.
      * truncate(Number), has been added, rounding
        numbers toward zero.
      * quotientRemainder(ZZ,ZZ),
        has been added, for
        obtaining the quotient and remainder simultaneously when performing
        integer division.
      * The bitwise not operator, see ZZ ~, has been added.
      * A new strategy Dynamic, is implemented for
        determinant, minors, and
        exteriorPower.
      * A new global variable blockMatrixForm, which
        affects the display of matrices has been added.
      * Partial support for UTF-8 in strings has been added.
      * changeBase, has been added for changing integer
        bases.
  * functionality changed in a way that could break code:
      * remove, may now be used to remove elements from mutable
        lists.  Its previous (undocumented) behavior was equivalent to
        drop.
      * characters, and width(Net), now
        split strings according to UTF-8 characters rather than bytes.

changes, 1.20
*************

  * new packages:
      * CotangentSchubert, a package by Paul
        Zinn-Justin for cotangent Schubert calculus, has been added.
      * OnlineLookup, a package by Paul Zinn-Justin
        for looking up mathematical information online, has been added.
      * MergeTeX, a package by Paul Zinn-Justin for
        running Macaulay2 code and inserting the results into a LaTeX file, has
        been added.
      * Probability, a package by Doug Torrance for
        basic probability, has been added.
      * Isomorphism, a package by David Eisenbud for
        probabilistic searching for isomorphisms between modules, has been
        added.
      * a gold star SchurVeronese, a package by
        Juliette Bruce, Daniel Erman, Steve Goldstein and Jay Yang for
        examining data for Veronese embeddings of projective space, has been
        added and published.
      * a gold star CodingTheory, a package by Taylor
        Ball, Eduardo Camps, Henry Chimal-Dzul, Delio Jaramillo-Velez, Hiram H.
        Lopez, Nathan Nichols, Matthew Perkins, Ivan Soprunov, German Vera, and
        Gwyn Whieldon for coding theory, has been added and published.
  * packages that have been published and certified:
      * a gold star ThreadedGB, a package by Sonja
        Petrovic and Shahrzad Zelenberg, for computing a Groebner basis using
        the classical Buchberger algorithm with multiple threads, has been
        published.
      * a gold star MultiprojectiveVarieties,
        a package by Giovanni Staglianò for
        multi-projective varieties, has been published.
  * improved packages:
      * The package GraphicalModelsMLE, has been
        improved following many recommendations through its certification
        process. Several computations have been optimized. The names of several
        procedures and options have been modified.
      * The package Complexes, has been improved.  The
        documentation has been enhanced, numerous minor bugs have been fixed,
        and free resolutions have been implemented independent of the current
        ChainComplex, class.
      * The package HyperplaneArrangements,
        has been improved.  It includes several improvements in the basic code,
        increased functionality with the Matroids package, completely rewritten
        documentation, numerous bug fixes, and better consistency with
        Macaulay2 conventions.
      * The package SimplicialComplexes, has
        been improved.  It adds constructors for many classic examples,
        implements a new data type for simplicial maps, incorporates many
        improvements to the methods, improves interoperability with
        Polyhedra, and completely overhauls the documentation.
        Changes that break backwards compatibility include changing the output
        of faces and facets from Matrix to List, changing the output type of
        fVector from HashTable to List, and replacing == with === for
        SimplicialComplexes.
  * functionality added:
      * New functions memoizeValues, and memoizeClear,
        have been added for dealing with the values retained by
        functions created with memoize.
      * A new method uniquePermutations, has been
        added. Equivalent to unique @@ permutations except faster.
      * A number of unicode symbols have been added as synonyms, e.g., ℤ or ⊗.
      * New numeric functions Beta, Digamma,
        inverseErf, regularizedBeta,
        inverseRegularizedBeta,
        regularizedGamma, and inverseRegularizedGamma,
        new numeric constant CatalanConstant.
        See Gamma, now accepts two arguments, for
        the incomplete gamma function.  Numeric functions accept constants as
        arguments.
      * pack, reverse, and tally, now
        support strings.
      * unique, now supports all visible lists.
      * Syntax highlighting of Macaulay2 code in the HTML documentation has
        been added as a build-time option.  Use M2CODE (Text), to
        indicate code to be highlighted.
  * functionality changed in a way that could break code:
      * The update to SimplicialComplexes has several minor breaking changes,
        outlined above.

changes, 1.19.1
***************

  * bugs fixed:
      * repaired two broken links to packages in the changes documentation
      * restored the 'Ways to use' and 'For the programmer' sections of the
        documentation provided by help, for a method function.

changes, 1.19
*************

  * new packages:
      * MonomialIntegerPrograms, a package
        by Lily Silverstein and Jay White for using integer programming for
        fast computations with monomial ideals, has been added.
      * ThinSincereQuivers, a package by Mary
        Barker and Patricio Gallardo for construction of flow polytopes and
        their associated quivers, has been added.
      * Python, a package by Daniel R. Grayson and Doug
        Torrance for an interface to Python, has been added.
      * BettiCharacters, a package by Federico
        Galetto for finite group characters on free resolutions and graded
        modules, has been added.
      * Jets, a package by Federico Galetto and Nicholas
        Iammarino, for computing jets of various algebraic, geometric and
        combinatorial objects, has been added.
      * FunctionFieldDesingularization,
        a package by Douglas A. Leonard
        for desingularization of function fields, has been added.
      * HomotopyLieAlgebra, a package by David
        Eisenbud for homotopy Lie algebra, has been added.
      * TSpreadIdeals, a package by Luca Amata for
        t-spread ideals of a polynomial ring, has been added.
      * ExteriorModules, a package by Luca Amata
        and Marilena Crupi for monomial modules over exterior algebras, has
        been added.
      * GroebnerStrata, a package by Kristine Jones
        and Mike Stillman for working with Groebner families and subschemes of
        Hilbert schemes, has been added.
      * QuaternaryQuartics, a package by
        Kapustka, Kapustka, Ranestad, Schenck, Stillman and Yuan containing
        code and examples for their paper 'Quaternary Quartic Forms and
        Gorenstein Rings', has been added.
      * RealRoots, a package by Jordy Lopez, Kelly
        Maluccio, Frank Sottile, and Thomas Yahl for symbolically exploring,
        counting, and locating real solutions to polynomial systems, has been
        added.
      * K3Surfaces, a package by Michael Hoff and
        Giovanni Staglianò for explicit constructions of K3 surfaces, has been
        added.
  * improved packages:
      * The package Truncations, has been improved to
        support modules over the Cox rings of simplicial normal toric varieties (NormalToricVarieties).
      * The package MonodromySolver, includes
        several new convenience functions for manipulating systems and creating
        seed pairs.
      * The package Complexes, has been improved.  The
        documentation is complete, and all methods involving Yoneda Ext and
        connecting maps have been written.  This package will soon replace the
        chain complex code from the Core.
  * packages that have been published and certified:
      * a gold star DecomposableSparseSystems,
        a package by Taylor Brysiewicz, Jose
        Israel Rodriguez, Frank Sottile, and Thomas Yahl for solving
        decomposable sparse systems, has been published.
      * a gold star SparseResultants, a package
        by Giovanni Staglianò for computations with sparse resultants, has been
        published.
      * a gold star ExteriorModules, a package by
        Luca Amata and Marilena Crupi for monomial modules over exterior
        algebras, has been published.
  * packages that have been renamed:
      * The package FastLinAlg has been renamed to FastMinors.
      * The package RandomRationalPoints has been renamed to
        RandomPoints.
  * functionality added:
      * Integers may now be entered using the binary, octal, and hexadecimal
        numeral systems with the prefixes "0b", "0o", and "0x", respectively.
      * A new binary operator, see ^^, has been added for computing the
        bitwise XOR of two integers.  This replaces the "xor" method.
      * A new keyword, see xor, has been added for finding the logical
        XOR of two boolean objects.
      * The function printerr, for printing warning messages
        and logs to stderr, is now exported.

changes, 1.18
*************

  * packages that have been published and certified:
      * a gold star PhylogeneticTrees, a package
        by Nathaniel Bushek, Ruth Davidson, Elizabeth Gross, Pamela Harris,
        Robert Krone, Colby Long, AJ Stewart, and Robert Walker for invariants
        for group-based phylogenetic models, has been published.
      * a gold star GradedLieAlgebras, a package
        by Clas Löfwall and Samuel Lundqvist for computations in graded Lie
        algebras, has been published.
      * a gold star RelativeCanonicalResolution,
        a package by Christian Bopp and
        Michael Hoff for computation of the relative canonical resolution for
        g-nodal canonical curves with a fixed $g^1_k$, has been published.
      * a gold star FrobeniusThresholds, a
        package by Juliette Bruce, Daniel Hernández, Karl Schwede, Dan Smolkin,
        Pedro Teixeira, and Emily Witt, for calculations of F-thresholds, has
        been published.
  * new packages:
      * AssociativeAlgebras, a package by
        Frank Moore and Mike Stillman for noncommutative algebra, has been
        added.
      * RationalPoints2, a package by Jieao Song
        for finding rational points on a variety, has been added.
      * SuperLinearAlgebra, a package by
        Fereshteh Bahadorykhalily and Fatemeh Tarashi Kashani for computing
        with supermatrices, has been added.
      * SubalgebraBases, a package by Michael
        Burr, Oliver Clarke, Timothy Duff, Jackson Leaman, Nathan Nichols,
        Elise Walker, Mike Stillman, and Harrison Tsai, for computing canonical
        subalgebra bases, has been added.
      * AInfinity, a package by David Eisenbud and Mike
        Stillman for A-infinity structures on free resolutions, has been added.
      * LinearTruncations, a package by Lauren
        Cranton Heller, David Eisenbud, and Navid Nemati for finding
        multigraded truncations that give linear resolutions, has been added.
  * improved packages:
      * The package NumericalSchubertCalculus,
        has been improved: several functions
        and options were added for user convenience. Output formats, verbosity,
        and documentation were greatly improved.
      * The package VirtualResolutions, has been
        improved: a new strategy using a significantly faster algorithm has
        been added for the multigradedRegularity (VirtualResolutions),
        function.
      * The package NoetherianOperators, has
        been improved: the DiffOp (NoetherianOperators), type has
        been reworked, and support for Noetherian operators and differential
        primary decompositions of modules has been added.
      * Several packages (see Chordal, Graphs,
        see Markov, and Posets)
        that generate and display visualizations of mathematical
        objects using external image viewers have been modified so that they no
        longer require package-specific configuration of these viewers.
        Instead, see show, is used, which opens the images using the
        system default viewer (using open on macOS and xdg-open on Linux).
  * functionality added:
      * A new type of real number, see RRi, based on interval arithmetic
        has been added, based on the library mpfi, thanks to Michael Burr, with
        help from Anton Leykin.
      * The function tests, has been added, for getting
        information about a package's tests.
      * A new type of list, see AngleBarList, has been added,
        for use in forming free associative algebras. An instance can be
        created with the notation <|x,y,z|>.
      * The function assert, now accepts an Expression,
        object as its argument. This provides more useful error
        messages for debugging, because they will contain the expression in
        unevaluated form, which might be something like d == 3.
      * In the function orbitRepresentatives (MonomialOrbits),
        in the package
        MonomialOrbits, it is now possible to specify a
        subset of monomials from which the monomials that represent orbits are
        chosen, or from which the monomials that represent orbits are removed.
  * functionality removed
      * The type MatrixDegreeExpression has been removed.
      * The type ModuleMap has been removed.

changes, 1.17
*************

  * functionality added:
      * The function importFrom, has been added, for
        importing individual symbols from another package.
      * The function readPackage, has been added, for
        retrieving the options in the preamble of a package quickly.
      * The function hooks, has been added, for retrieving the
        list of functions installed as hooks for handling computations of a
        specific type.
      * The function baseRing, has been added, for retrieving
        the ring from which a ring was formed.
      * The functions findProgram, and runProgram,
        have been added, to provide a uniform way for packages to
        locate external programs. (The names and locations of such programs may
        vary from system to system.
      * The function formation, has been added, for retrieving
        the way a module was formed, whether as a direct sum, tensor product,
        or Hom-module.
  * functionality improved:
      * The function capture, is now used for generating most
        examples and tests.
      * The function installPackage, accepts two new
        argument: installPackage(...,MakeHTML=>...), and
        installPackage(...,MakePDF=>...). The PDF output
        will be improved in a future release.
      * The new optional argument name Keywords, can now be
        used with packages to specify a list of key words (or phrases), useful
        for searching and organizing the packages by topic, as seen here:
        packages provided with Macaulay2.
      * The functions addHook, and runHooks,
        have been modified to accept a new syntax, allow giving names to hooks,
        and run specific hooks using the option Strategy. The symbol
        Default, has been added for use as the name of hooks. The
        mutable hash table GlobalHookStore, has been added as a
        storage location for some hooks. For more information on using hooks,
        see that documentation node.
      * The functions code, is modified to also show the code for
        hooks listed by the function hooks.
      * $\LaTeX$ typesetting for the web documentation is now rendered using
        $\KaTeX$ (see https://katex.org/ ), a JavaScript math typesetting
        library for browsers. As a result, $\LaTeX$ equations and matrices are
        rendered correctly. One notable change is that mathematical characters
        and equations now must be enclosed in \(...\), \[...\], $...$, or
        $$...$$ in order to be rendered. See html(TEX) (Text),
        for more details and examples
      * The option Boxes, of netList,
        has been made more flexible to allow
        customization of the box; it now accepts as input a pair of lists of
        rows and columns.
      * A brief documentation of various types of objects can be viewed using
        ? Symbol.
      * The document, function now accepts three new options:
        Acknowledgement, Contributors,
        and References. The content of each
        will appear under a subsection of the same name in the documentation.
        Moreover, see document(String) (SimpleDoc), is now a synonym for
        doc(String) (SimpleDoc).
      * The regex, function, as well as other functions that
        accept regular expressions, have been
        rewritten to use the Perl regular expression syntax by default, which
        allows more fine-grained control of the matches. The POSIX,
        extended flavor is still available as an option. The
        functionality is unchanged in almost all cases, except for regular
        expressions containing escaped special characters, where another
        backslash may be needed, and, in rare cases, where there are multiple
        options to match the regular expression. Internally, the new
        implementation incorporates the Boost.Regex, library.
  * new packages:
      * EagonResolution, a package by David
        Eisenbud and Mike Stillman for Eagon resolutions of residue fields, has
        been added.
      * EigenSolver, a package by Laurent Busé, Justin
        Chen, Kisun Lee, Anton Leykin, Tomas Pajdla, and Erika Pirnes for
        solving polynomial systems using eigen-computations, has been added.
      * GKMVarieties, a package by Chris Eur and
        Ritvik Ramkumar for computations with GKM manifolds and moment graphs,
        has been added.
      * GraphicalModelsMLE, a package by Carlos
        Amendola, Luis David Garcia Puente, Roser Homs Pons, Olga Kuznetsova,
        Harshit J Motwani, Elina Robeva, and David Swinarski, for maximum
        likelihood estimates for graphical statistical models, has been added.
      * Hadamard, a package by Iman Bahmani Jafarloo for
        Hadamard products of projective subvarieties, has been added.
      * MonomialOrbits, a package by David Eisenbud
        and Mike Stillman for orbit representatives of monomial ideals, has
        been added.
      * MultiprojectiveVarieties, a
        package by Giovanni Staglianò for multi-projective varieties, has been
        added.
      * MultiplicitySequence, a package by
        Justin Chen, Youngsu Kim, and Jonathan Montaño, for computing the
        multiplicity sequence of an ideal, has been added.
      * NoetherianOperators, a package by
        Robert Krone, Justin Chen, Marc Harkonen, Yairon Cid-Ruiz, and Anton
        Leykin, for numerically computing local dual spaces, Hilbert functions,
        and Noetherian operators, has been added. (The package NumericalHilbert
        has been absorbed into this new package.
      * NumericalLinearAlgebra, a package
        by Robert Krone, Marc Harkonen, and Anton Leykin for numerically
        compute local dual spaces and Hilbert functions, has been added.
      * RandomPoints, previously called
        RandomRationalPoints a package by Sankhaneel Bisui, Thai Nguyen, Karl
        Schwede, Sarasij Maitra, and Zhan Jiang, for computing a random point
        in a given variety over a finite field, has been added.
      * ResLengthThree, a package by Lars Winther
        Christensen, Luigi Ferraro, Francesca Gandini, Frank Moore, and Oana
        Veliche, for multiplication in free resolutions of length three, has
        been added.
      * ResolutionsOfStanleyReisnerRings,
        a package by Ashleigh Adams for
        comparing resolutions of Stanley-Reisner rings and computing various
        systems of parameters, has been added.
      * Saturation, a package by Justin Chen, Mahrud
        Sayrafi, and Mike Stillman for computations involving quotients,
        saturations, and annihilators of modules and ideals, has been added.
        The package is preloaded, so the routines from this package will be
        used automatically. In particular, the new implementation supports
        caching of computations as well as new strategies, which can be listed
        using the hooks, function.
      * StatGraphs, a package by Carlos Amendola, Luis
        David Garcia Puente, Roser Homs Pons, Olga Kuznetsova, and Harshit J
        Motwani, for graphs used in algebraic statistics, has been added.
      * SwitchingFields, a package by Zhan Jiang
        and Sarasij Maitra for switching base fields and obtaining natural
        maps, has been added.
  * packages that have been published and certified:
      * a gold star VirtualResolutions, a
        package by Ayah Almousa, Christine Berkesch, Juliette Bruce, David
        Eisenbud, Michael Loper, and Mahrud Sayrafi for virtual resolutions on
        products of projective spaces, has been published.
  * improved packages:
      * The doc(String) (SimpleDoc), method from the SimpleDoc,
        package has been rewritten to support documenting
        multiple nodes at once. The following keywords were added: Node,
        Synopsis, Tree, Acknowledgement, Contributors, References, and
        SourceCode. Moreover, two new functions, see arXiv (SimpleDoc),
        and stacksProject (SimpleDoc), were added to help
        with referencing external documents.
      * The PrimaryDecomposition, package has
        been improved to support computation of associated primes and primary
        decomposition of modules. In addition, partial computations in this
        package are now cached.
      * The MinimalPrimes, package has been improved
        and the minimalPrimes (MinimalPrimes), and
        isPrime(Ideal) (MinimalPrimes), routines from that
        package are now used by default, deprecating the installMinprimes
        routine. A new routine radicalContainment (MinimalPrimes),
        has been added, and the function
        radical (MinimalPrimes), is moved to this package. In
        addition, partial computations in this package are now cached.
      * Version 2.0 of InvariantRing, introduces
        types for different group actions as well as rings of invariants. It
        also contains new functionality for computing invariants of finite
        groups, diagonal actions (tori/abelian groups), and linearly reductive
        groups. The code from version 1.1.0 has been updated to work with the
        new types.
  * functionality changed:
      * The functions associatedPrimes (PrimaryDecomposition),
        see topComponents (PrimaryDecomposition),
        and removeLowestDimension (PrimaryDecomposition),
        have been moved to the
        package PrimaryDecomposition.
      * The destinations of the links at the tops of the web pages portraying
        documentation nodes in a package have been altered.  The links labeled
        next and previous have been interchanged with the links labelled
        forward and backward.  This was done to bring the terminology into
        agreement with that used in the info nodes portraying documentation
        nodes.  The result can be described as follows.  By virtue of the
        Subnodes, option, each node is provided with a certain number
        of subnodes, so the documentation as a whole may be regarded as an
        ordered union of rooted trees, with the top node of the package serving
        as the root of the first one. (Ideally it would be the only one.)  The
        next and previous links can be used to traverse the (sibling) subnodes
        of a given node, in sequence.  (The various roots are also regarded as
        siblings.)  The forward and backward links can be used to traverse all
        the nodes, in depth-first sequence.  Ideally, the documentation would
        be structured so such a traversal results in a readable document with
        topics presented in a logical sequence.
  * functionality changed in a way that could break code:
      * The variable backupFileRegexp has been replaced by the Exclude,
        option to copyDirectory.
      * The option installPackage(...,InstallPrefix=>...),
        no longer accepts a function as input. only strings
        containing a path to the installation prefix are accepted.
      * The function localRing has been moved to the package LocalRings.
  * functionality removed
      * The function removeHook has been removed.
      * The ForestNode and TreeNode types have been made internal.

changes, 1.16
*************

  * functionality added:
      * The location of Macaulay2's emacs files has changed from site-lisp to
        site-lisp/Macaulay2, so users, after installing this version of
        Macaulay2, may once again need to run setupEmacs, (or
        setup).
  * new packages:
      * SimplicialPosets, a package by Nathan
        Nichols for constructing Stanley simplicial poset rings, has been
        added.
      * SlackIdeals, a package by Amy Wiebe and
        Antonio Macchia for slack ideals of polytopes and matroids, has been
        added.
      * PositivityToricBundles, a package
        by Andreas Hochenegger for checking positivity of toric vector bundles,
        has been added.
      * SparseResultants, a package by Giovanni
        Staglianò for computations with sparse resultants, has been added.
      * DecomposableSparseSystems, a
        package by Taylor Brysiewicz, Jose Israel Rodriguez, Frank Sottile, and
        Thomas Yahl for solving decomposable sparse systems, has been added.
      * MixedMultiplicity, a package by Kriti
        Goel, Sudeshna Roy, and J. K. Verma for mixed multiplicities of ideals,
        has  been added.
      * ThreadedGB, a package by Sonja Petrovic, Sara
        Jamshidi Zelenberg, and Tanner Zielinski for computing a Groebner basis
        using the classical Buchberger algorithm with multiple threads, has
        been added.
      * PencilsOfQuadrics, a package by
        Frank-Olaf Schreyer, David Eisenbud, and Yeongrak Kim for Clifford
        algebras of pencils of quadratic forms, has been added.
      * VectorGraphics, a package by Paul
        Zinn-Justin for producing scalable vector graphics, has been added.
  * packages that have been published and certified:
      * a gold star DeterminantalRepresentations,
        a package by Justin Chen and Papri
        Dey for computing determinantal representations, has been published.
      * a gold star Seminormalization, a package
        by Karl Schwede and Bernard Serbinowski for computing seminormalization
        of rings, has been published.
      * a gold star SumsOfSquares, a package by
        Diego Cifuentes, Thomas Kahle, Pablo A. Parrilo, and Helfried Peyrl for
        sums of squares, has been published.
  * functionality added:
      * The function installPackage, now returns, as its
        value, the package that was installed. This makes it more convenient to
        both install and check a package, because one can type check
        installPackage "FOO".
      * The roots, command is now handled by the
        MPSolve, library, and is more robust, but no longer
        takes an optional argument Unique.
      * The Complexes, package has new data types and
        routines for homological algebra. Eventually, it will replace the
        current facilities for homological algebra. We are making this
        available in order to get feedback from users before making this
        change.  Please email the authors with any and all comments or
        suggestions.
  * functionality improved
      * The PARI library has been removed.  Its functionality has been subsumed
        by the MPSolve, library (for the roots,
        function for finding roots of a univariate
        polynomial), and the FLINT, library, for integer
        factorization and primality testing.
      * The Boost.Stacktrace, library has been added for printing
        stack traces in case of a crash.
      * Primality testing, provided by isPrime, is now handled
        by the FLINT, library.
      * Probable prime testing, provided by isPseudoprime,
        is now handled by the FLINT,
        library.
      * Factorization of integers, provided by factor(ZZ),
        is now handled by the FLINT,
        library.
      * The FLINT, library, and several others, no longer need to
        be patched while building Macaulay2. This involved a reorganization of
        the way memory management is done in the engine and the interpreter. As
        a result, we can use versions of several basic libraries as provided by
        the operating system, including GNU MP,MPIR,see MPFR,
        and the NTL library.
      * The CompleteIntersectionResolutions,
        package now has an implementation
        of the dual of the (infinite) Tate resolution of any module over a
        complete intersection $R$ as a finitely generated module over
        $R[t_1..t_c]$, the ring of Eisenbud operators.  As a byproduct, this
        gives another method for computing the global $Ext_R(M,N)$.  Also
        implemented layered resolutions (in the sense of Eisenbud-Peeva) of
        Cohen-Macaulay modules over $R$.
      * The ReesAlgebra, has new functionality, with
        the defaults changed to make the computation faster.

changes, 1.15
*************

  * new packages:
      * VirtualResolutions, a package by Ayah
        Almousa, Christine Berkesch, Juliette Bruce, David Eisenbud, Michael
        Loper, and Mahrud Sayrafi, for virtual resolutions on products of
        projective spaces, has been added. (Actually, it was added in 1.14, but
        we forgot to say that in changes, 1.14.
      * FastMinors, previously called FastLinAlg, a
        package by Boyana Martinova, Marcus Robinson, Karl Schwede, and Yuhui
        (Wei) Yao, for faster linear algebra operations, has been added.
      * FrobeniusThresholds, a package by
        Juliette Bruce, Daniel Hernández, Karl Schwede, Dan Smolkin, Pedro
        Teixeira, and Emily Witt, for calculations of F-thresholds, has been
        added.
      * The package SOS has been renamed to SumsOfSquares.
      * SpechtModule, a package by Jonathan Niño for
        efficient computation of invariants for permutation groups, has been
        added.
      * SpecialFanoFourfolds, a package by
        Giovanni Staglianò for special cubic fourfolds and special prime Fano
        fourfolds of degree 10 and index 2, has been added.
  * packages that have been published and certified:
      * a gold star NumericalImplicitization,
        a package by Justin Chen and Joe Kileel
        for computing invariants of images of polynomial maps, has been
        published.
      * a gold star RandomMonomialIdeals, a
        package by Sonja Petrovic, Despina Stasi, Dane Wilburne, Tanner
        Zielinski, Daniel Kosmas, Parker Joncus, Richard Osborn, Monica Yun,
        and Genevieve Hummel, for generating Erdos-Renyi-type random monomial
        ideals, has been published.
      * a gold star SymbolicPowers, a package by
        Eloisa Grifo for calculations involving symbolic powers, has been
        published.
      * a gold star TestIdeals, a package by Alberto F.
        Boix, Juliette Bruce, Drew Ellingson, Daniel Hernandez, Zhibek
        Kadyrsizova, Mordechai Katzman, Sara Malec, Matthew Mastroeni, Maral
        Mostafazadehfard, Marcus Robinson, Karl Schwede, Dan Smolkin, Pedro
        Teixeira, and Emily Witt for calculations of singularities in positive
        characteristic, has been published.
      * a gold star SchurComplexes, a new package
        by Michael K. Brown, Amy Huang, Robert Laudone, Michael Perlman,
        Claudiu Raicu, Steven V. Sam, and Joao Pedro Santos, for Schur functors
        of chain complexes, has been added and published.
  * functionality added or improved:
      * The function nanosleep, has been added by Boyana
        Martinova and Karl Schwede.  It allows the Macaulay2 process to sleep
        for short periods.
      * The sagbi engine command rawSubduction has been fixed.  A new engine
        function rawMonoidNumberOfBlocks  has been created, which returns the
        number of blocks of the monomial order of the monoid (each Weight
        function, Lex, or GRevLex group counts as a block)
  * commits, issues, and pull requests on github
      * See closed 1.15 issues (see
        https://github.com/Macaulay2/M2/issues?q=milestone%3A%22version+1.15%22
        +is%3Aclosed ), for the issues and pull requests incorporated into
        1.15.
      * See 1.15 commits (see https://github.com/Macaulay2/M2/commits/release-
        1.15 ) for complete information about all changes to the code
        incorporated into 1.15.

changes, 1.14
*************

  * functionality added or improved:
      * A bug related to determining the correct layout of a source directory
        prevented the function help, from finding the example
        output and merging it into the help message.  This has been fixed.
      * A change to the way expressions interact with the reverse dictionary
        prevented normal toric varieties assigned to global variables from
        being printed out as the name of the variable.
  * new packages:
      * DiffAlg, a package by Manuel Dubinsky, Cesar
        Massri, Ariel Molinuevo, and Federico Quallbrunn, for computations with
        differential forms, has been added.
      * Quasidegrees, a package by Roberto Barrera
        for computing quasidegrees and graded local cohomology, has been added.
      * DeterminantalRepresentations,
        a package by Justin Chen and Papri Dey for computing determinantal
        representations, has been added.
      * FGLM, a package by Dylan Peifer and Mahrud Sayrafi
        for computing Groebner bases via the algorithm of Faugère, Gianni,
        Lazard, and Mora, has been added.
  * packages that have been published and certified:
      * a gold star LieTypes, and ConformalBlocks,
        two packages by Dave Swinarski for computing
        ranks and first Chern classes of conformal block bundles on the moduli
        space of n-pointed curves of genus 0, have been published.
      * a gold star Divisor, a package by Karl Schwede and
        Zhaoning Yang for working with Weil divisors, has been published.
      * a gold star StronglyStableIdeals, a
        package by Davide Alberelli and Paolo Lella for studying strongly
        stable ideals related to Hilbert polynomials, has been published.
      * a gold star DiffAlg, a package by Manuel Dubinsky,
        Cesar Massri, Ariel Molinuevo, and Federico Quallbrunn, for
        computations with differential forms, has been published.
      * a gold star Matroids, a package by Justin Chen
        for computations with matroids, has been published.
      * a gold star Quasidegrees, a package by
        Roberto Barrera for computing quasidegrees and graded local cohomology,
        has been published.
  * improved packages:
      * ReflexivePolytopesDB, now has a
        simplified interface and also does not access the web during
        installation.  However, these changes will likely break previous code.
      * CohomCalg, also has a simplified interface and
        also does not access the web during installation.  However, these
        changes will likely break previous code using this package.
  * new constants and operators:
      * The symbol Jupyter, has been added.
      * The type MultigradedBettiTally, has been
        added.
      * The function multigraded, has been added.
  * commits, issues, and pull requests on github
      * See closed 1.14 issues (see
        https://github.com/Macaulay2/M2/issues?q=milestone%3A%22version+1.14%22
        +is%3Aclosed ), for the issues and pull requests incorporated into
        1.14.
      * See 1.14 commits (see https://github.com/Macaulay2/M2/commits/release-
        1.14 ) for complete information about all changes to the code
        incorporated into 1.14.

changes, 1.13
*************

  * functionality changed in a way that could break code:
      * Various packages have been preloaded for convenience when starting
        Macaulay2, but now they are no longer visible by default inside the
        source code of a package.  Developers of packages should add the names
        of the needed preloaded packages to the value of the
        newPackage(...,PackageImports=>...), or
        newPackage(...,PackageExports=>...), option, to ensure that
        needed definitions are visible.
      * the Schubert2 functions projectiveSpace and projectiveSpace'have been
        renamed abstractProjectiveSpace (Schubert2),
        and
        abstractProjectiveSpace' (Schubert2).  The
        reason is that there were name conflicts with the
        NormalToricVarieties, package. Since PP is
        no longer protected, you may put PP = abstractProjectiveSpace in your
        init file and then use something like X = PP 4, although PP^4 will no
        longer work.
      * The deprecated old-style block comment syntax has been disabled.  Now
        one types -* COMMENT *- instead of {* COMMENT *}.
  * new packages:
      * Truncations, a package by David Eisenbud and
        Mike Stillman for truncating modules, has been added. It implements a
        better notion of truncation of a multigraded module.  Some bugs in the
        old function have been fixed. The function truncate(List,Module) (Truncations),
        has been made functorial, but
        it no longer allows partial degrees to be given.
      * FrobeniusThresholds, a package by Erin
        Bela, Alberto F. Boix, Juliette Bruce, Drew Ellingson, Daniel
        Hernandez, Zhibek Kadyrsizova, Moty Katzman, Sara Malec, Matthew
        Mastroeni, Maral Mostafazadehfard, Marcus Robinson, Karl Schwede, Dan
        Smolkin, Pedro Teixeira and Emily Witt for calculation of Frobenious
        thresholds, has been added.
      * ToricInvariants, a package by Martin
        Helmer for computing Euclidean distance degrees, polar degrees, degree
        and codimension of the dual, and Chern-Mather classes of toric
        varieties, has been added.
      * SegreClasses, a package by Martin Helmer and
        Corey Harris for testing containment of varieties and computing
        algebraic multiplicity of subvarieties and Fulton-MacPherson
        intersection products, has been added.
      * SemidefiniteProgramming, a package
        by Diego Cifuentes, Thomas Kahle, Pablo A. Parrilo, and Helfried Peyrl
        for semidefinite programming, has been added.
      * SumsOfSquares, a package by Diego Cifuentes,
        Thomas Kahle, Pablo A. Parrilo, and Helfried Peyrl for sums of squares,
        has been added.
      * MultiGradedRationalMap, a package
        by Yairon Cid Ruiz for computing the degree and birationality of
        multigraded rational maps, has been added.
  * improved packages:
      * CompleteIntersectionResolutions,
        now has a full implementation of
        the Eisenbud-Shamash resolution, and using MCMApproximations,
        now can compute the layered resolution of any
        Cohen-Macaulay module, not just a high syzygy.
  * new constants and operators:
      * The type Describe, MapExpression,
        MatrixDegreeExpression (missing documentation), see
        SheafExpression (Varieties), and
        VectorExpression, have been added.
      * The top level mode WebApp, has been added.
      * The function htmlWithTex has been added.
      * The function polarize, has been added.

changes, 1.12
*************

  * new packages:
      * Seminormalization, a package by Bernard
        Serbinowski and Karl Schwede for computing seminormalization of rings,
        has been added.
      * CoincidentRootLoci, a package by M. C.
        Brambilla and G. Staglianò for computations with coincident root loci,
        has been added.
      * RelativeCanonicalResolution, a
        package by Christian Bopp and Michael Hoff for computation of the
        relative canonical resolution for g-nodal canonical curves with a fixed
        $g^1_k$, has been added.
      * RandomCurvesOverVerySmallFiniteFields,
        a package by Christian
        Bopp and Frank-Olaf Schreyer for computation of general canonical
        curves of genus $\le 15$ over fields with small characteristic, has
        been added.
      * StronglyStableIdeals, a package by
        Davide Alberelli and Paolo Lella for studying strongly stable ideals
        related to Hilbert polynomials, has been added.
      * SLnEquivariantMatrices, a package
        by Ada Boralevi, Daniele Faenzi and Paolo Lella for computations
        related to the paper "A construction of equivariant bundles on the
        space of symmetric forms", has been added.
      * CorrespondenceScrolls, a package by
        David Eisenbud, Frank-Olaf Schreyer, and Alessio Sammartano, to compute
        and analyze examples of correspondence scrolls, has been added.
      * NCAlgebra, a package by Frank Moore, Andrew
        Conner, and Courtney Gibbons, implementing data types for
        noncommutative algebras, has been added.
      * SpaceCurves, a package by Frank Schreyer, Mike
        Stillman, and Mengyuan Zhang, for generation of space curves, has been
        added.
      * ExteriorIdeals, a package by Marilena Crupi
        and Luca Amata for manipulating monomial ideals over exterior algebras,
        has been added.
  * packages that have been published and certified:
      * a gold star Resultants, a package by Giovanni
        Staglianò for resultants and discriminants for multivariate
        polynomials, has been published.
      * a gold star SpaceCurves, a package by Frank
        Schreyer, Mike Stillman, and Mengyuan Zhang, for generation of space
        curves, has been published.
      * a gold star ReesAlgebra, a package by David
        Eisenbud, Amelia Taylor, and Sorin Popescu for computations with Rees
        algebras, has been published.
      * a gold star Cremona, a package by Giovanni
        Staglianò for computations for rational maps between projective
        varieties, has been published.
      * a gold star ExteriorIdeals, a package by
        Marilena Crupi and Luca Amata for manipulating monomial ideals over
        exterior algebras, has been published.
  * improved packages:
      * The package VersalDeformations, has had
        a bug fixed.  The lifting algorithm would give an error or incorrect
        output if the tangent cone for the obstruction equations wasn't
        generated by the lowest order terms of the obstruction equations. This
        has been remedied by actually calculating the tangent cone, and making
        appropriate adjustments to the algorithm.
      * The package TateOnProducts, has been
        improved.  The package implements the method of Tate resolutions, for
        computing cohomology of sheaves on products of projective spaces, and
        also the pushforward complex of a sheaf under a map from a variety to a
        projective space. Tate resolutions on single projective spaces were
        treated in the package BGG, but the case of a product
        of projective spaces is much more subtle, since no term of the full
        Tate resolution is finitely generated.
  * functionality added or improved:
      * The function about, has been added.  It allows one to
        search the documentation of all the packages that have been installed,
        optionally searching the contents, in addition to the keys. For
        example, the command help about X will display all the documentation
        about X.
      * The class NumberedVerticalList, has been
        added.  It's a new type of vertical list (see VerticalList)
        that is also printed vertically, but with numbered
        entries, for ease of referring to them.
      * The option AbsoluteLinks to installPackage, has
        been removed.  Better logic is now used internally, producing relative
        links only between files installed under the same prefix.
      * The layout of files into directories used by installPackage,
        has been simplified, so it may be a good idea to
        reinstall any packages you have installed.  See Layout.
      * Each directory listed in prefixPath, now has its own
        layout, which is detected at runtime. See Layout.
      * Functionality for fast nonminimal free resolutions, see
        FastNonminimal, has a number of bug fixes and
        improvements: (1) it now works for input modules, not just ideals
        (there was a monomial order mismatch which would often cause it to
        fail), (2) multigraded and inhomogeneous ideals/modules are allowed,
        (3) this function works over the exterior algebra as well (it has
        always done so, but that was not always realized), (4) it is possible
        to have M2 use an already created Groebner basis, instead of
        recomputing one.  Use Strategy=>5 in the resolution,
        command, to tell the command that the provided ideal has generators
        which already form a Groebner basis, not necessarily a reduced Groebner
        basis, or a quotient module, whose presentation matrix forms a Groebner
        basis. If the input is not, then this function can give incorrect
        answers or fail.  See FastNonminimal, for details
        and examples.
      * New types MethodFunctionSingle, and
        MethodFunctionBinary, were introduced to serve as
        classes of method functions with a single argument, such as code,
        and of associative method functions based on methods with two
        arguments, such as gcd, from other compiled functions.
      * We have removed the feature where typing an extra empty line ends
        multiline input in a terminal window or emacs buffer. This will make it
        easier to feed input from a file into the interpreter with F-11 and
        encounter the same behavior, since in files we have permit empty lines.
        This change was requested at our Leipzig workshop, with Q2 at
        https://github.com/Macaulay2/Workshop-2018-Leipzig/wiki/Q&A-Thursday
        (see https://github.com/Macaulay2/Workshop-2018-Leipzig/wiki/Q&amp;A-
        Thursday ) being the question that prompted the discussion.
  * commits, issues, and pull requests on github
      * See closed 1.12 issues (see
        https://github.com/Macaulay2/M2/issues?q=milestone%3A%22version+1.12%22
        +is%3Aclosed ), for the issues and pull requests incorporated into
        1.12.
      * See 1.12 commits (see https://github.com/Macaulay2/M2/commits/release-
        1.12 ) for complete information about all changes to the code
        incorporated into 1.12.

changes, 1.11
*************

  * new packages:
      * AbstractToricVarieties, a package
        by Mike Stillman for linking abstract simplicial (normal) toric
        varieties to Schubert2, has been added.
      * AlgebraicSplines, a package by Gwyn
        Whieldon, Eliana Duarte, Daniel Irving Bernstein, and Daniel Irving
        Bernstein for splines on simplicial complexes, polytopal complexes, and
        graphs, has been added.
      * Chordal, a package by Diego Cifuentes and Pablo
        Parrilo for exploiting chordal structure, has been added.
      * CohomCalg, a package by Mike Stillman for
        providing an interface to CohomCalg software for computing cohomology
        of torus invariant divisors on a toric variety, has been added.
      * Complexes, a package by Gregory G. Smith and
        Mike Stillman for chain complexes, has been added.
      * GroebnerWalk, a package by Dylan Peifer for
        computing Groebner bases via the Groebner walk, has been added.
      * Matroids, a package by Justin Chen for
        computations with matroids, has been added.
      * NonminimalComplexes, a package by
        Frank Schreyer and Mike Stillman for obtaining the non-minimal strands
        of a non-minimal resolution of a homogeneous module, has been added.
      * NumericalImplicitization, a
        package by Justin Chen and Joe Kileel for computing invariants of
        images of polynomial maps, has been added.
      * PruneComplex, a package by Mahrud Sayrafi and
        Mike Stillman for pruning chain complexes over polynomial and local
        rings, has been added.
      * RandomMonomialIdeals, a package by
        Despina Stasi, Dane Wilburne, Tanner Zielinski, Daniel Kosmas, Parker
        Joncus, Richard Osborn, Monica Yun, and Genevieve Hummel for generating
        Erdos-Renyi-type random monomial ideals, has been added.
      * ReflexivePolytopesDB, a package by
        Mike Stillman for simple access to Kreuzer-Skarke database of reflexive
        polytopes of dimensions 3 and 4, has been added.
      * SymbolicPowers, a package by Eloisa Grifo
        for calculations involving symbolic powers, has been added.
      * TestIdeals, a package by Alberto F. Boix,
        Juliette Bruce, Drew Ellingson, Daniel Hernandez, Zhibek Kadyrsizova,
        Mordechai Katzman, Sara Malec, Matthew Mastroeni, Maral
        Mostafazadehfard, Marcus Robinson, Karl Schwede, Dan Smolkin, Pedro
        Teixeira, and Emily Witt for calculations of singularities in positive
        characteristic, has been added.
      * Topcom, a package by Mike Stillman that provides an
        interface to a small part of topcom, has been added.
      * TriangularSets, a package by Diego
        Cifuentes for triangular decomposition of ideals, has been added.
      * Tropical, a package by Kathlen Kohn, Sara
        Lamboglia, Diane Maclagan, Benjamin Smith, Jeff Sommars, Paolo Tripoli,
        Magdalena Zajaczkowska, and Magdalena Zajaczkowska for computations in
        tropical geometry, has been added.
  * improved packages:
      * The package CompleteIntersectionResolutions,
        includes now the analysis of
        resolutions over complete intersections, and computations of the
        special resolutions of modules over complete intersections that were
        described by Eisenbud and Peeva in various papers.
      * The package ReesAlgebra, has been improved:
        Corrected and completed the documentation and cleaned up code; added
        functionality having to do with options for computing saturation (used
        in the basic routines); added functionality of the 'Jacobian dual'
        method. Submitted JSAG article explaining the package.
      * The package K3Carpets, includes now facilities
        for computing with K3carpets and their generalization, the
        correspondence scrolls, and using the Schreyer resolution and Schreyer
        naming of syzygies to determine in which characteristics they have
        behavior other than that corresponding to Green's conjecture. The
        computations are used in a forthcoming preprint by Eisenbud and
        Schreyer.
      * LocalRings, has been rewritten by Mahrud Sayrafi
        and Mike Stillman. Functions from the old version are still available.
        The new package extends various primary functions to work over local
        rings with respect to prime ideals. These functions include syz, res,
        trim, mingens, minimalPresentation, symbol //, inducedMap, symbol :,
        saturate, annihilate. The function hilbertSamuelFunction for modules
        over local rings, optionally given a parameter ideal, has been added.
      * Cremona, has been updated from version 3.9.1 to
        version 4.2. The class 'RationalMap' has been improved; in particular,
        this affects the way how the objects of the class are displayed.
        Support has been added for rational maps whose source is a subvariety
        of a product of projective spaces. For instance 'graph(RationalMap)'
        returns a pair of such maps.
        'composeRationalMap(rationalMap,RationalMap)' has been replaced by
        'rationalMap * RationalMap' 'invertBirMap' has been replaced by
        'inverseMap' 'kernelComponent(RingMap,ZZ)' has been replaced by
        'kernel(RingMap,ZZ)'
      * Resultants, has been updated from version 1.0 to
        1.2. 'CayleyTrick' has been changed and replaced by 'cayleyTrick'
        'ChowEquations' has been replaced by 'chowEquations' 'ChowForm' has
        been replaced by 'chowForm' 'Discriminant' has been replaced by
        'discriminant' 'Dual' has been replaced by 'dualVariety' 'Resultant'
        has been replaced by 'resultant' 'Xresultant(Ideal)' has been removed:
        use 'fromPluckerToStiefel dualize ChowForm I' instead The methods
        'affineDiscriminant', 'affineResultant', 'hurwitzForm',
        'macaulayFormula' has bees added.
      * The package TorAlgebra, replaces the package
        CodepthThree. In addition to the functionality of CodepthThree, the new
        package now also implements the classification scheme (due to Kustin
        and Miller) for Gorenstein rings of codepth 4. Moreover, the package
        recognizes complete intersection, Gorenstein, and Golod rings of any
        codepth via the functions isCI, isGorenstein, and isGolod.
      * The package Divisor, has numerous changes to core
        methods to make them compatible with Macaulay2 standards and
        conventions (including renaming many methods). Documentation is also
        improved throughout.  Additional functionality has also been added (for
        example, checking if a divisor is very ample).
  * functionality added or improved:
      * The function localRing (LocalRings), for localizing a
        polynomial ring at a prime ideal, has been added.
      * The function length(Module), now can compute
        length of Artinian modules over local rings.
      * The function newPackage, now takes two new options:
        OptionalComponentsPresent tells whether all optional external
        components of the package are present on the system, and
        UseCachedExampleOutput tells whether to use the cached example output
        files.  This will be useful for packages that use external programs
        that are not always present, so they can seize the opportunity to rerun
        examples when the external programs are present and give no error when
        the external programs are absent.
  * functionality changed:
      * The format for multi-line (un-nested) block comments has been changed
        from {* ... *} to -* ... *- so emacs can colorize the comments
        correctly.  The (deprecated) old style will be recognized by M2 for a
        while.

changes, 1.10
*************

  * new packages:
      * SpectralSequences, a package by Adam
        Boocher, Nathan Grieve, Eloisa Grifo, Gregory G. Smith, and Thanh Vu
        for spectral sequences, has been added.
      * SectionRing, a package by Andrew Bydlon for
        computing the section ring of a Weil Divisor., has been added.
      * K3Carpets, a package by David Eisenbud,
        Frank-Olaf Schreyer for K3 double structure on scrolls, has been added.
      * ChainComplexOperations, a package
        by David Eisenbud for sym2, wedge2, chi2 of a ChainComplex, has been
        added.
      * NumericalCertification, a package
        by Kisun Lee for testing NumericalAlgebraicGeometry, has been added.
      * PhylogeneticTrees, a package by
        Nathaniel Bushek, Ruth Davidson, Elizabeth Gross, Pamela Harris, Robert
        Krone, Colby Long, AJ Stewart, Robert Walker, and Robert Walker for
        invariants for group-based phylogenetic models, has been added.
      * MonodromySolver, a package by Cvetelina
        Hill, Anders Nedergaard Jensen, Kisun Lee, Anton Leykin, and Jeff
        Sommars for solving polynomial systems via monodromy, has been added.
      * ReactionNetworks, a package by Timothy
        Duff, Kisun Lee, and Anton Leykin for reaction networks, has been
        added.
      * PackageCitations, a package by Aaron Dall
        for citation of Macaulay2 packages, has been added.
      * NumericSolutions, a package by Corrado
        Possieri, and Antonio Tornambe for solving systems of polynomial
        equalities, has been added.
      * GradedLieAlgebras, a package by Clas
        Löfwall and Samuel Lundqvist for computations in graded Lie algebras,
        has been added.
      * InverseSystems, a package by David Eisenbud
        for equivariant Macaulay inverse systems, has been added.
      * Pullback, a package by Drew Ellingson and Karl
        Schwede for pullback of rings, has been added.
      * EngineTests, a package by Michael E. Stillman
        and Jakob Kroeker for a test suite for the Macaulay2 engine, has been
        added.
      * SVDComplexes, a package by Frank Schreyer and
        Mike Stillman for SVD of a complex, including nonminimal resolutions
        over the reals, has been added.
      * RandomComplexes, a package by Frank
        Schreyer and Mike Stillman for random complexes over fields or the
        integers, has been added.
  * improved packages:
      * Polyhedra, has been rewritten by Lars Kastner for
        improved performance.  Many bugs have been fixed, and there are now a
        large number of tests. Some changes are not backward compatible.  Some
        changes include:
          * Fan (Polyhedra), is no longer a collection of Cone
            objects, but contains a matrix of rays (over ZZ), and a list of
            lists of integer indices, indicating the maximal cones.
            Well-defined-ness is no longer automatically checked.  Use
            isWellDefined(Fan) (Polyhedra),
          * Polyhedron (Polyhedra), is now a wrapper for the
            homogenized cone.
          * PolyhedralComplex (Polyhedra), is now a
            wrapper for the homogenized fan.
          * Cone (Polyhedra), has basically the same functionality,
            except that not everything is computed ahead of time.
          * faces (Polyhedra), now returns a list of lists of
            integer indices.  There are two new functions for recovering the
            old behavior: facesAsCones (Polyhedra), (for
            fans and cones), and  facesAsPolyhedra (Polyhedra),
            for polyhedra and polyhedral
            complexes.
        An important difference is that objects of these classes can no longer
        be used as keys into hash tables, since these objects are implemented
        as mutable hash tables. In particular ===, no
        longer works on cones.  Instead, use a sorted list of e.g. vertices and
        lineality space.

        If you need the old behavior, load the package OldPolyhedra.
        However, if possible, change your code to run with
        the new package.
  * functionality added or improved:
      * The functions toDual (InverseSystems), and fromDual (InverseSystems),
        have been improved and moved to the new
        package InverseSystems,: they are now
        compatible with linear changes of coordinates.
  * new constants and operators:
      * The function QRDecomposition, has been added.
      * The function isFinitePrimeField, has been
        added.
      * The function isWeylAlgebra, has been added.

changes, 1.9.2
**************

  * new packages:
      * RationalMaps, a package by Karl Schwede,
        Daniel Smolkin, S. Hamid Hassanzadeh, and C. J. Bott, for working with
        rational maps, has been added.
  * functionality added or improved:
      * The generation of the documentation in HTML format has been improved,
        and validity is now verified overnight automatically.

changes, 1.9.1
**************

  * new packages:
      * ResidualIntersections, a package by
        Katie Ansaldi, David Eisenbud, Robert Krone, and Jay Yang, for studying
        conditions associated to residual intersection theory, has been added.
      * Visualize, a package by Brett Barwick, Thomas
        Enkosky, Branden Stone, and Jim Vallandingham, to help visualize
        algebraic objects in the browser using javascript, has been added.
      * EquivariantGB, a package by Chris Hillar,
        Robert Krone, and Anton Leykin for equivariant Groebner bases and
        related algorithms, has been added.
      * ExampleSystems, a package by Anton Leykin
        for examples of polynomial systems in numerical algebraic geometry, has
        been added.
  * functionality added or improved:
      * The new function minimalBetti, finds minimal Betti
        numbers of an ideal or module using the new FastNonminimal,
        functionality, avoiding unneeded computation of
        matrices in the free resolution.
      * The new function roots, provided by
        Guillem Blanco, finds roots of univariate polynomials numerically.
      * the new function splitWWW, takes an http response, e.g.
        from getWWW, and unpacks it into the header, and the
        body.  Additionally, if the response indicates that this is a chunked
        response, then the body is unchunked (should be considered a bug fix
        from previous functionality).
  * functionality changed:
      * Some linear algebra functions, including LUdecomposition,
        see solve, nullSpace, and
        columnRankProfile,  when presented with
        matrices over ZZ, would previously give occasional
        nonsensical answers.  These functions have been disabled for matrices
        over ZZ.  However, see solve, uses Groebner basis
        methods to solve a linear system, so did not suffer this problem.
        Caveat: using these functions with a ring that is not a field, even if
        it runs, might give a nonsensical answer. This will be cleaned up in a
        later version.

changes, 1.9
************

  * major improvements and additions:
      * Fast minimal betti number and non-minimal resolution code, for
        homogeneous ideals and modules over polynomial rings over finite prime
        fields.  Also is functional for ideals and modules over exterior
        algebras.  See FastNonminimal, and
        betti(...,Minimize=>...).
        For computing minimal betti numbers, on larger examples, this code is
        often hundreds to thousands of times faster than standard use of
        resolution, and is also, in many cases, much faster than
        the similar code in Singular version 4.0.2 described in Erocal, Motsak,
        Schreyer, Steenpass, Refined Algorithms to compute syzygies, arxiv
        1502.01654.  A paper describing our algorithm and implementation is
        forthcoming.
  * packages that have been published and certified:
      * a gold star HighestWeights, a package by
        Federico Galetto for decomposing free resolutions and graded modules
        with a semisimple Lie group action, has been published.
      * a gold star Posets, a package by David Cook II,
        Sonja Mapes, and Gwyn Whieldon, for processing partially ordered sets,
        has been published.
      * a gold star MultiplierIdeals, a package
        by Zach Teitler for computing multiplier ideals of monomial ideals, has
        been published.
      * a gold star CharacteristicClasses, a
        package by Christine Jost and Martin Helmer for computing
        characteristic classes on toric varieties, has been published.
  * new packages:
      * MCMApproximations, a package by David
        Eisenbud for maximal Cohen-Macaulay approximations and complete
        intersections, has been added.
      * MultiplierIdealsDim2, a package by
        Ferran Dachs-Cadefau for computing multiplier ideals in 2-dimensional
        rings, has been added.
      * RunExternalM2, a package by Brian Pike for
        running Macaulay2 functions outside the current Macaulay2 process, has
        been added.
      * SLPexpressions, a package by Anton Leykin
        for straight line programs and algebraic circuits, has been added.
      * NumericalSchubertCalculus, a
        package by Anton Leykin, Abraham Martin del Campo, and Jan Verschelde,
        for numerical methods in Schubert Calculus, has been added.
      * ToricTopology, a package by Alvise Trevisan
        and Alexander I. Suciu for toric topology, has been added.
      * Cremona, a package by Giovanni Staglianò for
        rational maps between projective varieties, has been added.
      * Resultants, a package by Giovanni Staglianò for
        resultants and discriminants for multivariate polynomials, has been
        added (originally called MultipolynomialResultants).
      * VectorFields, a package by Brian Pike for
        vector fields, has been added.
      * RandomIdeals, a package by David Eisenbud for
        creating random ideals of various sorts, has been added.
      * Miura, a package by Joe Suzuki for divisor class
        groups on curves, has been added.
  * functionality added or improved:
      * The new function installedPackages, returns a
        list of names of packages installed by the user with
        installPackage.
      * The new function uninstallAllPackages,
        uninstalls all the packages installed by the user with
        installPackage.
  * useful functions involving prime numbers, submitted by Frank Schreyer:
      * nextPrime, a simple function to find the first prime
        number at least as large as a given number
      * getPrimeWithRootOfUnity, used to find a
        prime number p s.t. ZZ/p contains a n-th root of unity
      * randomKRationalPoint, a function to find a
        random rational point on a variety over a finite field

changes, 1.8.2
**************

  * functionality added or improved:
      * A problem with making finite fields using GF, was fixed.  It
        involved the third-party FLINT number theory library not being able to
        find its file containing a list of Conway polynomials.

changes, 1.8.1
**************

  * functionality added or improved:
      * The function remainder, was recently made more general
        (so the modules involved are not necessarily free), but as a result,
        some Gröbner bases were no longer cached, necessitating frequent
        recomputation in certain examples, slowing them down substantially. We
        fixed that for remainder, and also for quotient,
        and gb.

changes, 1.8
************

  * new packages:
      * BinomialEdgeIdeals, a package by Tobias
        Windisch for computations with binomial edge ideals, has been added.
      * TateOnProducts, a package by Daniel Erman,
        David Eisenbud, and Frank-Olaf Schreyer for Tate resolutions on
        products of projective spaces, has been added.
      * LatticePolytopes, a package by Anders
        Lundman and Gustav Sædén Ståhl for computations with lattice polytopes,
        has been added.
      * FiniteFittingIdeals, a package by
        Gustav Sædén Ståhl for computing Fitting ideals of finite modules, has
        been added.
      * HigherCIOperators, a package by David
        Eisenbud for computing higher complete intersection operators, has been
        added. It implements some work of Burke, Eisenbud and Schreyer on a
        structure that exists on resolutions over a complete intersection. This
        structure allows one to lift a resolution over a complete intersection
        to a resolution over the ambient ring -— a construction dual, in a
        sense, to the well known Eisenbud-Shamash construction, which is also
        implemented.
      * LieTypes, a package by Dave Swinarski for
        defining types used by the package ConformalBlocks,
        has been added.
      * ConformalBlocks, a package by Dave
        Swinarski for computing ranks and first Chern classes of conformal
        block bundles on the moduli space of n-pointed curves of genus 0, has
        been added.
      * M0nbar, a package by Han-Bom Moon and David
        Swinarski for calculations for divisors and F-curves on the moduli
        space of stable n-pointed genus zero curves, has been added.
      * AnalyzeSheafOnP1, a package by David
        Eisenbud for decomposing a coherent sheaf on the projective line into a
        direct sum of line bundles and cyclic skyscraper sheaves, has been
        added.
  * improved packages:
      * The package Binomials, has been upgraded from
        version 1.0 to 1.2.
      * The package BoijSoederberg, has been
        upgraded from version 1.2 to 1.5.
      * The package ChainComplexExtras, has been
        upgraded from version 0.5 to version 1.
      * The package MultiplierIdeals, has been
        upgraded from version 1.0 to version 1.1.
      * The package CompleteIntersectionResolutions,
        has been upgraded from version
        0.8 to version 0.9. It implements a number of old and new ideas about
        minimal resolutions over a complete intersection developed by
        Eisenbud-Peeva, Avramov-Jorgensen, Eisenbud-Peeva-Schreyer, and
        Burke-Eisenbud-Schreyer. Let S = k[x_1..x_n] be a polynomial ring, ff a
        codimension c regular sequence of homogeneous forms of the same degree,
        and R = S/(ff). It contains:
          * routines to compute the structure of higher matrix factorization on
            a high R-syzygy M — one for which the modules Ext_R^even(M,k) and
            Ext_R^odd(M,k) have negative regularity over the ring of CI
            operators. There are also routines to extract various information
            from the higher matrix factorization.
          * routines that implement the reconstruction algorithm of Avramov and
            Jorgensen that constructs modules M having (certain kinds of)
            specified Ext-modules.
          * routines to test of a conjecture of Eisenbud about the vanishing of
            certain local cohomology of Ext-modules, implementing the map from
            a module to its saturation.
          * routines to compute the higher homotopies for ff on an S-free
            resolution of an S-module M annihilated by ff, and understanding
            the structure of module over an exterior algebra, determined by the
            ff-homotopies on a resolution of M, on Tor^S(M,N) and Ext_S(M,N),
            when M and N are S-modules annihilated by ff. These routines led to
            conjectures that were later proven, and will appear in a
            work-in-progress of Eisenbud, Peeva and Schreyer.
          * routines to compute Hom in the stable category of Cohen-Macaulay
            R-modules, and test for stable triviality. This is used in
            understanding possible obstructions to commutativity of
            CI-operators.
  * functionality added or improved:
      * The function pairs, will now accept (basic) list (or
        sequence) x and return the list of pairs (i,x#i), thanks to Zach
        Teitler.
      * The function minimalPresentation, has been
        modified so that it applies its degree-preserving method also for
        homogeneous modules over affine algebras over affine algebras.
      * The function applyKeys, will now accept an additional
        function to be called when collisions occur between new keys, for
        combining the corresponding values, thanks to Paul Zinn-Justin.
      * The function partition, now takes a third argument: a
        list of additional values in the range of the function, allowing
        members of the resulting partition to be empty.
      * The function loadPackage, can now be used to reload
        a package by giving the package itself as the argument.  This is easier
        than setting the loadPackage(...,Reload=>...),
        option.
      * The function adjoint, has been improved to work not just
        for free modules, and the function adjoint1 has been replaced by
        adjoint'.  This pair of function now implements both
        direction in the adjointness between Hom and tensor product.
      * The new function homomorphism', complements
        homomorphism.  From a map between modules it produces
        the element of Hom.
      * The new function compose, expresses composition of maps
        between modules as a bilinear map between Hom-modules.
      * Bracket powers of ideals (see Ideal ^ Array) have
        been added, thanks to Frank Moore.
      * Several bugs related to computing Groebner bases in polynomial rings
        over ZZ have been fixed.  trim I in this case now returns an ideal or
        module with a Groebner basis as generating set, as a minimal generating
        set isn't well-defined.  In a future release, we hope to provide a
        function to determine a smaller set of generators.  mingens I also
        returns the Groebner basis matrix.  In a future release this function
        might be changed to give an error in cases where there is not a
        well-defined notion of minimal generators.
  * functionality changed:
      * The function export, now accepts strings and options
        only, not symbols.

changes, 1.7
************

  * packages that have been published and certified:
      * a gold star QuillenSuslin, a package by
        Brett Barwick and Branden Stone for computing a basis of a projective
        module over a polynomial ring, has been published.
      * a gold star GraphicalModels, a package by
        Luis Garcia-Puente, Sonja Petrovic, Mike Stillman, and Seth Sullivant,
        for discrete and Gaussian graphical models, has been published.
      * a gold star InvariantRing, a package by
        Thomas Hawes for constructing the invariant ring of a finite group, has
        been published.
      * a gold star MonomialAlgebras, a package
        by David Eisenbud, Janko Boehm, and Max Nitsche for decomposing a
        monomial algebra as a module over a subalgebra, has been published.
      * a gold star TorAlgebra, a package by Lars
        Winther Christensen and Oana Veliche for classification of codepth 3
        local rings based on multiplication in homology, has been published,
        under its old name, CodepthThree.
  * new packages:
      * Book3264Examples, a package by Charley
        Crissman containing Schubert2 code for some of the examples and
        exercises in the book '3264 and all that', by Eisenbud and Harris, has
        been added.
      * EnumerationCurves, a package by Hiep
        Dang for enumeration of rational curves via torus actions, has been
        added.
      * Divisor, a package by Karl Schwede and Zhaoning
        Yang for working with Weil divisors, has been added.
      * EllipticCurves, a package by Alessandro
        Oneto and Stefano Marseglia for addition on elliptic curves and point
        counting, has been added.
      * HighestWeights, a package by Federico
        Galetto for decomposing free resolutions and graded modules with a
        semisimple Lie group action, has been added.
      * NumericalHilbert (absorbed by NoetherianOperators),
        a package by Robert Krone for numerically
        computing local dual spaces and Hilbert functions, has been added.
      * MinimalPrimes, an experimental package by
        Frank Moore, Mike Stillman and Franziska Hinkelmann for finding the
        minimal primes of an ideal, has been added.
      * Bertini, a package by Elizabeth Gross, Jose Israel
        Rodriguez, Dan Bates and Anton Leykin for providing an interface to
        Bertini, has been added.
      * TorAlgebra, a package by Lars Winther
        Christensen and Oana Veliche for classification of codepth 3 local
        rings based on multiplication in homology, has been added, under its
        old name, CodepthThree.
      * Permanents, a package by Tair Akhmejanov for
        computing the permanents of a matrix, has been added.
  * improved packages:
      * SchurRings, has been updated, with support for
        several groups of variables,  documentation, working plethysm, and
        more. The old version is being kept as SchurRingsOld as there are
        incompatible changes.  Specifically, symmRing is now called
        symmetricRing, and has more variables (three sets, h, e, p) than the
        old version.  Please use the new version, and if there is a problem
        that requires you to use the old version, please email Mike Stillman.
      * The packages Polyhedra, and
        ToricVectorBundles, now implement a canonical
        ordering for the rays in a fan.  Formerly the rays came out in an
        unpredictable (but deterministic) order.  Various tests in the latter
        package have been updated to take into account the new ordering.  Users
        may find that their code will have to be modified slightly, by
        permuting lists of parameters (such as weights) corresponding to the
        rays.
  * functionality added or improved:
      * A new option,  see ExampleFiles, has been added to the
        documentation function document, which allows the
        package developer to specify that copies of certain auxiliary files
        should be visible in the current directory while example code is
        running.
      * It is now possible to reduce each entry of a matrix f modulo an ideal I
        by writing f % I.  See Matrix % Ideal.
      * A task now has a serial number, see serialNumber.
      * A new command line option, --no-randomize, prevents the random number
        seed from being set to a value that depends on the time of day and
        process ID.
      * A new command line option, --no-time, arranges for the function
        currentTime, to return 0 always, for reproducility of
        results, as an aid in debugging.
      * A new function, see submatrixByDegrees, allows
        the user to select a submatrix of a matrix by specifying intervals of
        acceptable column degrees or row degrees.
      * New functions elapsedTime, and elapsedTiming,
        analogous to time, and timing,
        measure elapsed time instead of CPU time.
      * A new command antipode, has been added.  This function
        implements the anti-isomorphism between left and right modules in skew
        commuting poly rings. It is used when transposing a matrix over a ring
        with skew commuting variables, basically, so that the transpose of a
        complex of matrices will still be a complex of matrices.
      * Hash codes of matrices have been improved - they are now computed using
        the first two nonzero entries in each column, whereas before the
        entries were not examined, and thus they do a better job of
        distinguishing matrices that are different.  A side effect is that hash
        tables whose keys involve matrices will be stored, printed, and
        converted to lists in a different order, which may affect some code.
      * The default arithmetic for computing in finite fields ZZ/p nows uses
        the FLINT library (see ...). The modulus p can now be p <=
        9223372036854775783, i.e. the largest prime less than 2^63. HOWEVER:
        factorization of polynomials over such rings can only be done for
        primes p < 2^31. TODO: CHECK THIS VALUE
      * Incorporated fast linear algebra for dense (mutable) matrices over
        finite prime fields, using ffpack and flint
      * Linear algebra for mutable matrices over arbitrary precision RR and CC
        approximate fields has been included. Functions which handle extended
        precision include determinant, rank, inverse, LUdecomposition, and
        solve. Functions SVD, eigenvalues, eigenvectors have not yet been
        extended
      * Extensive changes to numerical algebraic geometry code in the engine
      * The groebnerBasis, function includes new
        experimental Groebner code, which is much faster in some cases.
      * The {   t Macaulay2/e} engine directory now compiles cleanly, with a
        few warning messages left.
      * The overall structure of base rings in Macaulay2 has been revamped, to
        allow faster code.  The downside is that because of the high use of
        templates, compile times have generally increased.
      * Random number generation for finite fields has changed, so programs
        expecting a specific set of random numbers will change.
      * If kk is a finite field, e.g., ZZ/5[c]/(c^2+c+1) it was possible (and
        still is) to write map(ZZ[a], kk).  It was never clear what this should
        return, as it is not a well-defined ring map.  However, it now has
        different, still undefined, behavior.
  * functionality changed:
      * If debuggingMode, is false when a package is
        loaded, it will remain false during the loading of the package, even if
        the DebuggingMode, option of loadPackage,
        or newPackage, is set to true.  This
        will help the user avoid entering the debugger while already in the
        debugger.
      * The random number seed is now initialized to 0 with
        setRandomSeed, when running examples (with
        installPackage) and when running tests (with
        check), to ensure predictability and uniformity of results.

changes, 1.6
************

  * packages that have been published and certified:
      * a gold star VersalDeformations, a
        package for calculating tangent and obstruction spaces as well as power
        series solutions for deformation problems involving isolated
        singularities and projective schemes, has been published.
      * a gold star KustinMiller, a package for
        unprojection and the Kustin-Miller complex, has been published.
  * new packages:
      * PushForward, a package for computing the
        push-forward functor for finite ring maps, has been added.  (It should
        have been added to the previous distribution.)
      * EliminationMatrices, a package for
        computing resultants, has been added.
      * EllipticIntegrals, a package for
        numerical computation of elliptic integrals and elliptic functions, has
        been added.
      * Triplets, a package for computing Betti diagrams
        and hypercohomology tables associated to triplets of degree sequences,
        has been added.
      * CompleteIntersectionResolutions,
        a package for analyzing the
        asymptotic structure of minimal resolutions over a complete
        intersection, has been added.
  * improved packages:
      * The package GraphicalModels, has been
        extended significantly by its authors. The previous version of this
        package was simply a basic extension of the package Markov.
        Among the new algorithms implemented are procedures for
        computing the vanishing ideal of a graphical model and for checking for
        identifiable parameters in Gaussian mixed graph models. These
        procedures can be used to study fundamental problems about graphical
        models.
      * The package Schubert2, now handles intersection
        rings of isotropic flag bundles, with an algorithm based on a theorem
        in a paper of Grayson, Seceleanu, and Stillman.
  * functionality added or improved:
      * Factoring of polynomials over non-prime Galois fields has been added,
        using the Singular-Factory, library.
      * The methods for Hom(Matrix,Module), and
        Hom(Module,Matrix), now handle non-free
        modules. There is also a new method for Hom(Matrix,Matrix).
  * functionality changed:
      * changed the order of loading packages inside a package, as specified by
        newPackage(...,PackageImports=>...), and
        newPackage(...,PackageExports=>...), options, so that the
        order of loading is easy to specify (to avoid problems with shadowed
        variables).  The packages are loaded with needsPackage,
        and now the imported packages are loaded before the
        exported packages.  So, if there is a problem, just replicate all the
        exported packages in the list of imports, and juggle the order of the
        list of imports.
      * The function temporaryFileName, now obeys the
        TMPDIR environment variable, the way other unix applications do, rather
        than putting temporary files into the directory /tmp.
  * new constants and operators:
      * New functions fileReadable, fileWritable,
        see fileExecutable, provide
        information about file permissions.
      * The class Task, replaces Thread, and the function
        isCanceled, tells whether a task has been
        canceled.

changes, 1.5
************

  * major improvements and additions:
      * A facility for scheduling tasks to be performed in parallel (in
        threads) has been developed. See parallel programming with threads and tasks.
  * packages that have been published and certified:
      * a gold star Nauty, a package for an interface to the
        program nauty, which provides efficient methods for determining whether
        graphs are isomorphic, generating all graphs with particular
        properties, generating random graphs, and more, has been published.
      * a gold star NumericalAlgebraicGeometry,
        a package for using polynomial
        homotopy continuation to solve systems of polynomial equations and
        describing positive-dimensional complex algebraic varieties, has been
        published.
      * a gold star Binomials, a package for binomial
        ideals with a particular focus on intersection decompositions and
        associated primes, has been published.
  * new packages:
      * BIBasis, a package for constructing reduced
        Pommaret and Gröbner bases in a Boolean ring, has been added.
      * CharacteristicClasses, a package for
        degrees of Chern classes and other characteristic classes of projective
        schemes, has been added.
      * KustinMiller, a package for unprojection and
        the Kustin-Miller complex construction, has been added.
      * MonomialAlgebras, a package for
        decomposing a monomial algebra as a module over a subalgebra, has been
        added.
      * MultiplierIdeals, a package for computing
        multiplier ideals of monomial ideals, has been added (originally called
        MonomialMultiplierIdeals).
      * NautyGraphs, a package for an interface to
        nauty (Graphs fork), has been added.
      * QthPower, a package for computing the integral
        closure of type I affine domains, has been added.
      * RandomObjects, RandomCanonicalCurves,
        see RandomCurves,
        RandomGenus14Curves,
        RandomPlaneCurves, and
        RandomSpaceCurves, packages for the
        construction of random points of unirational moduli spaces, have been
        added.
      * TensorComplexes, a package for multilinear
        algebra for the construction of tensor complexes, has been added.
      * Units, a package for conversion of units of measure,
        has been added.
      * VersalDeformations, a package for
        calculating versal deformations and local Hilbert schemes, has been
        added.
  * functionality added or improved:
      * The function temporaryFileName, now produces
        file names with no chance of collision, and deletes the files upon
        normal termination of the program.
      * The function newPackage, now has two new options,
        see newPackage(...,PackageExports=>...), and
        newPackage(...,PackageImports=>...), which provide a more
        robust way to specify that other packages should be loaded when this
        new package is loaded.
      * The new functions limitFiles, and
        limitProcesses, can be used to impose resource limits
        on the current process.
  * functionality changed:
      * Now F = GF p will return a ring of type GaloisField,
        when p is prime, instead of returning the quotient ring ZZ/p.  In
        particular, the generator F_0 will be a generator of the multiplicative
        group.

changes, 1.4
************

  * major improvements and additions:
      * In preparation for running Macaulay2 in parallel using threads, the
        Safe C language, in which the interpreter is written, has been
        reworked.  The chief advantage is that now, references to top level
        objects now consist of a single address pointer, and thus assignment
        can happen atomically.  Formerly, a small integer (for identifying the
        type of object pointed to) accompanied the pointer, but now it is
        stored with the rest of the object.  Also, new keywords have been added
        to allow the definition of new types, support has been added for
        translation to C++, and support for atomic operations and thread local
        variables has been added.
  * new packages:
      * AdjointIdeal, a package for adjoint ideals of
        plane curves, has been added.
      * BooleanGB, a package for Gröbner bases in
        Boolean rings, has been added.
      * DGAlgebras, a package for handling differential
        graded algebras, has been added.
      * FormalGroupLaws, a package for commutative
        formal group laws, has been added.
      * GraphicalModels, a package for discrete
        and Gaussian statistical graphical models, has been added.
      * Graphics, a package for creating graphics, has
        been added.
      * Graphs, a package providing data types,
        visualization, and basic functions for graphs, has been added.
      * a gold star HodgeIntegrals, a package for
        Hodge integrals on the moduli space of curves, has been added and
        certified.
      * Kronecker, a package for Kronecker and rational
        normal forms, has been added.
      * a gold star ModuleDeformations, a
        package for computing versal deformations of maximal Cohen-Macaulay
        modules, has been added and certified.
      * NAGtypes, a package containing declarations of
        types needed by two other packages, has been added.
      * Nauty, an interface package for the program nauty,
        which computes automorphism groups of graphs and digraphs, has been
        added.
      * a gold star Normaliz, an interface package to the
        program normaliz, which computes the Hilbert basis of a rational cone,
        has been certified.
      * NormalToricVarieties, a package
        designed to manipulate normal toric varieties and related geometric
        objects, has been added.
      * Parametrization, a package for rational
        parametrization of rational plane curves, has been added.
      * PHCpack, an interface package to the program
        PHCpack, which uses homotopy continuation methods to solve systems of
        polynomial equations numerically, has been added.
      * Serialization, a preliminary package for
        saving Macaulay2 objects in files, has been added.
      * a gold star SimplicialDecomposability,
        a package containing various
        decomposability routines for simplicial complexes, has been added and
        certified.
      * a gold star ToricVectorBundles, a
        package for vector bundles on toric varieties, has been added and
        certified.
      * WeylGroups, a package for root systems and Weyl
        groups, has been added.
  * improved packages:
      * directImageComplex (BGG), now has the ability
        to compute direct image complexes, and maps between them.
      * Polyhedra, a package for computations with
        convex polyhedra, has been improved: matrices that are returned from
        polyhedral objects are over ZZ, now, except for vertices of a
        polyhedron; see fourierMotzkin (FourierMotzkin), is
        now called only once, to increase the speed in higher dimensions.
      * Schubert2, a package for enumerative geometry,
        has been well documented (finally) and has been improved, e.g.
        incidence correspondences between flag varieties has been added.
      * The SimpleDoc, package, used for documentation in
        Macaulay2, has a new function, see multidoc (SimpleDoc), that
        allows multiple documentation nodes per string.  The format of the
        Consequences section has changed.  There is a new keyword, Pre, that
        allows preformatted text to be easily inserted.
      * The package XML, has been documented.
  * functionality added or improved:
      * The debugging function on, has been improved.
      * Gröbner bases over fields are now autoreduced, so the answer is
        mathematically well-defined.  Resulting changes in coefficients of
        polynomials in matrices returned by such functions as syz,
        and complement, may be observed.
      * The function basis, now is functorial: if given a matrix,
        it returns the matrix between the images of the bases of the source and
        target.
      * The functions basis, and truncate(List,Module) (Truncations),
        now allow partial
        multidegrees to be given. The result is a basis or generating set over
        the subring generated by variables whose initial degrees are zero.
      * Various bug fixes, including several memory leaks, and an efficiency
        related bug where e.g. generators gb I, of an ideal over the rationals,
        would take a long time to compute
      * TEX mode can now handle $\mapsto$.
      * Addition of ideals with an expression such as I+J has been extended to
        work in the case where I and J are ideals in different, but compatible,
        rings. Here compatibility means the one is an predecessor of the other,
        as would be the coefficient ring of a polynomial ring or the ambient
        ring of a quotient ring.
      * Added a new method, see matrix(RingElement),
        that makes a one by one matrix from a ring
        element.
      * Added a new method exp(RingElement), for
        the exponential function applied to a nilpotent ring element.
  * functionality changed:
      * Elements of sets are now sorted before printing.
      * Loading a package twice now gives an error unless you use the
        loadPackage(...,Reload=>...), option. Reloading a package
        can lead to subtle errors.  For example, if the package creates a new
        type, then it will do that each time the package is loaded, and objects
        of that type that were created before reloading will not work after
        reloading.  Also, reloading a package may cause a memory leak.
      * The function getSymbol, now always creates a symbol in
        the user dictionary, whereas formerly, it provided an existing symbol,
        or created one in the first mutable dictionary listed by
        dictionaryPath. The reason is that the main
        application in a package is to create symbols to server as variables in
        polynomial rings to be handed to the user, and the user will need those
        symbols to be visible.
      * The one-letter symbols, which are treated specially by vars,
        are now no longer pre-defined.  Now they are created when
        needed.  Packages can create them with getSymbol.
        This change is intended to prevent the kind of bug where a package
        unintentionally refers to or modifies a one-letter global variable.
      * Packages containing unset mutable private global symbols will now be
        flagged with an error message, and the locations of the offending
        symbols will be given.  This is intended to be an aid in detecting
        bugs, because one common way for such symbols to arise is by
        misspelling the name of a function parameter or the name of a local
        variable.  Another way they arise is by forgetting to declare that a
        variable used just inside the body of a function is a local variable.
      * A new way to create a polynomial ring in a package whose variables are
        based on symbols in the user dictionary is to put the names in
        quotation marks, like this: QQ["x","y"].  Now that the one-letter
        symbols are no longer predefined in the Core dictionary, something like
        this will be necessary, as QQ[x,y] will not work, because x and y will
        refer to private global symbols of the package, and will most likely
        now get flagged as errors.

changes, 1.3.1
**************

  * major improvements and additions:
      * packages newly included:
          * NumericalAlgebraicGeometry,
            -- Numerical Algebraic Geometry
          * BeginningMacaulay2, --
            Mathematicians' Introduction to  Macaulay2
  * functionality added or improved:
      * The behavior of loadDepth, has been reworked, with the
        goal being to arrange for error messages, signalled by code in a
        package that has been loaded without debugging mode enabled (see
        newPackage, and loadPackage), to appear
        to come from the user's code instead (when the filename, line number,
        and column number of the error are displayed).
      * Fixed a bug: determinants and minors in rings over RR or CC would give
        wrong answers or even crash M2.  The Bareiss strategy now gives an
        error in this case, and the Cofactor strategy is the default in this
        case. Additionally, pfaffians over such rings are now declared as not
        implemented.
      * Matrices over different rings can now be joined together (see
        Matrix | Matrix, Matrix || Matrix,
        and Matrix ++ Matrix).
      * The functions used with merge, and combine,
        now have a way to indicate that the resulting hashtable should have no
        entry corresponding to the current key.

changes, 1.3
************

  * major improvements and additions:
      * A new option newPackage(...,Certification=>...), for
        newPackage, provides information about packages that
        have been accepted for publication in a refereed journal.  The
        information is displayed in the top documentation node of the package.
        The first three packages so certified are EdgeIdeals,
        a gold star, see PieriMaps, a gold
        star, and Polyhedra, a gold star.
      * New packages OpenMath, and SCSCP,
        for communicating via SCSCP with OpenMath to programs such
        as GAP and Maple have been developed, thanks to Dan Roozemond.  They
        depend on the new package XML, which uses the libxml2
        library to parse XML code.
      * The programs 4ti2, gfan, and normaliz,
        are now included with Macaulay2 binary distributions, and are
        compiled automatically during Macaulay2's build process, with automatic
        downloading available as an option.  This makes the packages
        FourTiTwo, gfanInterface,
        Normaliz, and StatePolytope,
        each of which uses one or more of them, more
        readily usable.
      * packages newly included:
          * ConvexInterface -- Interface to the
            Maple package Convex.
          * MapleInterface -- Interface to Maple.
          * OpenMath -- OpenMath support
          * Posets -- a package for working with partially
            ordered sets
          * RationalPoints -- Find the rational
            points of an affine variety defined over a finite field
          * SCSCP -- SCSCP (Symbolic Computation Software
            Composability Protocol) support
          * SRdeformations -- Deformations of
            Stanley-Reisner rings and related computations.
          * XML -- an XML parser
      * Improved handling of finite fields: GF, now uses Conway polynomials (ConwayPolynomials),
        when possible. Maps between Galois
        fields made with them are now easy to produce with map(E,F).  (This was
        advertised as a change to 1.2, when the package was introduced, but the
        package was not pre-loaded, whereas now it is.).
      * Fixed a long-standing bug in saturate (Saturation), that
        caused it to give incorrect answers (too small) in the case that the
        following three conditions all held: the ring has a non-standard
        monomial ordering, such as a weight vector; all variables had degree 1;
        and the degree of the element being used to saturate was equal to 1.
      * The function toField, has been changed so that
        the expression F = toField A returns a new ring F isomorphic to A and
        declares it to be field, whereas formerly A was declared to be a field,
        without creating a new ring.  Users of this function should check their
        code and ensure that the return value F is used. The return value is a
        polynomial ring of no variables over A, with a new monomial ordering,
        and with degree length equal to 0.  The advantage is that now various
        computations in polynomial rings over the newly declared field will
        provide correct answers.
      * Fixed a bug in degree(x,f) where the degrees of the grading were used
        instead of the actual exponents.
      * Fixed a bug in read, reported by Dan Roozemond: whenever it
        would return a string of length 4096, subsequent read operations would
        change the bytes in it.
      * The package IntegralClosure, has been
        rewritten.  The ring used as input for integralClosure (IntegralClosure),
        must be a domain, but the
        documentation describes how to get around this. The function now
        provides correct output when it finishes, and it can handle much larger
        input than before.  There are some new routines and some new strategies
        for the computation.
      * A bug in Gröbner bases over the integers was fixed, which, under
        certain situations, led to an incomplete Gröbner basis.
      * A bug in Gröbner bases over fields and the integers was fixed, which
        caused, under some situations, the list of "trimmed" generators to be
        incomplete (but the Gröbner basis itself was correct). This impacted
        functions which use trim, especially minimalPrimes (MinimalPrimes).
      * The function eliminate (Elimination), has been fixed.
        The function previously quietly assumed a flat polynomial ring, with no
        quotient elements, and also quietly assumed that the ring was
        commutative.  Now error messages are given when it would have produced
        incorrect answers, and it handles Weyl and skew commutative poly rings
        correctly.  Additionally, this function now uses an elimination order
        rather than a product order, improving performance in many cases.
      * Fixed a a bug in independentSets, which
        produced incorrect answers on the cygwin version.  A variable was not
        being initialized.  Thanks to B. Roune for reporting the bug and
        suggesting the fix.
      * A bug in minimalPrimes (MinimalPrimes), was
        unearthed that could produce incorrect answers.  The problem was that
        trim, sometimes could produce incorrect answers (fixed).
      * Fixed a bug where if the degrees of the variables in a ring were not
        all equal to 1, and weight vectors were present, then the monomial
        ordering was not the documented one.
      * Fixed a bug in minimalPresentation, of an
        Ideal, or Ring, which would produce incorrect
        answers in rare situations.
  * functionality added or improved:
      * The method function minimalPresentation(Ring),
        now allows an option, see
        minimalPresentation(...,Exclude=>...),
        which takes a list of integers: the variables with these indices will
        not be eliminated.  Indices are used, because if the ring is a quotient
        by linear polynomials, then variables might have normal forms that are
        complicated polynomials.
      * The function installPackage, will now, when the
        option AbsoluteLinks is set to true, will now also search
        the installation prefix where the package is about to be installed for
        the files that are linked to. This should resolve the situation where a
        developer uses the function to modify a package that is already
        incorporated into Macaulay2 itself, and (some of) the links in the
        freshly installed package end up pointing to the wrong web pages.
      * The expression setRandomSeed() can now be used to re-initialize the
        random number generator; see setRandomSeed.
      * The operator .., can now be used to generate sequences of
        consecutive strings.
      * A new binary operator ..<, provides for the generation
        of sequences that stop one short of those provided by ..,
        .
      * The operator .., will now deliver rectangular sequences
        of consecutive indexed variables, e.g., x_1 .. y_2 will have the value
        (x_1,x_2,y_1,y_2).
      * A new variable, see handleInterrupts, specifies
        whether Macaulay2's interrupt handlers for SIGINT and SIGALRM are
        installed.
      * The function EXAMPLE, will now accept objects of type
        PRE (Text), to be interpreted as preformatted example output.
      * The function openListener, can now open
        a socket on a specified interface.
      * The function doc (SimpleDoc), will now handle example input
        expressions that span multiple lines: within in each expression, indent
        lines after the first one more than the first.
      * Multiplication of a scalar and a mutable matrix is now not allowed.
        Previously attempting this could cause Macaulay2 to crash.
      * Very long lists can now be parsed without overflowing the stack and
        causing the program to crash. This was a problem for MacOS with lists
        of length greater than about 90000.  In a future version we plan to
        reduce the amount of memory required to parse, translate, and then
        evaluate the list.
  * functionality changed:
      * The CTRL-C interrupt signal SIGINT will now interrupt system calls
        (such as read and write) that are in progress; formerly, they were
        restarted by the kernel after the handler set a flag.  This
        necessitated reworking the handling of interrupts by the top level
        interpreter, which will now respond to them immediately. When the
        readline library is active and reading user input (such as when the
        emacs interface to Macaulay2 is not used), interrupts are handled just
        by it.
      * currentDirectory, is now a function rather than
        a string constant, in order to postpone signalling an error if a
        component of the path to the current working directory no longer
        exists.
      * When the program starts, the random number seed is now initialized to a
        value that depends on the date, time in seconds, and the process id.
        The former initial state can be obtained with setRandomSeed().
      * The function realpath, now returns a string ending in
        '/' if the path leads to a directory, for consistency with the
        convention elsewhere in Macaulay2 that directory names end in '/'.
      * The UserMode, option to installPackage,
        and check, now has default value
        null, meaning to propagate the command line option -q, if
        present, to child processes running M2 on examples and tests
      * If you set the variable gbTrace, to 15, then now one
        sees a large amount of information about the S-pairs computed during a
        Gröbner basis computation, if the default algorithm is in use.
      * The initialization file init.m2 is now sought only in the user's
        application directory, and not also in the current directory.
  * new constants and operators:
      * New constants rootPath, and rootURI,
        provide prefixes to be prepended to absolute file paths so that native
        Microsoft Windows programs can find them.
      * New binary operators <==, and <===, have been
        introduced.  The operators are flexible, i.e., the user can install
        methods for them.

changes, 1.2
************

  * major improvements and additions:
      * Improved old documentation and added many new descriptions of
        functions.
      * Greatly improved the debugger. In particular, the debugger will put you
        directly onto the line of the program with an error, and allows the
        user to execute a given number of steps of the program (see step)
        and to conveniently display and change values of variables as
        they evolve.
      * Improved the making of packages: made it much easier for a user to
        create a complete package, including documentation.
      * Improved the handling of symmetric algebras and Rees algebras; improved
        implementation of things like analytic spread.
      * Improved handling of finite fields: GF, now uses Conway polynomials (ConwayPolynomials),
        when possible. Maps between Galois
        fields made with them are now easy to produce with map(E,F).  (Note:
        actually, the user must load the package manually.)
      * The function hilbertFunction, is now faster at
        computing power series expansions.
      * Homomorphisms (maps) of modules over different rings with respect to a
        ring homomorphism between them are now supported.  Composition, coimage
        (replacing pushForward1), and kernel work. An option has been added to
        basis, to ask it to return such a homomorphism.  See
        map(Module,Module,RingMap,Matrix),
        see
        map(Module,Nothing,RingMap,Matrix),
        and
        map(Module,RingMap).
      * The total Ext functor now accepts multigraded modules, see
        Ext(Module,Module).
      * Macaulay2 now incorporates PARI (see http://pari.math.u-bordeaux.fr/ ),
        a free library for computing in number theory. It is used by
        factor(ZZ), factor(QQ),
        see isPseudoprime(ZZ),
        and isPrime(ZZ).
      * new packages, included:
          * BGG -- Bernstein-Gel'fand-Gel'fand correspondence
          * BoijSoederberg -- Betti diagram
            routines
          * Bruns -- produces an ideal with three generators
            whose 2nd syzygy module is isomorphic to a given module
          * ConwayPolynomials -- database of
            Conway polynomials for use with GF
          * EdgeIdeals -- A package for working with
            the edge ideals of (hyper)graphs
          * FourTiTwo -- Interface for 4ti2
          * gfanInterface -- a Macaulay2 interface
            to gfan
          * LocalRings -- Localizations of polynomial
            rings at prime ideals
          * Polyhedra -- for computations with convex
            polyhedra, cones, and fans
          * Polymake -- a package for interfacing with
            polymake
          * SimpleDoc -- simpler documentation for
            functions and methods
          * StatePolytope -- computes state
            polytopes of ideals
          * SymmetricPolynomials -- the
            algebra of symmetric polynomials
          * Text -- documentation and hypertext
      * downloadable packages (see http://www.math.uiuc.edu/Macaulay2/Packages/
        ):
          * Kronecker, Kronecker normal form of a matrix pencil, by Edward
            Carter
          * LDL, the LDL' factorization of a positive semidefinite matrix, by
            Helfried Peyrl
      * improved packages:
          * HyperplaneArrangements, --
            manipulating hyperplane arrangements
          * ReesAlgebra -- Compute Rees algebras and
            their invariants
          * PieriMaps -- Pieri inclusions
          * Schubert2 -- computation in intersection
            theory
          * SchurFunctors -- for computing Schur
            functors
  * new functions:
      * groupID -- the process group identifier
      * heft -- heft vector of ring or monoid
      * insert -- copy a list, inserting an element
      * inversePermutation -- inverse permutation
      * isSorted -- whether a list is sorted
      * multidegree -- multidegree
      * runLengthEncode -- run length
        encoding
      * selectVariables, --
        make a subring of a polynomial ring generated by selected variables
      * step -- step by single lines in the debugger
      * switch -- copy a list, switching two elements
  * new methods for old functions:
      * all(ZZ,Function) -- whether all
        elements of a list satisfy a specified condition
      * any(ZZ,Function) -- whether any
        elements of a list satisfy a specified condition
      * degreesMonoid(List) -- the ring or monoid
        of degrees
      * degreesRing(Monoid) -- the ring or monoid of
        degrees
      * degreesRing(List) -- the ring or monoid
        of degrees
      * export(String) -- export symbols from a package
      * findFiles(List) -- find files recursively
      * flattenRing(Ideal) -- write a ring as a (quotient
        of a) polynomial ring
      * gcd(RingElement,ZZ) -- greatest common divisor
      * gcd(ZZ,RingElement) -- greatest common divisor
      * indices(Matrix) -- indices of
        variables occurring in a polynomial
      * map(Module,Module,RingMap,Matrix)
        -- homomorphism of modules
        over different rings
      * map(Module,Nothing,RingMap,Matrix)
        -- homomorphism of modules
        over different rings
      * map(Module,RingMap),
        -- homomorphism of modules over different rings
      * map(Module,ZZ,ZZ), --
        construct the map induced by multiplication by a ring element on the
        generators
      * max(GradedModule)
      * min(GradedModule)
      * part(InfiniteNumber,InfiniteNumber,VisibleList,RingElement)
        -- select terms of a polynomial by degree(s) or weight(s)
      * part(InfiniteNumber,InfiniteNumber,RingElement) -- select
        terms of a polynomial by degree(s) or weight(s)
      * part(InfiniteNumber,ZZ,VisibleList,RingElement) -- select
        terms of a polynomial by degree(s) or weight(s)
      * part(InfiniteNumber,ZZ,RingElement) -- select terms of a
        polynomial by degree(s) or weight(s)
      * part(Nothing,Nothing,VisibleList,RingElement) -- select
        terms of a polynomial by degree(s) or weight(s)
      * part(Nothing,Nothing,RingElement) -- select terms of a
        polynomial by degree(s) or weight(s)
      * part(Nothing,ZZ,VisibleList,RingElement) -- select terms
        of a polynomial by degree(s) or weight(s)
      * part(Nothing,ZZ,RingElement) -- select terms of a
        polynomial by degree(s) or weight(s)
      * part(ZZ,InfiniteNumber,VisibleList,RingElement) -- select
        terms of a polynomial by degree(s) or weight(s)
      * part(ZZ,InfiniteNumber,RingElement) -- select terms of a
        polynomial by degree(s) or weight(s)
      * part(ZZ,VisibleList,RingElement) -- select terms of a
        polynomial by degree(s) or weight(s)
      * part(ZZ,Nothing,VisibleList,RingElement) -- select terms
        of a polynomial by degree(s) or weight(s)
      * part(ZZ,Nothing,RingElement) -- select terms of a
        polynomial by degree(s) or weight(s)
      * part(ZZ,ZZ,VisibleList,RingElement) -- select terms of a
        polynomial by degree(s) or weight(s)
      * part(ZZ,ZZ,RingElement) -- select terms of a polynomial by
        degree(s) or weight(s)
      * quotientRemainder(Number,RingElement)
        -- quotient and
        remainder
      * quotientRemainder(RingElement,Number)
        -- quotient and
        remainder
      * quotientRemainder(RingElement,RingElement)
        -- quotient and
        remainder
      * scanLines(Function,List) -- apply a function to each
        line of a file
      * support(Matrix) -- list of variables occurring in a
        polynomial or matrix
      * Sequence <- Thing -- assignment with left side evaluated
      * Number _ Ring -- promote to another ring
      * GradedModuleMap | GradedModuleMap
        -- a binary operator, often used for horizontal
        concatenation
      * symmetricAlgebra(Matrix) -- the symmetric
        algebra of a module
      * symmetricAlgebra(Nothing,Nothing,Matrix), --
        the symmetric algebra of a module
      * symmetricAlgebra(Nothing,Ring,Matrix) -- the
        symmetric algebra of a module
      * symmetricAlgebra(Ring,Nothing,Matrix) -- the
        symmetric algebra of a module
      * symmetricAlgebra(Ring,Ring,Matrix) -- the
        symmetric algebra of a module
      * Number ^ Ring -- lift to another ring
      * Number ^ RingFamily -- lift to another ring
  * new variables:
      * currentLayout -- relative locations of Macaulay2
        files
      * prefixPath -- absolute locations of Macaulay2 files
      * lastMatch -- regular expression matching
  * new symbols:
      * FlatMonoid
      * Join -- an optional argument
      * Reduce -- an optional argument
      * Result -- an optional argument
      * RunExamples -- an optional argument
      * SeparateExec -- an optional argument
      * SourceRing -- an optional argument
  * new optional arguments to functions:
      * GF(...,SizeLimit=>...) -- make a finite field
      * basis(...,SourceRing=>...) -- basis or generating set of
        all or part of a ring, ideal or module
      * check(...,UserMode=>...) -- perform tests of a package
      * fillMatrix(...,Height=>...) -- fill a mutable matrix
        with random numbers
      * flattenRing(...,Result=>...)
        -- optionally specify
        which output(s) to return (see Description for details)
      * hilbertSeries(...,Reduce=>...)
        -- reduce the Hilbert
        series
      * installPackage(...,CacheExampleOutput=>...), --
        load and install a package and its documentation
      * installPackage(...,RunExamples=>...) -- load and
        install a package and its documentation
      * installPackage(...,SeparateExec=>...) -- load
        and install a package and its documentation
      * installPackage(...,UserMode=>...) -- load and
        install a package and its documentation
      * installPackage(...,Verbose=>...) -- load and
        install a package and its documentation
      * lift(...,Verify=>...) -- lift to another ring
      * map(...,DegreeLift=>...) -- make
        a ring map
      * monoid(...,DegreeLift=>...)
        -- specify maps between
        degree groups
      * monoid(...,Join=>...),
        -- specify how to handle degrees in the coefficient ring
      * newPackage(...,CacheExampleOutput=>...) -- the
        preamble of a package
      * newRing(...,DegreeLift=>...) -- make a copy of a ring,
        with some features changed
      * newRing(...,DegreeMap=>...) -- make a copy of a ring,
        with some features changed
      * newRing(...,Join=>...) -- make a copy of a ring, with
        some features changed
      * symmetricAlgebra(...,DegreeLift=>...) -- the
        symmetric algebra of a module
      * symmetricAlgebra(...,DegreeMap=>...) -- the
        symmetric algebra of a module
      * symmetricAlgebra(...,Join=>...) -- the
        symmetric algebra of a module
      * tensor(Monoid,Monoid,DegreeLift=>...)
        -- tensor product of monoids
      * tensor(Monoid,Monoid,DegreeMap=>...)
        -- tensor product of monoids
      * tensor(Monoid,Monoid,Join=>...), --
        tensor product of monoids
  * functionality removed or changed:
      * Comparison of rings and ring maps with ==, is no longer
        supported. Old code can be fixed by changing the comparison operator to
        ===.
      * The variable randomHeight has been removed, replaced by
        fillMatrix(...,Height=>...), and
        random(...,Height=>...).
      * The function betti, now uses the dot product of the heft
        vector of the ring with the (multi)degrees of the basis elements in a
        chain complex in its display.  See heft vectors.
      * The behavior of return, in the debugger has changed: it
        now stops in the debugger at the next available opportunity.
      * The function minors, has been altered so
        the ideal of n by n minors that it provides for negative values of n is
        the unit ideal.
      * The optional argument to monoid, and to polynomial ring
        creation named ConstantCoefficients has been removed.  Specifying
        ConstantCoefficients=>false can be accomplished by specifying
        Join=>false.  See Join.
  * functionality added or improved:
      * Filenames starting with ~/ will have the tilde replaced by the home
        directory.
      * The D language, in which the Macaulay2 interpreter is written, is now
        type-safe
      * During compilation of Macaulay2, as much of the computation as possible
        is now done to satisfy the make-target all, with the resulting files
        placed in a staging area, ready for quickly satisfying the make-target
        install.
      * During compilation of Macaulay2, it is now possible to keep the
        architecture independent files in a separate directory tree, saving
        time if versions for multiple architectures are to be built.  Including
        those files in a source tar file will allow the distribution of a fat
        source tar file, speeding up compilation.
      * Pressing the RET key in the Macaulay2 interaction buffer on a line
        containing a source file name and line number will open up the source
        file at that position in a new buffer.  This allows error messages to
        be treated with dispatch.
      * The behavior of setup, has changed, in that the commands
        that set the paths are now placed in separate files in the home
        directory of the user, and those files are sourced only if they are
        present.  That enables the user to continue to share the usual init
        files on multiple machines, even though Macaulay2 may be installed in
        various different locations.
      * A new division algorithm has been implemented in rings with monomials
        less than 1, e.g., where the monomials can involve negative exponents,
        and hence do not form a well-ordered set. See division in polynomial rings with monomials less than 1.
      * A bug in irreducibleCharacteristicSeries,
        upon with minimalPrimes (MinimalPrimes),
        depends, was fixed.  Now the new ring
        supporting the characteristic series will have variables with the same
        names and degrees, but the ordering of the variables and the monomial
        ordering will be different.  This ensures that homogeneity will be
        preserved.  Also, for convenience, the routine now returns a sequence,
        instead of a list, suitable for immediate parallel assignment.
      * The function part, has been altered so that for multigraded
        rings, it does not use the first component of the degree vector.  New
        functionality has been added, and the method for
        part(Sequence,RingElement) has been removed.
      * Heft vectors are now automatically computed, see heft vectors.
        Users who specify the Heft option explicitly may be
        able to avoid that now.
      * The description of a ring provided by describe, is now
        abbreviated by making use of run length encoding.
      * Browsers started by viewHelp, are now run in a separate
        process group so they don't die when Macaulay2 terminates.
      * The function prune, and decompose, are no
        longer exact synonyms of minimalPresentation,
        and minimalPrimes (MinimalPrimes),
        respectively.
      * The function get, has been fixed so it returns an error
        message if the process associated with the pipe has died.
      * The function searchPath, now does
        what the documentation said it would do.
      * The output operation s<<x, when s is a string, has been changed so that
        if a file with filename s is already open, that file will be used
        instead of opening a new file with the same name, erasing the data
        already written to the file.
      * Tensor product of a module with a ring has been modified so it will
        make a ring map between the two rings that is derived from the names of
        the variables.
      * The degrees in symmetric algebras have been corrected.
      * The default for polynomial rings over polynomial rings is now to join
        the degree vectors of monomials in the base to the degree vectors of
        the top level monoid, usually resulting in a multigraded ring.  For
        example, QQ[x][y] is now bigraded.
      * Inverting a noninvertible matrix results in an error message now.
      * The function export, given a string (rather than a
        symbol) will now make a new symbol with that name, even if a symbol
        with the same name already exists in another visible package.
      * The function basis, will now check finite dimensionality
        in advance, to avoid running out of memory.
      * Functions and types associated with hypertext and documentation have
        been isolated in a new package called Text, which
        gets loaded automatically by beginDocumentation.
      * errorCode has been renamed to current,
      * The file layout system, as described by Layout,
        formerly called LAYOUT, now supports separation of architecture
        independent files from architecture dependent files.
      * The cross reference hyperlinks in the info form of the documentation
        have been improved, but we recommend reading it in emacs with M-x info,
        configuring the emacs variable Info-hide-note-references so its value
        is hide. See reading the documentation.
      * Now the function needs, will reload the requested file not
        only if the file has not been loaded before, but also if it has changed
        since the previous time.
      * It is now possible to represent a series of three or more slashes
        within a string delimited by ///, by typing a longer series.
      * The conversion of TEX (Text), to html has been improved and
        documented, see html(TEX) (Text).
      * Unicode, encoded in utf-8 format, is supported in documentation pages,
        both in html form and in emacs info form: 你好.
      * When an error occurs within a string being evaluated with value,
        the appropriates lines of the string will be displayed if the
        debugger is entered.
      * A new method for substring, accepts a pair of integers
        as first argument of the sort returned by regex.
      * Regular expression handling, by the functions regex,
        match, replace, and select,
        is now much faster because strings are not copied.
      * The function regex, now has a form that restricts the
        range of the search.
      * Macaulay2 now incorporates frobby, a free library for
        computing the Alexander dual of a monomial ideal (see
        dual(MonomialIdeal)).
      * The function select, will now give an error message if
        the function provided to it returns something neither true,
        nor false.
      * The quotient and remainder for two ring elements can now be obtained
        simultaneously, saving time.  See
        quotientRemainder(RingElement,RingElement).
      * The binary representation of a real number is now available using
        promote(RR,type of QQ). The code for lift(RR,type of QQ),
        has been tightened up so a rational number is provided that
        provides exactly the same real number when promoted.
      * The emacs commands M-x M2, bound to f12, and M2-send-to-program, bound
        to f11, have some new capability. With prefix argument C-u C-u to M-x
        M2, the tag from which the buffer name is constructed (by prepending
        and appending asterisks) can be entered in the minibuffer. With a
        prefix argument to M2-send-to-program, the name of the buffer to which
        this and future uses of the command (in this buffer) should be sent can
        be entered, with history.
      * The function symmetricAlgebra, is now
        functorial.

changes, 1.0 and 1.1
********************

 Versions have been compiled specifically for the following GNU/Linux systems:
generic Linux, Ubuntu (32 bit and 64 bit), Debian (32 bit and 64 bit) both with
*.deb files, Fedora 7, Fedora 8, and Red Hat Enterprise 4, with *.rpm files;
for the following Macintosh OS X systems: 10.4 and 10.5 on Intel 32 bit, 10.5
on Intel 64 bit, and 10.4 on the Power PC; and on Microsoft Windows with the
Cygwin compatibility package installed. Automatic installation from our
repositories is possible for Debian, Ubuntu, and Microsoft Windows.  The files
for downloading are now divided into two archives, depending on whether they
depend on the architecture.

Packages have been contributed: NoetherNormalization,
by Bart Snapp and Nathaniel Stapleton; see
GenericInitialIdeal, and Regularity,
by Alexandra Seceleanu and Nathaniel Stapleton; see
InvolutiveBases, by Daniel Robertz; see
ChainComplexExtras, by Frank Moore and Greg Smith;
see HyperplaneArrangements, by Graham Denham
and Gregory G. Smith; see LexIdeals, by Chris Francisco;
see ReesAlgebra, by David Eisenbud, Amelia Taylor, and
Sorin Popescu; and TangentCone, by Craig Huneke and
David Eisenbud.

A good implementation of real and complex numbers to arbitrary precision, based
on the mpfr library from http://mpfr.org/, has been implemented.  The library
is remarkable for the care taken to return correctly rounded results.  It is
hoped that this will form a good base for experimentation with algebraic
algorithms that mix symbolic and numeric techniques.  Basic transcendental
functions are also provided, and pi is now a symbolic constant usable in
numeric expressions of any precision.  An interface to lapack routines for
singular value decomposition and eigenvectors is provided (but they operate
only with 53 bits of precision).

 An interface with TeXmacs has been provided, so Macaulay2 can be run with a
good graphical user interface.  More work remains to be done, but it is usable.

 Documentation has been improved, with every function documented.

 Computation of Gröbner bases over local rings has been improved.  New notation
QQ{x,y,z} for local rings.  More precisely

 The default (GRevLex) monomial ordering in polynomial rings whose variables
don't all have degree 1 was fixed to take the degrees into account.  More
precisely, the ordering now uses the values obtained by scalar product of the
provided heft vector with the degree vector.

 The implementation of the Gröbner basis algorithm for polynomial rings where
the multidegrees of the variables don't all have strictly positive first
component has been fixed by having it use the heft vector provided. The problem
was that bases were not minimalized, and S-pairs were addressed in a
non-optimal order.  (The total Ext functor Ext(M,N) used this facility and was
returning wrong answers.)

 A bug in division (f//g) resulting in incorrect answers over quotient rings
was fixed.

A bug in trim, and mingens, resulting in incorrect
answers was fixed.

 A bug in computation of the Gröbner basis of an exterior algebra over Z was
fixed.

A bug in fraction division was fixed.  Fraction field code now checks for
non-units in many more places.  For rings that have been declared by the user
to be fields, and yet are not fields, attempting to divide by a non-unit
results in an error, and sets a value so that the function getNonUnit,
returns that value.

 The Gröbner basis routine can now handle large monomial ideals without a stack
overflow.

The function monomialIdeal, over polynomial rings over
ZZ, now incorporates leading monomials with nonzero coefficients.
Formerly the coefficients had to be units.

 Codimension (and dimension) computations over polynomial rings over Z work
once again.

 The speed of computation of projective resolutions when the first components
of the degrees of the variables are not necessarily positive has been improved.

 The interpreter has been fixed so it more often detects extreme recursion; one
case was omitted that allowed the machine stack to overflow with a segmentation
fault.

 The function "betti" now returns a new type of object of class BettiTally,
which can be manipulated with the operations that can manipulate chain
complexes.

Support for utf-8 encoding of unicode characters in strings provided via
utf8.

A new function scanLines, can be used for reading a big file
one line at a time.

A new format for multi-line block comments is {* ... *}.

M2 can now be run with script files by using

       #! /usr/bin/M2 --script

as the first line of the script file.

 Under Microsoft Windows, the links in the html form of the documentation now
work in such a way that browsers can follow them, and viewHelp now works (if it
finds firefox).

Here are the functions added to the Core package since 0.9.95: acosh,
see acot, agm, ancestors,
asinh, atan2, BesselJ, BesselY,
see clean, commonest, commonRing,
see cot, coth, cpuTime,
csc, csch, debugError, default,
see eint, erf, erfc, expm1,
see fillMatrix, Gamma, gbRemove,
see gbSnapshot, getSymbol,
globalAssign, httpHeaders,
installHilbertFunction, instances,
isANumber, isFinite, isInfinite,
see isReal, lngamma, log1p,
see LUdecomposition, markedGB,
see norm, openOutAppend,
see parts, powermod,
scanLines, sec, sech,
seeParsing, setupEmacs, size2,
toCC, toRR, utf8, wikipedia (SimpleDoc),
and zeta.

 Compilation of Macaulay2 from source has been improved.  Needed third party
libraries will now be downloaded and compiled automatically if they are not
already provided.

 More tests have been added (to verify, after compilation, that M2 is working
as expected).

list of obsolete functions
**************************

  * obsolete classes
      * Thread has been replaced by Task,
  * obsolete functions
      * 'mutableZero' has been replaced by mutableMatrix,
      * 'unlist' has been replaced by toSequence,
      * 'evaluate' has been replaced by value,
      * 'seq x' has been replaced by 'singleton x', which has been replaced by
        '1:x'
      * 'verticalJoin' has been replaced by stack,
      * 'netRows' has been replaced by unstack,
      * 'name' has been replaced by toString,
      * 'quote' has been replaced by symbol,
      * 'Numeric' has been replaced by numeric,
      * 'submodule' has been removed
      * 'monomialCurve' has been replaced by monomialCurveIdeal,
      * 'assign' has been replaced by <-,
      * 'minprimes' has been replaced by independentSets,
      * 'elapsedTime' has been renamed to cpuTime,
      * 'pushForward1(f,M)' has been replaced by 'relations coimage map(M,f)'
      * adjoint1 has been replaced by adjoint', whose interface
        is different
  * obsolete methods
      * Wikipedia(String) has been replaced: use wikipedia (SimpleDoc),
        instead
      * 'map(Ideal)' has been removed: use 'map(module I,module I, 1)' instead
      * 'map(Ideal,Ideal)' has been removed: use 'map(module I,module J)'
        instead
      * 'map(Module,Matrix)' has been replaced: use 'map(M,,f)' instead
      * 'map(Module,RingElement)' has been removed: use 'map(M,M,r)' instead
      * 'RingElement _ ZZ' has been replaced: use 'part(n,f)' instead
      * 'RingElement _ List' has been replaced: use 'part(d,f)' instead
      * 'diff(RingElement)' has been removed: use 'diff(vars ring f, f)'
        instead
      * 'diff(Matrix)' has been removed: use 'diff(vars ring f, f)' instead
      * 'map(Module,Module)' has been removed: use 'inducedMap' instead
      * 'monomialIdeal(R)' has been removed: use 'monomialIdeal(0_R)' instead

mathematical examples
*********************

In this section we present some tutorials that aim to introduce the user to
some mathematical ways of using Macaulay2.  The tutorials are relatively
independent of each other, and each one introduces the use of some features of
Macaulay2 in a slow and leisurely way, assuming the reader is already familiar
with the mathematical concepts involved. See David Eisenbud,
joins us as a co-author of these tutorials.

Tutorial: Elementary uses of Groebner bases
*******************************************

-*- coding: utf-8 -*- In this tutorial we introduce a number of basic
operations using Gröbner bases, and at the same time become familiar with a
range of useful Macaulay2 constructs. The sections are:

A.  First steps; example with a monomial curve

B.  Random regular sequences

C.  Division with remainder

D.  Elimination theory

E.  Quotients and saturation

A. First Steps; example with a monomial curve

To compute the Gröbner basis of an ideal $(x^2y,xy^2+x^3)$ in the polynomial
ring in four variables we proceed as follows:

Our favorite field

+------------------+
|i1 : KK = ZZ/31991|
|                  |
|o1 = KK           |
|                  |
|o1 : QuotientRing |
+------------------+

The polynomial ring

+--------------------+
|i2 : R = KK[x,y,z,w]|
|                    |
|o2 = R              |
|                    |
|o2 : PolynomialRing |
+--------------------+

and the ideal

+-------------------------------+
|i3 : I = ideal(x^2*y,x*y^2+x^3)|
|                               |
|             2    3      2     |
|o3 = ideal (x y, x  + x*y )    |
|                               |
|o3 : Ideal of R                |
+-------------------------------+

now the punch line:

+-----------------------+
|i4 : J = gens gb I     |
|                       |
|o4 = | x2y x3+xy2 xy3 ||
|                       |
|             1      3  |
|o4 : Matrix R  <-- R   |
+-----------------------+

From this we can for example compute the codimension, dimension, degree, and
the whole Hilbert function and polynomial. This will be more fun if we work
with an example having some meaning.  We choose to work with the ideal defining
the rational quartic curve in $\PP^3$ given parametrically in an affine
representation by $$t \mapsto{} (t,t^3,t^4).$$ (The reader who doesn't
understand this terminology may ignore it for the moment, and treat the ideal
given below as a gift from the gods... .) We obtain the ideal by first making
the polynomial ring in 4 variables (the homogeneous coordinate ring of $\PP^3$)

+-------------------+
|i5 : R = KK[a..d]  |
|                   |
|o5 = R             |
|                   |
|o5 : PolynomialRing|
+-------------------+

and then using a function monomialCurveIdeal, which we shall treat for now as a
black box

+-------------------------------------------------------+
|i6 : I = monomialCurveIdeal(R,{1,3,4})                 |
|                                                       |
|                        3      2     2    2    3    2  |
|o6 = ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c)|
|                                                       |
|o6 : Ideal of R                                        |
+-------------------------------------------------------+

From Macaulay2's point of view, $I$ is an ideal, and the codimension of its
support is 2, while its dimension is 2:

+------------+
|i7 : codim I|
|            |
|o7 = 2      |
+------------+
|i8 : dim I  |
|            |
|o8 = 2      |
+------------+

This is the codimension of $R/I$ in $R$ and the dimension of $R/I$.  We could
work with the module $R/I$ as well. Precision requires writing $R^1$ instead of
$R$ ($R$ is a ring, and $R^1$ is the free module of rank 1 over it)

+------------------------+
|i9 : codim (R^1/(I*R^1))|
|                        |
|o9 = 2                  |
+------------------------+

We could also extract the generators of $I$ (as a matrix) and take the cokernel
to get the same thing:

+----------------------------------------------+
|i10 : M = coker gens I                        |
|                                              |
|o10 = cokernel | bc-ad c3-bd2 ac2-b2d b3-a2c ||
|                                              |
|                             1                |
|o10 : R-module, quotient of R                 |
+----------------------------------------------+
|i11 : codim M                                 |
|                                              |
|o11 = 2                                       |
+----------------------------------------------+
|i12 : dim M                                   |
|                                              |
|o12 = 2                                       |
+----------------------------------------------+

And similarly for the degree:

+--------------+
|i13 : degree I|
|              |
|o13 = 4       |
+--------------+
|i14 : degree M|
|              |
|o14 = 4       |
+--------------+

As one might expect, the degree of the quartic is 4 !  The Hilbert polynomial
is obtained by

+---------------------------------+
|i15 : hilbertPolynomial M        |
|                                 |
|o15 = - 3*P  + 4*P               |
|           0      1              |
|                                 |
|o15 : ProjectiveHilbertPolynomial|
+---------------------------------+

The term $\PP^i$ represents the Hilbert polynomial of projective $i$-space.
This formula tells us that the Hilbert polynomial of $M$ is $H(m) = 4(m+1) - 3
= 4m + 1$.  Thus the degree is four, the dimension of the projective variety
which is the support of $M$ is 1 (and so the affine dimension is 2), and that
the (arithmetic) genus is 0 (1 minus the constant term, for curves).

The Hilbert series of $M$ (the generating function for the dimensions of the
graded pieces of $M$) is

+--------------------------------+
|i16 : hilbertSeries M           |
|                                |
|           2     3     4    5   |
|      1 - T  - 3T  + 4T  - T    |
|o16 = -----------------------   |
|                     4          |
|              (1 - T)           |
|                                |
|o16 : Expression of class Divide|
+--------------------------------+

The indeterminate in this expression is \$T.

Another way to get information about the module $M$ is to see its free
resolution

+-----------------------------------+
|i17 : Mres = res M                 |
|                                   |
|       1      4      4      1      |
|o17 = R  <-- R  <-- R  <-- R  <-- 0|
|                                   |
|      0      1      2      3      4|
|                                   |
|o17 : ChainComplex                 |
+-----------------------------------+

To get more precise information about Mres, we could do

+--------------------+
|i18 : betti Mres    |
|                    |
|             0 1 2 3|
|o18 = total: 1 4 4 1|
|          0: 1 . . .|
|          1: . 1 . .|
|          2: . 3 4 1|
|                    |
|o18 : BettiTally    |
+--------------------+

The display is chosen for compactness: B    total: 1 4 4 1 B        0: 1 . . .
B        1: . 1 . . B        2: . 3 4 1 the first line gives the total betti
numbers, the same information given when we type the resolution.  The remaining
lines express the degrees of each of the generators of the free modules in the
resolution.  The $j$th column after the colons gives the degrees of generators
of the $j$th module(counting from $0$); an $n$ in the $j$th column in the row
headed by ``$d$:'' means that the $j$th free module has $n$ generators of
degree $n+j$.  Thus for example in our case, the generator of the third (last)
free module in the resolution has degree $3+2=5$.

B. Random regular sequences

An interesting and illustrative open problem is to understand the initial ideal
(and the Gröbner basis) of a ``generic'' regular sequence.  To study a very
simple case we take a matrix of 2 random forms in a polynomial ring in 3
variables:

+-----------------------------------------------------------------------------+
|i19 : R = KK[x,y,z]                                                          |
|                                                                             |
|o19 = R                                                                      |
|                                                                             |
|o19 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i20 : F = random(R^1, R^{-2,-3})                                             |
|                                                                             |
|o20 = | 107x2+4376xy+3187y2-5558xz+3783yz-5295z2                             |
|      -----------------------------------------------------------------------|
|      8570x3-15332x2y-10468xy2-8239y3+8444x2z+10359xyz+2653y2z-7452xz2+      |
|      -----------------------------------------------------------------------|
|      5071yz2-6191z3 |                                                       |
|                                                                             |
|              1      2                                                       |
|o20 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+

makes $F$ into a $1 \times 2$ matrix whose elements have degrees $2,3$ (that
is, $F$ is a random map to the free module $R^1$, which has its one generator
in the (default) degree, $0$, from the free module with generators in the
listed degrees, $\{2,3\}$).  We now can compute

+-----------------------------------------------------------------------------+
|i21 : GB = gens gb F                                                         |
|                                                                             |
|o21 = | x2+14392xy+12587y2+845xz+5716yz-7823z2                               |
|      -----------------------------------------------------------------------|
|      xy2+12057y3+3459xyz-9492y2z-3723xz2+1975yz2+10368z3                    |
|      -----------------------------------------------------------------------|
|      y4-9513y3z+14408xyz2-3635y2z2+9536xz3-11704yz3-6151z4 |                |
|                                                                             |
|              1      3                                                       |
|o21 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i22 : LT = leadTerm gens gb F                                                |
|                                                                             |
|o22 = | x2 xy2 y4 |                                                          |
|                                                                             |
|              1      3                                                       |
|o22 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i23 : betti LT                                                               |
|                                                                             |
|             0 1                                                             |
|o23 = total: 1 3                                                             |
|          0: 1 .                                                             |
|          1: . 1                                                             |
|          2: . 1                                                             |
|          3: . 1                                                             |
|                                                                             |
|o23 : BettiTally                                                             |
+-----------------------------------------------------------------------------+

shows that there are Gröbner basis elements of degrees 2,3, and 4.  This result
is dependent on the monomial order in the ring $R$; for example we could take
the lexicographic order

+-----------------------------------------+
|i24 : R = KK[x,y,z, MonomialOrder => Lex]|
|                                         |
|o24 = R                                  |
|                                         |
|o24 : PolynomialRing                     |
+-----------------------------------------+

(see help MonomialOrder for other possibilities). We get

+-----------------------------------------------------------------------------+
|i25 : F = random(R^1, R^{-2,-3})                                             |
|                                                                             |
|o25 = | 12365x2-13496xy-9468xz-11938y2+8231yz+5864z2                         |
|      -----------------------------------------------------------------------|
|      5026x3+10259x2y-7489x2z+9534xy2-7204xyz-10113xz2+7256y3-5309y2z+6230yz2|
|      -----------------------------------------------------------------------|
|      +9033z3 |                                                              |
|                                                                             |
|              1      2                                                       |
|o25 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i26 : GB = gens gb F                                                         |
|                                                                             |
|o26 = | y6-8008y5z+7794y4z2-5193y3z3-14781y2z4-5196yz5+7619z6                |
|      -----------------------------------------------------------------------|
|      xz4+13855y5-14988y4z+15518y3z2+11760y2z3-15752yz4+15870z5              |
|      -----------------------------------------------------------------------|
|      xyz2-14606xz3-412y4+13343y3z-6269y2z2-10851yz3-13370z4                 |
|      -----------------------------------------------------------------------|
|      xy2-10538xyz+5129xz2-4072y3-2528y2z+10043yz2-5766z3                    |
|      -----------------------------------------------------------------------|
|      x2+15085xy-14572xz-11778y2+7708yz+4065z2 |                             |
|                                                                             |
|              1      5                                                       |
|o26 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i27 : LT = leadTerm gens gb F                                                |
|                                                                             |
|o27 = | y6 xz4 xyz2 xy2 x2 |                                                 |
|                                                                             |
|              1      5                                                       |
|o27 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i28 : betti LT                                                               |
|                                                                             |
|             0 1                                                             |
|o28 = total: 1 5                                                             |
|          0: 1 .                                                             |
|          1: . 1                                                             |
|          2: . 1                                                             |
|          3: . 1                                                             |
|          4: . 1                                                             |
|          5: . 1                                                             |
|                                                                             |
|o28 : BettiTally                                                             |
+-----------------------------------------------------------------------------+

and there are Gröbner basis elements of degrees $2,3,4,5,6.$

C. Division With Remainder

A major application of Gröbner bases is to decide whether an element is in a
given ideal, and whether two elements reduce to the same thing modulo an ideal.
For example, everyone knows that the trace of a nilpotent matrix is 0. We can
produce an ideal $I$ that defines the variety $X$ of nilpotent $3 \times 3$
matrices by taking the cube of a generic matrix and setting the entries equal
to zero.  Here's how:

+-----------------------------------------------------------------------------+
|i29 : R = KK[a..i]                                                           |
|                                                                             |
|o29 = R                                                                      |
|                                                                             |
|o29 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i30 : M = genericMatrix(R,a,3,3)                                             |
|                                                                             |
|o30 = | a d g |                                                              |
|      | b e h |                                                              |
|      | c f i |                                                              |
|                                                                             |
|              3      3                                                       |
|o30 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i31 : N = M^3                                                                |
|                                                                             |
|o31 = | a3+2abd+bde+2acg+bfg+cdh+cgi                                         |
|      | a2b+b2d+abe+be2+bcg+ach+ceh+bfh+chi                                  |
|      | a2c+bcd+abf+bef+c2g+cfh+aci+bfi+ci2                                  |
|      -----------------------------------------------------------------------|
|      a2d+bd2+ade+de2+cdg+afg+efg+dfh+fgi a2g+bdg+cg2+adh+deh+fgh+agi+dhi+gi2|
|      abd+2bde+e3+bfg+cdh+2efh+fhi        abg+beg+bdh+e2h+cgh+fh2+bgi+ehi+hi2|
|      acd+cde+bdf+e2f+cfg+f2h+cdi+efi+fi2 acg+bfg+cdh+efh+2cgi+2fhi+i3       |
|      -----------------------------------------------------------------------|
|      |                                                                      |
|      |                                                                      |
|      |                                                                      |
|                                                                             |
|              3      3                                                       |
|o31 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i32 : I = flatten N                                                          |
|                                                                             |
|o32 = | a3+2abd+bde+2acg+bfg+cdh+cgi a2b+b2d+abe+be2+bcg+ach+ceh+bfh+chi     |
|      -----------------------------------------------------------------------|
|      a2c+bcd+abf+bef+c2g+cfh+aci+bfi+ci2 a2d+bd2+ade+de2+cdg+afg+efg+dfh+fgi|
|      -----------------------------------------------------------------------|
|      abd+2bde+e3+bfg+cdh+2efh+fhi acd+cde+bdf+e2f+cfg+f2h+cdi+efi+fi2       |
|      -----------------------------------------------------------------------|
|      a2g+bdg+cg2+adh+deh+fgh+agi+dhi+gi2 abg+beg+bdh+e2h+cgh+fh2+bgi+ehi+hi2|
|      -----------------------------------------------------------------------|
|      acg+bfg+cdh+efh+2cgi+2fhi+i3 |                                         |
|                                                                             |
|              1      9                                                       |
|o32 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+

(actually this produces a 1 x 9 matrix of of forms, not the ideal: J = ideal I;
the matrix will be more useful to us). But the trace is not in $I$!  This is
obvious from the fact that the trace has degree $1$, but the polynomials in $I$
are of degree $3$. We could also check by division with remainder:

+-------------------------------------------------+
|i33 : Tr = trace M                               |
|                                                 |
|o33 = a + e + i                                  |
|                                                 |
|o33 : R                                          |
+-------------------------------------------------+
|i34 : Tr //I  -- the quotient, which is 0        |
|                                                 |
|o34 = 0                                          |
|                                                 |
|              9      1                           |
|o34 : Matrix R  <-- R                            |
+-------------------------------------------------+
|i35 : Tr % I  -- the remainder, which is Tr again|
|                                                 |
|o35 = a + e + i                                  |
|                                                 |
|o35 : R                                          |
+-------------------------------------------------+

(Here Tr is an element of $R$, not a matrix. We could do the same thing with a
$1 \times 1$ matrix with Tr as its element.) This is of course because the
entries of $I$ do NOT generate the ideal of all forms vanishing on $X$ -- this
we may find with J = radical ideal I, (but this takes a while: see the
documentation for radical on a faster way to find this) which shows that the
radical is generated by the trace, the determinant, and the sum of the
principal $2 \times 2$ minors, that is, by the coefficients of the
characteristic polynomial. In particular, we can try the powers of the radical:

+-----------------------------------------------------------------------------+
|i36 : Tr^2 % I                                                               |
|                                                                             |
|       2           2                  2                                      |
|o36 = a  + 2a*e + e  + 2a*i + 2e*i + i                                       |
|                                                                             |
|o36 : R                                                                      |
+-----------------------------------------------------------------------------+
|i37 : Tr^3 % I                                                               |
|                                                                             |
|        2                 2     3                                2           |
|o37 = 3a e + 3b*d*e + 3a*e  + 3e  + 3b*f*g + 3c*d*h + 6e*f*h + 3a i + 6a*e*i |
|      -----------------------------------------------------------------------|
|          2                          2       2     3                         |
|      + 3e i + 3c*g*i + 6f*h*i + 3a*i  + 3e*i  + 3i                          |
|                                                                             |
|o37 : R                                                                      |
+-----------------------------------------------------------------------------+
|i38 : Tr^4 % I                                                               |
|                                                                             |
|        2 2         2       3     4                                          |
|o38 = 6a e  + 6b*d*e  + 6a*e  + 6e  + 6b*e*f*g + 6c*d*e*h - 6b*d*f*h +       |
|      -----------------------------------------------------------------------|
|                    2                   2 2      2                       2   |
|      6a*e*f*h + 12e f*h - 6c*f*g*h - 6f h  + 12a e*i + 12b*d*e*i + 12a*e i +|
|      -----------------------------------------------------------------------|
|         3                                                               2 2 |
|      12e i + 12c*e*g*i + 6b*f*g*i + 6c*d*h*i + 6a*f*h*i + 36e*f*h*i + 6a i  |
|      -----------------------------------------------------------------------|
|               2     2 2         2          2       3        3     4         |
|      + 12a*e*i  + 6e i  + 6c*g*i  + 12f*h*i  + 6a*i  + 12e*i  + 6i          |
|                                                                             |
|o38 : R                                                                      |
+-----------------------------------------------------------------------------+
|i39 : Tr^5 % I                                                               |
|                                                                             |
|         2 2           2         3       4         2         2               |
|o39 = 30a e i + 30b*d*e i + 30a*e i + 30e i + 30c*e g*i + 30a f*h*i +        |
|      -----------------------------------------------------------------------|
|                                     2                         2 2           |
|      30b*d*f*h*i + 60a*e*f*h*i + 90e f*h*i + 30c*f*g*h*i + 30f h i +        |
|      -----------------------------------------------------------------------|
|         2   2            2        2 2      3 2            2            2    |
|      30a e*i  + 30b*d*e*i  + 30a*e i  + 30e i  + 30c*e*g*i  + 60a*f*h*i  +  |
|      -----------------------------------------------------------------------|
|                2      2 3          3          3      2 3          3         |
|      120e*f*h*i  + 30a i  + 30b*d*i  + 30a*e*i  + 30e i  + 30c*g*i  +       |
|      -----------------------------------------------------------------------|
|             3        4        4      5                                      |
|      90f*h*i  + 30a*i  + 30e*i  + 30i                                       |
|                                                                             |
|o39 : R                                                                      |
+-----------------------------------------------------------------------------+
|i40 : Tr^6 % I                                                               |
|                                                                             |
|         2 2 2          2 2        3 2      4 2        2   2      2     2    |
|o40 = 90a e i  + 90b*d*e i  + 90a*e i  + 90e i  + 90c*e g*i  + 90a f*h*i  +  |
|      -----------------------------------------------------------------------|
|                 2               2       2     2              2      2 2 2   |
|      90b*d*f*h*i  + 180a*e*f*h*i  + 270e f*h*i  + 90c*f*g*h*i  + 90f h i  + |
|      -----------------------------------------------------------------------|
|         2   3            3        2 3      3 3            3             3   |
|      90a e*i  + 90b*d*e*i  + 90a*e i  + 90e i  + 90c*e*g*i  + 180a*f*h*i  + |
|      -----------------------------------------------------------------------|
|                3      2 4          4          4      2 4          4         |
|      360e*f*h*i  + 90a i  + 90b*d*i  + 90a*e*i  + 90e i  + 90c*g*i  +       |
|      -----------------------------------------------------------------------|
|              4        5        5      6                                     |
|      270f*h*i  + 90a*i  + 90e*i  + 90i                                      |
|                                                                             |
|o40 : R                                                                      |
+-----------------------------------------------------------------------------+
|i41 : Tr^7 % I                                                               |
|                                                                             |
|o41 = 0                                                                      |
|                                                                             |
|o41 : R                                                                      |
+-----------------------------------------------------------------------------+

The seventh power is the first one in the ideal!  (Bernard Mourrain has worked
out a formula for which power in general.) In this case

+-----------------------------------------------------------------------------+
|i42 : Tr^6 // I                                                              |
|                                                                             |
|o42 = {3} | a3+6a2e+3bde+15ae2+22e3+6efh+6a2i+30aei+60e2i+6fhi+15ai2+60ei2+22|
|      {3} | 0                                                                |
|      {3} | 0                                                                |
|      {3} | -27abe-45be2+9ceh+30bfh-72abi-144bei+75chi                       |
|      {3} | -2a3+15a2e+21bde+6ae2+e3+33bfg+9cdh-36afh+51efh+60a2i+72bdi+30aei|
|      {3} | 18abg+45beg+3a2h+9bdh-21aeh+3e2h+9cgh+36fh2+114bgi-135ahi-39ehi+3|
|      {3} | 18ace+6abf-36bef-18cfh+66aci+36cei-57bfi+132ci2                  |
|      {3} | -3a2f-39bdf+75aef-12e2f+9cfg-36f2h-66cdi+135afi+51efi+69fi2      |
|      {3} | -2a3-18abd-30a2e-60bde-30ae2-44e3-18ceg-33bfg-9cdh+18afh-93efh-75|
|      -----------------------------------------------------------------------|
|      i3                                                  |                  |
|                                                          |                  |
|                                                          |                  |
|                                                          |                  |
|      +6e2i+66cgi+147fhi-30ai2-75ei2-26i3                 |                  |
|      6hi2                                                |                  |
|                                                          |                  |
|                                                          |                  |
|      a2i-90bdi-60aei-75e2i-66cgi-171fhi-84ai2-84ei2-89i3 |                  |
|                                                                             |
|              9      1                                                       |
|o42 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+

is not 0.  It is a matrix that makes the following true:

+------------------------------------------+
|i43 : Tr^6 == I * (Tr^6 // I) + (Tr^6 % I)|
|                                          |
|o43 = true                                |
+------------------------------------------+

D. Elimination Theory

Consider the problem of projecting the ``twisted cubic'', a curve in $\PP^3$
defined by the three $2 \times 2$ minors of a certain $2 \times 3$ matrix into
the plane. Such problems can be solved in a very simple and direct way using
Gröbner bases. The technique lends itself to many extensions, and in its
developed form can be used to find the closure of the image of any map of
affine varieties.

In this section we shall first give a simple direct treatment of the problem
above, and then show how to use Macaulay2's general tool to solve the problem.
We first clear the earlier meaning of x to make it into a subscripted variable

+------------------+
|i44 : x = global x|
|                  |
|o44 = x           |
|                  |
|o44 : Symbol      |
+------------------+

and then set

+-----------------------+
|i45 : R = KK[x_0..x_3] |
|                       |
|o45 = R                |
|                       |
|o45 : PolynomialRing   |
+-----------------------+

the homogeneous coordinate ring of $\PP^3$ and

+----------------------------------------------------+
|i46 : M = map(R^2, 3, (i,j)->x_(i+j))               |
|                                                    |
|o46 = | x_0 x_1 x_2 |                               |
|      | x_1 x_2 x_3 |                               |
|                                                    |
|              2      3                              |
|o46 : Matrix R  <-- R                               |
+----------------------------------------------------+
|i47 : I = gens minors(2,M)                          |
|                                                    |
|o47 = | -x_1^2+x_0x_2 -x_1x_2+x_0x_3 -x_2^2+x_1x_3 ||
|                                                    |
|              1      3                              |
|o47 : Matrix R  <-- R                               |
+----------------------------------------------------+

a matrix whose image is the ideal of the twisted cubic. As projection center we
take the point defined by

+---------------------------------------+
|i48 : pideal = ideal(x_0+x_3, x_1, x_2)|
|                                       |
|o48 = ideal (x  + x , x , x )          |
|              0    3   1   2           |
|                                       |
|o48 : Ideal of R                       |
+---------------------------------------+

To find the image we must intersect the ideal $I$ with the subring generated by
the generators of pideal.  We make a change of variable so that these
generators become the last three variables in the ring; that is, we write the
ring as $KK[y_0..y_3]$ where $$y_0 = x_0, y_1 = x_1, y_2 = x_2, y_3 = x_0+x_3$$
and thus $x_3 = y_3-y_0$, etc. We want the new ring to have an ``elimination
order'' for the first variable.

+--------------------------------------------------+
|i49 : y = global y                                |
|                                                  |
|o49 = y                                           |
|                                                  |
|o49 : Symbol                                      |
+--------------------------------------------------+
|i50 : S = KK[y_0..y_3,MonomialOrder=> Eliminate 1]|
|                                                  |
|o50 = S                                           |
|                                                  |
|o50 : PolynomialRing                              |
+--------------------------------------------------+

Here is one way to make the substitution

+----------------------------------------------------------------+
|i51 : I1 = substitute(I, matrix{{y_0,y_1,y_2,y_3-y_0}})         |
|                                                                |
|o51 = | y_0y_2-y_1^2 -y_0^2+y_0y_3-y_1y_2 -y_0y_1-y_2^2+y_1y_3 ||
|                                                                |
|              1      3                                          |
|o51 : Matrix S  <-- S                                           |
+----------------------------------------------------------------+

The elimination of 1 variable from the matrix of Gröbner basis elements
proceeds as follows:

+---------------------------------------+
|i52 : J = selectInSubring(1,gens gb I1)|
|                                       |
|o52 = | y_1^3+y_2^3-y_1y_2y_3 |        |
|                                       |
|              1      1                 |
|o52 : Matrix S  <-- S                  |
+---------------------------------------+

and gives (a matrix with element) the cubic equation of a rational curve with
one double point in the plane. However, we are still in a ring with 4
variables, so if we really want a plane curve (and not the cone over one) we
must move to yet another ring:

+-------------------------------+
|i53 : S1 = KK[y_1..y_3]        |
|                               |
|o53 = S1                       |
|                               |
|o53 : PolynomialRing           |
+-------------------------------+
|i54 : J1 = substitute(J, S1)   |
|                               |
|o54 = | y_1^3+y_2^3-y_1y_2y_3 ||
|                               |
|               1       1       |
|o54 : Matrix S1  <-- S1        |
+-------------------------------+

This time we didn't have to give so much detail to the substitute command
because of the coincidence of the names of the variables.

Having shown the primitive method, we now show a much more flexible and
transparent one:  we set up a ring map from the polynomial ring in $3$
variables (representing the plane) to $R/I$, taking the variables $y$ to the
three linear forms that define the projection center.  Then we just take the
kernel of this map!  (``Under the hood'', Macaulay2 is doing a more refined
version of the same computation as before.) Here is the ring map

+----------------------------------------------------------+
|i55 : Rbar = R/(ideal I)                                  |
|                                                          |
|o55 = Rbar                                                |
|                                                          |
|o55 : QuotientRing                                        |
+----------------------------------------------------------+
|i56 : f = map(Rbar, S1, matrix(Rbar,{{x_0+x_3, x_1,x_2}}))|
|                                                          |
|o56 = map (Rbar, S1, {x  + x , x , x })                   |
|                       0    3   1   2                     |
|                                                          |
|o56 : RingMap Rbar <-- S1                                 |
+----------------------------------------------------------+

and the desired ideal

+-----------------------------+
|i57 : J1 = ker f             |
|                             |
|             3             3 |
|o57 = ideal(y  - y y y  + y )|
|             2    1 2 3    3 |
|                             |
|o57 : Ideal of S1            |
+-----------------------------+

E. Quotients and saturation

Another typical application of Gröbner bases and syzygies is to the computation
of ideal quotients and saturations.  Again we give an easy example that we can
treat directly, and then introduce the tool used in Macaulay2 to treat the
general case.

If $I$ and $J$ are ideals in a ring $R$, we define $(I:J)$, the ideal quotient,
by $$(I:J) = \{f \in R \mid fJ \subset I\}.$$

In our first examples we consider the case where $J$ is generated by a single
element $g$. This arises in practice, for example, in the problem of
homogenizing an ideal.  Suppose we consider the affine space curve parametrized
by $t \mapsto{} (t,t^2,t^3)$.  The ideal of polynomials vanishing on the curve
is easily seen to be $(b-a^2, c-a^3)$ (where we have taken $a,b,c$ as the
coordinates of affine space). To find the projective closure of the curve in
$\PP^3$, we must homogenize these equations with respect to a new variable d,
getting $db-a^2, d^2c-a^3$.  But these forms do NOT define the projective
closure! In general, homogenizing the generators of the ideal $I$ of an affine
variety one gets an ideal $I_1$ that defines the projective closure UP TO a
component supported on the hyperplane at infinity (the hyperplane $d=0$).  To
see the ideal of the closure we must remove any such components, for example by
replacing $I_1$ by the union $I_2$ of all the ideals $(I_1:d^n)$, where $n$
ranges over positive integers.  This is not so hard as it seems: First of all,
we can successively compute the increasing sequence of ideals $(I_1:d),
(I_1:d^2), \ldots $ until we get two that are the same; all succeeding ones
will be equal, so we have found the union. A second method involves a special
property of the reverse lex order, and is much more efficient in this case.  We
shall illustrate both. First we set up the example above:

+-------------------------------------+
|i58 : R = KK[a,b,c,d]                |
|                                     |
|o58 = R                              |
|                                     |
|o58 : PolynomialRing                 |
+-------------------------------------+
|i59 : I1 = ideal(d*b-a^2, d^2*c-a^3) |
|                                     |
|                2           3      2 |
|o59 = ideal (- a  + b*d, - a  + c*d )|
|                                     |
|o59 : Ideal of R                     |
+-------------------------------------+

How to compute the ideal quotient: If $I$ is generated by $f_1,\ldots,f_n$, we
see that $s\in (I:g)$ iff there are ring elements $r_i$ such that
$$\sum_{i=1}^{n} r_i f_i + s g = 0. $$ Thus it suffices to compute the kernel
(syzygies) of the $1 \times (n+1)$ matrix $$(f_1, ... ,f_n, g)$$ and collect
the coefficients of $g$, that is, the entries of the last row of a matrix
representing the kernel. Thus in our case we may compute $(I_1:d)$ by
concatenating the matrix for $I_1$ with the single variable $d$

+-------------------------------------+
|i60 : I1aug = (gens I1) | matrix{{d}}|
|                                     |
|o60 = | -a2+bd -a3+cd2 d |           |
|                                     |
|              1      3               |
|o60 : Matrix R  <-- R                |
+-------------------------------------+
|i61 : augrelations = gens ker I1aug  |
|                                     |
|o61 = {2} | -a    d     |            |
|      {3} | 1     0     |            |
|      {1} | ab-cd a2-bd |            |
|                                     |
|              3      2               |
|o61 : Matrix R  <-- R                |
+-------------------------------------+

There are 3 rows (numbered 0,1,2 !) and 2 columns, so to extract the last row
we may do

+-----------------------------------------------+
|i62 : I21 = submatrix(augrelations, {2}, {0,1})|
|                                               |
|o62 = {1} | ab-cd a2-bd |                      |
|                                               |
|              1      2                         |
|o62 : Matrix R  <-- R                          |
+-----------------------------------------------+

But this is not an ``ideal'' properly speaking: first of all, it is a matrix,
not an ideal, and second of all its target is not $R^1$ but $R(-1)$, the free
module of rank 1 with generator in degree 1.  We can fix both of these problems
by

+---------------------------------+
|i63 : I21 = ideal I21            |
|                                 |
|                         2       |
|o63 = ideal (a*b - c*d, a  - b*d)|
|                                 |
|o63 : Ideal of R                 |
+---------------------------------+

This is larger than the original ideal, having two quadratic generators instead
of a quadric and a cubic, so we continue.  Instead of doing the same
computation again, we introduce the built-in command

+-------------------------------------------+
|i64 : I22 = I21 : d                        |
|                                           |
|              2                    2       |
|o64 = ideal (b  - a*c, a*b - c*d, a  - b*d)|
|                                           |
|o64 : Ideal of R                           |
+-------------------------------------------+

which is again larger than I21, having three quadratic generators. Repeating,

+-------------------------------------------+
|i65 : I23 = I22 : d                        |
|                                           |
|              2                    2       |
|o65 = ideal (b  - a*c, a*b - c*d, a  - b*d)|
|                                           |
|o65 : Ideal of R                           |
+-------------------------------------------+

we get another ideal with three quadratic generators.  It must be the same as
I21, but the generators are written differently because of the route taken to
get it, so (being suspicious) we might check with

+-----------------------------+
|i66 : (gens I23) % (gens I22)|
|                             |
|o66 = 0                      |
|                             |
|              1      3       |
|o66 : Matrix R  <-- R        |
+-----------------------------+

which returns 0, showing that I23 is contained in (gives remainder 0 when
divided by) I22.  Thus the homogeneous ideal I2 of the projective closure is
equal to I23 (this is the homogeneous ideal of the twisted cubic, already
encountered above).

A more perspicuous way of approaching the computation of the union of the
$(I:d^n)$, which is called the saturation of $I$ with respect to $d$, and
written $(I:d^\infty)$, is first to compute a reverse lex Gröbner basis.

+---------------------------------+
|i67 : gens gb I1                 |
|                                 |
|o67 = | a2-bd abd-cd2 b2d2-acd2 ||
|                                 |
|              1      3           |
|o67 : Matrix R  <-- R            |
+---------------------------------+

This yields (a2-bd, abd-cd2, b2d2-acd2), meaning $$(a^2-bd, abd-cd^2,
b^2d^2-acd^2).$$ We see that the second generator is divisible by $d$, and the
third is divisible by $d^2$. General theory says that we get the right answer
simply by making these divisions, that is, the saturation is $$(a^2-cd, ab-cd,
b^2-ac),$$ as previously computed.  The same thing can be accomplished in one
line by

+-----------------------------------------+
|i68 : I2 = divideByVariable(gens gb I1,d)|
|                                         |
|o68 = (| a2-bd ab-cd b2-ac |, 2)         |
|                                         |
|o68 : Sequence                           |
+-----------------------------------------+

This saturation may be found directly in Macaulay2:

+-------------------------------------------+
|i69 : saturate(I1, d)                      |
|                                           |
|              2                    2       |
|o69 = ideal (b  - a*c, a*b - c*d, a  - b*d)|
|                                           |
|o69 : Ideal of R                           |
+-------------------------------------------+

Tutorial: Canonical Embeddings of Plane Curves and Gonality
***********************************************************

MATHEMATICAL BACKGROUND

The gonality of a curve is defined to be the smallest degree of a morphism from
the curve to the projective line $\PP^1$. It is known that a curve $C$ of genus
$g$ admits a map to $\PP^1$ of degree at most $[(g+3)/2]$.  Further, if $C$ is
$d$-gonal, then in its canonical embedding $C$ lies on a rational normal scroll
of dimension $d-1$, and the free resolution of the homogeneous coordinate ring
of the scroll is a subcomplex of the free resolution of the homogeneous
coordinate ring of  $C$.  Thus for example the $2$-linear part of that
resolution has length at least $g-d$, and ``Green's Conjecture'' states that if
one computes Clifford index instead of gonality, a slight refinement, then
equality holds. For example, Green's conjecture predicts that the resolution of
the homogeneous coordinate ring of a general curve of genus 7 and gonality 4
is:

     total: 1 10 25 25 10 1
         0: 1 .  .  .  .  .
         1: . 10 16 9  .  .
         2: . .  9  16 10 .
         3: . .  .  .  .  1

(Green's conjecture has actually been proven by Frank Schreyer in this case; in
any case the result that the two-linear part is AT LEAST as long as predicted
in Green's conjecture is easy.)  If a curve can be represented as a plane curve
of degree $e$ with an ordinary multiple point (that is, the branches have
distinct tangents) of multiplicity $m$, then projection from the point defines
a map to $\PP^1$ of degree $e-m$. In this example we will illustrate the
``principle'' that this is often the gonality of the curve by computing the
canonical embedding and its resolution.  To compute the canonical embedding, we
will use ``adjunction'': the canonical series of a plane curve $C$ of degree
$e$ with only ordinary multiple points of degrees $m_i$ as singularities is
obtained as the linear series cut out by plane curves $D$ of degree $e-3$
passing through the nodes with multiplicities $m_i-1$; at a tacnode of
multiplicity 2 the condition is that $D$ passes through the singular point and
is tangent to the tangent line of $C$ at that point.

We will make these computations for three types of plane sextic curves (of
genus seven):

C1 will have 3 ordinary nodes;

C2 will have one ordinary triple point;

C3 will have one tacnode and one ordinary node.

Computation

We take C1 to be a curve of degree $6$ having $3$ ordinary double points:

+------------------------------------------------------+
|i1 : R = ZZ/31991[a,b,c] -- the coordinate ring of P^2|
|                                                      |
|o1 = R                                                |
|                                                      |
|o1 : PolynomialRing                                   |
+------------------------------------------------------+

We define the ideals of the points. We could write

+------------------------------------+
|i2 : ipoint1 = ideal matrix({{a,b}})|
|                                    |
|o2 = ideal (a, b)                   |
|                                    |
|o2 : Ideal of R                     |
+------------------------------------+

but the following shortcut is faster!

+-------------------------+
|i3 : ipoint1 = ideal(a,b)|
|                         |
|o3 = ideal (a, b)        |
|                         |
|o3 : Ideal of R          |
+-------------------------+
|i4 : ipoint2 = ideal(a,c)|
|                         |
|o4 = ideal (a, c)        |
|                         |
|o4 : Ideal of R          |
+-------------------------+
|i5 : ipoint3 = ideal(b,c)|
|                         |
|o5 = ideal (b, c)        |
|                         |
|o5 : Ideal of R          |
+-------------------------+

For a curve to be double at the $3$ points, its equation must lie in the ideal

+------------------------------------+
|i6 : icurves1 = intersect(          |
|                    ipoint1^2,      |
|                    ipoint2^2,      |
|                    ipoint3^2       |
|                )                   |
|                                    |
|                    2 2   2 2   2 2 |
|o6 = ideal (a*b*c, b c , a c , a b )|
|                                    |
|o6 : Ideal of R                     |
+------------------------------------+

The matrix with the generators of icurves1 as its entries is obtained by

+-----------------------------+
|i7 : Icurves1 = gens icurves1|
|                             |
|o7 = | abc b2c2 a2c2 a2b2 |  |
|                             |
|             1      4        |
|o7 : Matrix R  <-- R         |
+-----------------------------+

We find the equation F1 of a general curve of degree $6$ with these double
points by composing a random matrix of forms having the correct degree with the
matrix of generators of  icurves1.

+-----------------------------------------------------------------------------+
|i8 : F1 = Icurves1 * random(source Icurves1, R^{-6})                         |
|                                                                             |
|o8 = | -8239a4b2-6191a3b3+5864a2b4+107a4bc-5092a3b2c-4302a2b3c+8570ab4c-     |
|     ------------------------------------------------------------------------|
|     7452a4c2-487a3bc2+12260a2b2c2-12679ab3c2-11938b4c2-13496a3c3+4964a2bc3- |
|     ------------------------------------------------------------------------|
|     11182ab2c3+5026b3c3-7204a2c4-10468abc4+9534b2c4 |                       |
|                                                                             |
|             1      1                                                        |
|o8 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i9 : betti F1                                                                |
|                                                                             |
|            0 1                                                              |
|o9 = total: 1 1                                                              |
|         0: 1 .                                                              |
|         1: . .                                                              |
|         2: . .                                                              |
|         3: . .                                                              |
|         4: . .                                                              |
|         5: . 1                                                              |
|                                                                             |
|o9 : BettiTally                                                              |
+-----------------------------------------------------------------------------+

We now look for the equation F2 of C2, a curve with an ordinary triple point at
point1.  It must lie in the cube of the ideal ipoint1.

+-----------------------------------------------------------------------------+
|i10 : Icurves2 = gens (ipoint1^3)                                            |
|                                                                             |
|o10 = | a3 a2b ab2 b3 |                                                      |
|                                                                             |
|              1      4                                                       |
|o10 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i11 : F2 = Icurves2 * random(source Icurves2, R^{-6})                        |
|                                                                             |
|o11 = | 7256a6-6606a5b+126a4b2-6872a3b3+9483a2b4-12497ab5-13880b6+6230a5c+   |
|      -----------------------------------------------------------------------|
|      15973a4bc-12234a3b2c-15204a2b3c-809ab4c-982b5c-3984a4c2+6941a3bc2-     |
|      -----------------------------------------------------------------------|
|      8730a2b2c2+14943ab3c2+8971b4c2-11509a3c3+5679a2bc3+8922ab2c3-14153b3c3 |
|      -----------------------------------------------------------------------|
|      |                                                                      |
|                                                                             |
|              1      1                                                       |
|o11 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i12 : betti F2                                                               |
|                                                                             |
|             0 1                                                             |
|o12 = total: 1 1                                                             |
|          0: 1 .                                                             |
|          1: . .                                                             |
|          2: . .                                                             |
|          3: . .                                                             |
|          4: . .                                                             |
|          5: . 1                                                             |
|                                                                             |
|o12 : BettiTally                                                             |
+-----------------------------------------------------------------------------+

Finally, the equation of a curve with a tacnode at $a=b=0$ having tangent line
$a-b=0$  there must lie in the ideal

+-----------------------------------------------------+
|i13 : i = ideal((a-b)^2) + (ipoint1^4)               |
|                                                     |
|              2           2   4   3    2 2     3   4 |
|o13 = ideal (a  - 2a*b + b , a , a b, a b , a*b , b )|
|                                                     |
|o13 : Ideal of R                                     |
+-----------------------------------------------------+

and adding a node at point3 we get

+-------------------------------------------------------------------------+
|i14 : icurves3 = intersect(i, ipoint3^2)                                 |
|                                                                         |
|              2 2         2    2 2   2          2     3    4     3   2 2 |
|o14 = ideal (a c  - 2a*b*c  + b c , a b*c - 2a*b c + b c, b , a*b , a b )|
|                                                                         |
|o14 : Ideal of R                                                         |
+-------------------------------------------------------------------------+
|i15 : Icurves3 = gens icurves3                                           |
|                                                                         |
|o15 = | a2c2-2abc2+b2c2 a2bc-2ab2c+b3c b4 ab3 a2b2 |                     |
|                                                                         |
|              1      5                                                   |
|o15 : Matrix R  <-- R                                                    |
+-------------------------------------------------------------------------+

so

+-----------------------------------------------------------------------------+
|i16 : F3 = Icurves3 * random(source Icurves3, R^{-6})                        |
|                                                                             |
|o16 = | -6615a4b2-2888a3b3-62a2b4-10259ab5-11423b6-6441a4bc+11646a3b2c-      |
|      -----------------------------------------------------------------------|
|      2688a2b3c+7542ab4c-10870b5c-2990a4c2-13464a3bc2-15258a2b2c2-8437ab3c2- |
|      -----------------------------------------------------------------------|
|      8369b4c2-10509a3c3+6993a2bc3-14450ab2c3-14025b3c3+1206a2c4-2412abc4+   |
|      -----------------------------------------------------------------------|
|      1206b2c4 |                                                             |
|                                                                             |
|              1      1                                                       |
|o16 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i17 : betti F3                                                               |
|                                                                             |
|             0 1                                                             |
|o17 = total: 1 1                                                             |
|          0: 1 .                                                             |
|          1: . .                                                             |
|          2: . .                                                             |
|          3: . .                                                             |
|          4: . .                                                             |
|          5: . 1                                                             |
|                                                                             |
|o17 : BettiTally                                                             |
+-----------------------------------------------------------------------------+

It is evident from the discussion above that C1 and C3 have gonality $\leq 5$
(indeed, every curve of genus $7$ has gonality $\leq 5$) and that C2 has
gonality $\leq 4$.  We can establish lower bounds for the gonalities by looking
at the canonical embeddings. The canonical series of C1 is cut out by

+---------------------------------------------------------+
|i18 : can1 = basis(3, intersect(ipoint1,ipoint2,ipoint3))|
|                                                         |
|o18 = {2} | b c 0 0 0 0 0 |                              |
|      {2} | 0 0 a c 0 0 0 |                              |
|      {2} | 0 0 0 0 a b c |                              |
|                                                         |
|o18 : Matrix                                             |
+---------------------------------------------------------+

Some explanation regarding the basis command is needed here.  can1 is a matrix
whose target is the ideal of the intersection of these three points:

+-------------------------------+
|i19 : target can1              |
|                               |
|o19 = image | bc ac ab |       |
|                               |
|                              1|
|o19 : R-module, submodule of R |
+-------------------------------+

and whose source is a free module over the coefficient ring:

+-----------------------------------+
|i20 : source can1                  |
|                                   |
|       7                           |
|o20 = R                            |
|                                   |
|o20 : R-module, free, degrees {7:3}|
+-----------------------------------+

For our purposes, there are two problems with this. The first is that we want a
map where both the source and target have the base ring $R$.  This can be
accomplished by tensoring with $R$:

+---------------------------+
|i21 : can1 = can1 ** R     |
|                           |
|o21 = {2} | b c 0 0 0 0 0 ||
|      {2} | 0 0 a c 0 0 0 ||
|      {2} | 0 0 0 0 a b c ||
|                           |
|o21 : Matrix               |
+---------------------------+

The second problem is that the image of a basis element is not obviously in the
ideal: it is represented in terms of the generators of $I$.  This can be
alleviated by applying super: this takes a homomorphism $f : M \rightarrow{}
N$, where $N$ is a submodule of a quotient module $F/I$, and returns the
homomorphism $f : M \rightarrow{} F/I$.

+-------------------------------------+
|i22 : can1 = super can1              |
|                                     |
|o22 = | b2c bc2 a2c ac2 a2b ab2 abc ||
|                                     |
|              1      7               |
|o22 : Matrix R  <-- R                |
+-------------------------------------+

similarly, for C2 and C3:

+-----------------------------------------------------------------+
|i23 : can2 = basis(3, ipoint1^2)                                 |
|                                                                 |
|o23 = {2} | a b c 0 0 0 0 |                                      |
|      {2} | 0 0 0 b c 0 0 |                                      |
|      {2} | 0 0 0 0 0 b c |                                      |
|                                                                 |
|o23 : Matrix                                                     |
+-----------------------------------------------------------------+
|i24 : can2 = super (can2 ** R)                                   |
|                                                                 |
|o24 = | a3 a2b a2c ab2 abc b3 b2c |                              |
|                                                                 |
|              1      7                                           |
|o24 : Matrix R  <-- R                                            |
+-----------------------------------------------------------------+
|i25 : can3 = basis(3, intersect(ideal(a-b) + ipoint1^2, ipoint3))|
|                                                                 |
|o25 = {2} | a c 0 0 0 0 0 |                                      |
|      {2} | 0 0 b c 0 0 0 |                                      |
|      {2} | 0 0 0 0 a b c |                                      |
|                                                                 |
|o25 : Matrix                                                     |
+-----------------------------------------------------------------+

+--------------------------------------------+
|i26 : can3 = super (can3 ** R)              |
|                                            |
|o26 = | a2c-abc ac2-bc2 b3 b2c a2b ab2 abc ||
|                                            |
|              1      7                      |
|o26 : Matrix R  <-- R                       |
+--------------------------------------------+

These should all give embeddings of the curves in $\PP^6$, so we expect them to
be linear series of vector space dimension $7$. Here's how to check:

+-----------------+
|i27 : betti  can1|
|                 |
|             0 1 |
|o27 = total: 1 7 |
|          0: 1 . |
|          1: . . |
|          2: . 7 |
|                 |
|o27 : BettiTally |
+-----------------+
|i28 : betti  can2|
|                 |
|             0 1 |
|o28 = total: 1 7 |
|          0: 1 . |
|          1: . . |
|          2: . 7 |
|                 |
|o28 : BettiTally |
+-----------------+
|i29 : betti  can3|
|                 |
|             0 1 |
|o29 = total: 1 7 |
|          0: 1 . |
|          1: . . |
|          2: . 7 |
|                 |
|o29 : BettiTally |
+-----------------+

To compute the homogeneous coordinate rings of the canonical curves, we must
find the algebraic relations among the generators of cani modulo Fi.

The coordinate ring of $\PP^6$

+---------------------------------------+
|i30 : S = (coefficientRing R)[x_0..x_6]|
|                                       |
|o30 = S                                |
|                                       |
|o30 : PolynomialRing                   |
+---------------------------------------+

Find the canonical ideal IC1 of C1, that is, the kernel of the map $S
\rightarrow{} R/(F1)$ defined by the canonical series.

+-----------------------------------------------------------------------------+
|i31 : T1 = R/ideal F1                                                        |
|                                                                             |
|o31 = T1                                                                     |
|                                                                             |
|o31 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i32 : f1 = map(T1,S,substitute(can1, T1))                                    |
|                                                                             |
|                    2      2   2      2   2      2                           |
|o32 = map (T1, S, {b c, b*c , a c, a*c , a b, a*b , a*b*c})                  |
|                                                                             |
|o32 : RingMap T1 <-- S                                                       |
+-----------------------------------------------------------------------------+
|i33 : IC1 = mingens ker f1                                                   |
|                                                                             |
|o33 = | x_3x_5-x_6^2 x_2x_5-x_4x_6 x_1x_5-x_0x_6 x_3x_4-x_2x_6 x_1x_4-x_6^2  |
|      -----------------------------------------------------------------------|
|      x_0x_4-x_5x_6 x_0x_3-x_1x_6 x_1x_2-x_3x_6 x_0x_2-x_6^2                 |
|      -----------------------------------------------------------------------|
|      x_0^2-5644x_0x_1+13532x_1^2-5584x_2^2-9046x_1x_3+5977x_2x_3-14379x_3^2+|
|      -----------------------------------------------------------------------|
|      8460x_2x_4-11600x_4^2-15747x_0x_5-9928x_4x_5+9786x_5^2+13767x_0x_6-    |
|      -----------------------------------------------------------------------|
|      12878x_1x_6+11724x_2x_6-11443x_3x_6-4657x_4x_6-11260x_5x_6+10509x_6^2 ||
|                                                                             |
|              1      10                                                      |
|o33 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+

and similarly for C2, C3

+-----------------------------------------------------------------------------+
|i34 : T2 = R/ideal F2                                                        |
|                                                                             |
|o34 = T2                                                                     |
|                                                                             |
|o34 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i35 : f2 = map(T2,S,substitute(can2, T2))                                    |
|                                                                             |
|                    3   2    2      2          3   2                         |
|o35 = map (T2, S, {a , a b, a c, a*b , a*b*c, b , b c})                      |
|                                                                             |
|o35 : RingMap T2 <-- S                                                       |
+-----------------------------------------------------------------------------+
|i36 : IC2 = mingens ker f2                                                   |
|                                                                             |
|o36 = | x_4x_5-x_3x_6 x_2x_5-x_1x_6 x_4^2-x_2x_6 x_3x_4-x_1x_6 x_1x_4-x_0x_6 |
|      -----------------------------------------------------------------------|
|      x_3^2-x_1x_5 x_2x_3-x_0x_6 x_1x_3-x_0x_5 x_1x_2-x_0x_4 x_1^2-x_0x_3    |
|      -----------------------------------------------------------------------|
|      x_0^2x_5-8563x_0x_1x_5-12389x_0x_3x_5+14037x_0x_5^2+8268x_1x_5^2+11845x|
|      -----------------------------------------------------------------------|
|      _3x_5^2-2224x_5^3+9480x_0x_1x_6+7925x_0x_3x_6+6313x_0x_4x_6-12686x_2x_ |
|      -----------------------------------------------------------------------|
|      4x_6+11629x_0x_5x_6+2026x_1x_5x_6+11247x_3x_5x_6+11754x_5^2x_6+14978x_ |
|      -----------------------------------------------------------------------|
|      0x_6^2+3764x_1x_6^2+15163x_2x_6^2-6069x_3x_6^2+3255x_4x_6^2+10878x_5x_6|
|      -----------------------------------------------------------------------|
|      ^2-12704x_6^3 x_0^2x_3-13986x_0x_1x_5+9186x_0x_3x_5-15079x_0x_5^2+     |
|      -----------------------------------------------------------------------|
|      14646x_1x_5^2+15041x_3x_5^2-9467x_5^3+9480x_0^2x_6-7993x_0x_1x_6+6313x_|
|      -----------------------------------------------------------------------|
|      0x_2x_6-12686x_2^2x_6-11498x_0x_3x_6+8407x_0x_4x_6-5610x_2x_4x_6-6830x_|
|      -----------------------------------------------------------------------|
|      0x_5x_6-11228x_1x_5x_6-5086x_3x_5x_6+5816x_5^2x_6+8459x_0x_6^2+10126x_ |
|      -----------------------------------------------------------------------|
|      1x_6^2-7445x_2x_6^2-4585x_3x_6^2-4300x_4x_6^2-9478x_5x_6^2-14952x_6^3  |
|      -----------------------------------------------------------------------|
|      x_0^2x_1+9480x_0^2x_4+6313x_0x_2x_4-12686x_2^2x_4-10619x_0x_1x_5+7614x_|
|      -----------------------------------------------------------------------|
|      0x_3x_5+7361x_0x_5^2+3824x_1x_5^2+5305x_3x_5^2-9612x_5^3-7993x_0^2x_6+ |
|      -----------------------------------------------------------------------|
|      5078x_0x_1x_6+8407x_0x_2x_6-5610x_2^2x_6+15396x_0x_3x_6+6917x_0x_4x_6- |
|      -----------------------------------------------------------------------|
|      11755x_2x_4x_6-10278x_0x_5x_6-13476x_1x_5x_6+6611x_3x_5x_6-10305x_5^2x_|
|      -----------------------------------------------------------------------|
|      6+15366x_0x_6^2+13524x_1x_6^2-2921x_2x_6^2+13602x_3x_6^2-13715x_4x_6^2-|
|      -----------------------------------------------------------------------|
|      9488x_5x_6^2-130x_6^3 x_0^3+9480x_0^2x_2+6313x_0x_2^2-12686x_2^3-7993x_|
|      -----------------------------------------------------------------------|
|      0^2x_4+8407x_0x_2x_4-5610x_2^2x_4-4461x_0x_1x_5-4438x_0x_3x_5-15333x_0x|
|      -----------------------------------------------------------------------|
|      _5^2-12098x_1x_5^2+15822x_3x_5^2-7298x_5^3+5078x_0^2x_6+7839x_0x_1x_6+ |
|      -----------------------------------------------------------------------|
|      6917x_0x_2x_6-11755x_2^2x_6+8967x_0x_3x_6-23x_0x_4x_6-1454x_2x_4x_6-   |
|      -----------------------------------------------------------------------|
|      10385x_0x_5x_6-9238x_1x_5x_6-815x_3x_5x_6-13156x_5^2x_6+5654x_0x_6^2-  |
|      -----------------------------------------------------------------------|
|      5232x_1x_6^2-8521x_2x_6^2+5666x_3x_6^2+14435x_4x_6^2-6019x_5x_6^2+2271x|
|      -----------------------------------------------------------------------|
|      _6^3 |                                                                 |
|                                                                             |
|              1      14                                                      |
|o36 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+
|i37 : T3 = R/ideal F3                                                        |
|                                                                             |
|o37 = T3                                                                     |
|                                                                             |
|o37 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i38 : f3 = map(T3,S,substitute(can3, T3))                                    |
|                                                                             |
|                    2              2      2   3   2    2      2              |
|o38 = map (T3, S, {a c - a*b*c, a*c  - b*c , b , b c, a b, a*b , a*b*c})     |
|                                                                             |
|o38 : RingMap T3 <-- S                                                       |
+-----------------------------------------------------------------------------+
|i39 : IC3 = mingens ker f3                                                   |
|                                                                             |
|o39 = | x_3x_5-x_2x_6 x_1x_5+x_3x_6-x_6^2 x_0x_5-x_4x_6+x_5x_6 x_3x_4-x_5x_6 |
|      -----------------------------------------------------------------------|
|      x_2x_4-x_5^2 x_1x_4-x_0x_6 x_0x_3+x_3x_6-x_6^2 x_1x_2+x_3^2-x_3x_6     |
|      -----------------------------------------------------------------------|
|      x_0x_2+x_2x_6-x_5x_6 x_0^2+3438x_0x_1-3253x_1^2+11527x_2^2-3054x_1x_3+ |
|      -----------------------------------------------------------------------|
|      10168x_2x_3-8011x_3^2+7267x_0x_4+11397x_4^2-13895x_2x_5-10142x_4x_5+   |
|      -----------------------------------------------------------------------|
|      9929x_5^2-4744x_0x_6+3054x_1x_6+14035x_2x_6-1249x_3x_6+12142x_4x_6-    |
|      -----------------------------------------------------------------------|
|      11212x_5x_6+3306x_6^2 |                                                |
|                                                                             |
|              1      10                                                      |
|o39 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+

We now find the $2$-linear part of the free resolution of IC1 and its betti
numbers.

+-----------------------------------------------------+
|i40 : IC1res = res(coker IC1)                        |
|                                                     |
|       1      10      25      25      10      1      |
|o40 = S  <-- S   <-- S   <-- S   <-- S   <-- S  <-- 0|
|                                                     |
|      0      1       2       3       4       5      6|
|                                                     |
|o40 : ChainComplex                                   |
+-----------------------------------------------------+
|i41 : betti  IC1res                                  |
|                                                     |
|             0  1  2  3  4 5                         |
|o41 = total: 1 10 25 25 10 1                         |
|          0: 1  .  .  .  . .                         |
|          1: . 10 16  9  . .                         |
|          2: .  .  9 16 10 .                         |
|          3: .  .  .  .  . 1                         |
|                                                     |
|o41 : BettiTally                                     |
+-----------------------------------------------------+

From this computation, and the easy implication of Green's conjecture explained
above, we see that the gonality of C1 is exactly 4, the gonality of the linear
series obtained by projection from any one of the three double points. We now
do the same for IC2 and IC3:

+-----------------------------------------------------+
|i42 : IC2res = res(coker IC2)                        |
|                                                     |
|       1      14      35      35      14      1      |
|o42 = S  <-- S   <-- S   <-- S   <-- S   <-- S  <-- 0|
|                                                     |
|      0      1       2       3       4       5      6|
|                                                     |
|o42 : ChainComplex                                   |
+-----------------------------------------------------+
|i43 : betti  IC2res                                  |
|                                                     |
|             0  1  2  3  4 5                         |
|o43 = total: 1 14 35 35 14 1                         |
|          0: 1  .  .  .  . .                         |
|          1: . 10 20 15  4 .                         |
|          2: .  4 15 20 10 .                         |
|          3: .  .  .  .  . 1                         |
|                                                     |
|o43 : BettiTally                                     |
+-----------------------------------------------------+
|i44 : IC3res = res(coker IC3)                        |
|                                                     |
|       1      10      25      25      10      1      |
|o44 = S  <-- S   <-- S   <-- S   <-- S   <-- S  <-- 0|
|                                                     |
|      0      1       2       3       4       5      6|
|                                                     |
|o44 : ChainComplex                                   |
+-----------------------------------------------------+
|i45 : betti  IC3res                                  |
|                                                     |
|             0  1  2  3  4 5                         |
|o45 = total: 1 10 25 25 10 1                         |
|          0: 1  .  .  .  . .                         |
|          1: . 10 16  9  . .                         |
|          2: .  .  9 16 10 .                         |
|          3: .  .  .  .  . 1                         |
|                                                     |
|o45 : BettiTally                                     |
+-----------------------------------------------------+

and we find that in the tacnodal case the gonality is still 4, while in the
triple point case the gonality is 3. Note that we could have made the
computation faster, as in the following example.  In these cases the resolution
is so fast that the speedup is not noticeable, but in larger cases it would be
worthwhile. First clear the info computed in IC1

+-----------------------------------------------------------------------------+
|i46 : IC1 = matrix entries IC1                                               |
|                                                                             |
|o46 = | x_3x_5-x_6^2 x_2x_5-x_4x_6 x_1x_5-x_0x_6 x_3x_4-x_2x_6 x_1x_4-x_6^2  |
|      -----------------------------------------------------------------------|
|      x_0x_4-x_5x_6 x_0x_3-x_1x_6 x_1x_2-x_3x_6 x_0x_2-x_6^2                 |
|      -----------------------------------------------------------------------|
|      x_0^2-5644x_0x_1+13532x_1^2-5584x_2^2-9046x_1x_3+5977x_2x_3-14379x_3^2+|
|      -----------------------------------------------------------------------|
|      8460x_2x_4-11600x_4^2-15747x_0x_5-9928x_4x_5+9786x_5^2+13767x_0x_6-    |
|      -----------------------------------------------------------------------|
|      12878x_1x_6+11724x_2x_6-11443x_3x_6-4657x_4x_6-11260x_5x_6+10509x_6^2 ||
|                                                                             |
|              1      10                                                      |
|o46 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+

Now redo the resolution, this time bounding the degree to which the computation
is carried.

+-------------------------------------------------+
|i47 : IC1res = res(coker IC1, DegreeLimit => {1})|
|                                                 |
|       1      10      16      9                  |
|o47 = S  <-- S   <-- S   <-- S  <-- 0            |
|                                                 |
|      0      1       2       3      4            |
|                                                 |
|o47 : ChainComplex                               |
+-------------------------------------------------+
|i48 : betti IC1res                               |
|                                                 |
|             0  1  2 3                           |
|o48 = total: 1 10 16 9                           |
|          0: 1  .  . .                           |
|          1: . 10 16 9                           |
|                                                 |
|o48 : BettiTally                                 |
+-------------------------------------------------+

Instead of computing the canonical model of C1 directly, we could have treated
the structure sheaf of C1 as a sheaf on the projective plane, and compute its
push-forward under the map to $\PP^6$ given by can1 (the image of the plane
under this map is a Del Pezzo surface on which the canonical curve lies.) This
is done as follows:

+-----------------------------------------------------------------------------+
|i49 : ff1 = map(R,S,can1)                                                    |
|                                                                             |
|                   2      2   2      2   2      2                            |
|o49 = map (R, S, {b c, b*c , a c, a*c , a b, a*b , a*b*c})                   |
|                                                                             |
|o49 : RingMap R <-- S                                                        |
+-----------------------------------------------------------------------------+
|i50 : G = map(coker F1,ff1)                                                  |
|                                                                             |
|o50 = | 1 |                                                                  |
|                                                                             |
|o50 : Matrix                                                                 |
+-----------------------------------------------------------------------------+
|i51 : trim coimage G                                                         |
|                                                                             |
|o51 = cokernel | x_3x_5-x_6^2 x_2x_5-x_4x_6 x_1x_5-x_0x_6 x_3x_4-x_2x_6      |
|                                                                             |
|                             1                                               |
|o51 : S-module, quotient of S                                                |
|-----------------------------------------------------------------------------|
|x_1x_4-x_6^2 x_0x_4-x_5x_6 x_0x_3-x_1x_6 x_1x_2-x_3x_6 x_0x_2-x_6^2          |
|-----------------------------------------------------------------------------|
|x_0^2-5644x_0x_1+13532x_1^2-5584x_2^2-9046x_1x_3+5977x_2x_3-14379x_3^2+8460x_|
|-----------------------------------------------------------------------------|
|2x_4-11600x_4^2-15747x_0x_5-9928x_4x_5+9786x_5^2+13767x_0x_6-12878x_1x_6+    |
|-----------------------------------------------------------------------------|
|11724x_2x_6-11443x_3x_6-4657x_4x_6-11260x_5x_6+10509x_6^2 |                  |
+-----------------------------------------------------------------------------+

Tutorial: Fano varieties
************************

Given a variety $X$ in projective $r$-space $\PP^r$, the Fano scheme
$Fano_k(X)$ is the natural parameter space for the linear $k$-planes lying on
$X$.  In this tutorial we explore the methods for computing it. The tutorial is
in three parts

A. The twenty-seven lines

B. General methods

C. Surfaces of degree $4$ in $\PP^5$

In section A, we treat by hand the Fano variety of lines on a nonsingular cubic
surface in $\PP^3$, and find that there are indeed $27$ lines lying on the
surface.

In section B, we explain a general purpose function, written to compute Fano
schemes.

There are (up to linear transformations) just $3$ nondegenerate smooth surfaces
of degree $4$ in $\PP^5$: the Veronese embedding of $\PP^2$ and the rational
normal scrolls $S(1,3)$ and $S(2,2)$.  Can they be distinguished by their Fano
varieties of lines? To find out, read section C!

A. Lines on the nonsingular cubic in $\PP^3$

First make the homogeneous coordinate ring of the ambient projective $3$-space

+--------------------------+
|i1 : R = ZZ/32003[a,b,c,d]|
|                          |
|o1 = R                    |
|                          |
|o1 : PolynomialRing       |
+--------------------------+

and the ideal of a nonsingular cubic

+-------------------------------+
|i2 : X = ideal(a^3+b^3+c^3+d^3)|
|                               |
|            3    3    3    3   |
|o2 = ideal(a  + b  + c  + d )  |
|                               |
|o2 : Ideal of R                |
+-------------------------------+

We make a parametrized indeterminate line in our projective space, adding
parameters $s,t$ for the line and two points $p_0..p_3$ and $q_0..q_3$
representing the points 0 and infinity on the line.

+-----------------------------------+
|i3 : KK = coefficientRing R        |
|                                   |
|o3 = KK                            |
|                                   |
|o3 : QuotientRing                  |
+-----------------------------------+
|i4 : S = KK [s,t,p_0..p_3,q_0..q_3]|
|                                   |
|o4 = S                             |
|                                   |
|o4 : PolynomialRing                |
+-----------------------------------+

Then we make a map $F$ from $R$ to the new ring sending the variables to the
coordinates of the general point on the line

+---------------------------------------------------------------------+
|i5 : F = map(S,R,                                                    |
|            s*matrix{{p_0..p_3}} +                                   |
|            t*matrix{{q_0..q_3}}                                     |
|            )                                                        |
|                                                                     |
|o5 = map (S, R, {s*p  + t*q , s*p  + t*q , s*p  + t*q , s*p  + t*q })|
|                    0      0     1      1     2      2     3      3  |
|                                                                     |
|o5 : RingMap S <-- R                                                 |
+---------------------------------------------------------------------+

We now apply $F$ to the ideal of $X$

+-----------------------------------------------------------------------------+
|i6 : FX = F X                                                                |
|                                                                             |
|            3 3    3 3    3 3    3 3     2   2         2   2    3 3          |
|o6 = ideal(s p  + s p  + s p  + s p  + 3s t*p q  + 3s*t p q  + t q  +        |
|              0      1      2      3         0 0         0 0      0          |
|     ------------------------------------------------------------------------|
|       2   2         2   2    3 3     2   2         2   2    3 3     2   2   |
|     3s t*p q  + 3s*t p q  + t q  + 3s t*p q  + 3s*t p q  + t q  + 3s t*p q  |
|           1 1         1 1      1         2 2         2 2      2         3 3 |
|     ------------------------------------------------------------------------|
|           2   2    3 3                                                      |
|     + 3s*t p q  + t q )                                                     |
|             3 3      3                                                      |
|                                                                             |
|o6 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+

and the condition we want becomes the condition that FX vanishes identically in
$s,t$. The following line produces the coefficients:

+---------------------------------------------------------+
|i7 : cFX = last coefficients(gens FX, Variables => {s,t})|
|                                                         |
|o7 = {3} | p_0^3+p_1^3+p_2^3+p_3^3                 |     |
|     {3} | 3p_0^2q_0+3p_1^2q_1+3p_2^2q_2+3p_3^2q_3 |     |
|     {3} | 3p_0q_0^2+3p_1q_1^2+3p_2q_2^2+3p_3q_3^2 |     |
|     {3} | q_0^3+q_1^3+q_2^3+q_3^3                 |     |
|                                                         |
|             4      1                                    |
|o7 : Matrix S  <-- S                                     |
+---------------------------------------------------------+

The interface to the coefficients routine is a bit baroque, and might change in
the future.  For now, the $\{0,1\}$ says to find the coefficients of each
column of the matrix, with respect to the first two variables. The routine
returns a list of two matrices, the second one being the one we need (index 1,
since all indices start at 0 in Macaulay2)

We can get rid of some of the variables of $S$, to ease the computation:

+----------------------------------------------------+
|i8 : S1 = KK[p_0..p_3,q_0..q_3]                     |
|                                                    |
|o8 = S1                                             |
|                                                    |
|o8 : PolynomialRing                                 |
+----------------------------------------------------+
|i9 : cFX = substitute(cFX, S1)                      |
|                                                    |
|o9 = {3} | p_0^3+p_1^3+p_2^3+p_3^3                 ||
|     {3} | 3p_0^2q_0+3p_1^2q_1+3p_2^2q_2+3p_3^2q_3 ||
|     {3} | 3p_0q_0^2+3p_1q_1^2+3p_2q_2^2+3p_3q_3^2 ||
|     {3} | q_0^3+q_1^3+q_2^3+q_3^3                 ||
|                                                    |
|              4       1                             |
|o9 : Matrix S1  <-- S1                              |
+----------------------------------------------------+

The ring we want is the quotient

+--------------------------+
|i10 : S1bar = S1/ideal cFX|
|                          |
|o10 = S1bar               |
|                          |
|o10 : QuotientRing        |
+--------------------------+

Now we want to move to the Grassmannian, so we take a new polynomial ring in 6
variables that will correspond to the minors of the matrix with rows $p_0..p_3$
and $q_0..q_3$,

+--------------------------------------+
|i11 : GR = coefficientRing R[x_0..x_5]|
|                                      |
|o11 = GR                              |
|                                      |
|o11 : PolynomialRing                  |
+--------------------------------------+

We define a map sending the $x_i$ to the minors, regarded as elements of S1bar

+-----------------------------------------------------------------------------+
|i12 : M = substitute(                                                        |
|          exteriorPower(2, matrix{{p_0..p_3},{q_0..q_3}}),                   |
|          S1bar)                                                             |
|                                                                             |
|o12 = | -p_1q_0+p_0q_1 -p_2q_0+p_0q_2 -p_2q_1+p_1q_2 -p_3q_0+p_0q_3          |
|      -----------------------------------------------------------------------|
|      -p_3q_1+p_1q_3 -p_3q_2+p_2q_3 |                                        |
|                                                                             |
|                  1          6                                               |
|o12 : Matrix S1bar  <-- S1bar                                                |
+-----------------------------------------------------------------------------+
|i13 : gr = map (S1bar, GR, M)                                                |
|                                                                             |
|o13 = map (S1bar, GR, {- p q  + p q , - p q  + p q , - p q  + p q , - p q  + |
|                          1 0    0 1     2 0    0 2     2 1    1 2     3 0   |
|                                                                             |
|o13 : RingMap S1bar <-- GR                                                   |
|-----------------------------------------------------------------------------|
|p q , - p q  + p q , - p q  + p q })                                         |
| 0 3     3 1    1 3     3 2    2 3                                           |
+-----------------------------------------------------------------------------+
|i14 : fano = trim ker gr                                                     |
|                                                                             |
|                                                    2      2           2     |
|o14 = ideal (x x  - x x  + x x , x x x , x x x , x x  + x x , x x x , x x  + |
|              2 3    1 4    0 5   3 4 5   1 2 5   0 4    1 5   0 2 4   0 4   |
|      -----------------------------------------------------------------------|
|       2     3    3    3     2      2     2      2   2      2             2  |
|      x x , x  + x  + x , x x  + x x , x x  - x x , x x  + x x , x x x , x x |
|       1 5   3    4    5   1 3    2 4   0 3    2 5   1 3    2 4   0 1 3   0 3|
|      -----------------------------------------------------------------------|
|         2       2      2     2      2   2      2     2      2     3    3    |
|      + x x , x x  + x x , x x  + x x , x x  + x x , x x  - x x , x  + x  -  |
|         2 5   1 2    3 4   0 2    3 5   1 2    3 4   0 2    3 5   1    2    |
|      -----------------------------------------------------------------------|
|       3     2      2   2      2     3    3    3                             |
|      x , x x  - x x , x x  - x x , x  - x  - x )                            |
|       5   0 1    4 5   0 1    4 5   0    2    4                             |
|                                                                             |
|o14 : Ideal of GR                                                            |
+-----------------------------------------------------------------------------+

trim replaces the given set of generators with a minimal set of generators. We
get an ideal representing points:

+----------------+
|i15 : codim fano|
|                |
|o15 = 5         |
+----------------+

and the number of these points -- the number of the corresponding lines - is
27:

+-----------------+
|i16 : degree fano|
|                 |
|o16 = 27         |
+-----------------+

It is interesting to note that the ideal of the Fano scheme that we have
produced is NOT saturated, as the number (25) of cubics it contains is less
than $56 - 27 = 29$:

+-----------------+
|i17 : betti fano |
|                 |
|             0  1|
|o17 = total: 1 20|
|          0: 1  .|
|          1: .  1|
|          2: . 19|
|                 |
|o17 : BettiTally |
+-----------------+

Possible next steps in this computation would be to compute the Jacobian ideal
of Fano to show that we really got 27 distinct lines, etc.

B. General methods

The first step in writing a program is to decide what the program should do,
and it is just as well to write the documentation at this point .

The documentation has the following form.

+--------------------------------------------------------------------+
|i18 : needsPackage "Text"                                           |
|                                                                    |
|o18 = Text                                                          |
|                                                                    |
|o18 : Package                                                       |
+--------------------------------------------------------------------+
|i19 : document {                                                    |
|           Key => Fano2,                                            |
|              TT "Fano2(k,X,GR) or  Fano2(k,X)", " -- computes      |
|              the ideal of a Fano scheme in the Grassmannian.",     |
|              PARA{},                                               |
|              "Given an ideal X representing a projective variety   |
|              in P^r, a positive integer k<r, and optionally a      |
|              ring GR with (exactly) r+1 choose k+1 variables,      |
|              representing the ambient space of the Grassmannian of |
|              k-planes in P^r, this routine returns the ideal in    |
|              GR of the Fano scheme that parametrizes the k-planes  |
|              lying on X. If the optional third argument is not     |
|              present, the routine fabricates its own local ring,   |
|              and returns an ideal over it."                        |
|              };                                                    |
+--------------------------------------------------------------------+

If we take the variety that is the whole of $\PP^r$, we get the Grassmannian.
It is useful to be able to make the ring representing the ambient space of the
Grassmannian beforehand by hand, so the ideals of several Fano varieties can be
compared.  But often we won't need this.  Thus we make the function capable of
accepting this ambient ring as an argument, or of fending for itself if no
ambient ring is given.

+---------------------------------------------------------------------+
|i20 : document {                                                     |
|          Key => Grassmannian2,                                      |
|          TT "Grassmannian2(k,r,R) or                                |
|              Grassmannian2(k,r)",                                   |
|             "-- Given natural numbers k <= r,                       |
|              and optionally a ring R with at least binomial(r+1,k+1)|
|              variables, the routine defines the ideal of the        |
|              Grassmannian of projective k-planes in P^r, using      |
|              the first binomial(r+1,k+1) variables of R.            |
|              If R is not given, the routine makes and uses          |
|              ZZ/31991[vars(0..binomial(r+1,k+1)-1]."                |
|              };                                                     |
+---------------------------------------------------------------------+

In order to make Fano2 handle an optional number of arguments, we make it a
method instead of a function, documenting it as follows.

+----------------------+
|i21 : Fano2 = method()|
|                      |
|o21 = Fano2           |
|                      |
|o21 : MethodFunction  |
+----------------------+

Here is the code for the first case, with comments interspersed:

+-----------------------------------------------------------------------------+
|i22 : Fano2(ZZ,Ideal,Ring) := (k,X,GR) -> (                                  |
|        -- Get info about the base ring of X:                                |
|        -- The coefficient ring (to make new rings of                        |
|        -- the same characteristic, for example)                             |
|        -- and the number of variables                                       |
|        KK:=coefficientRing ring X;                                          |
|        r := (numgens ring X) - 1;                                           |
|        -- Next make private variables for our                               |
|        -- intermediate rings, to avoid interfering                          |
|        -- with something outside:                                           |
|        t:=symbol t;                                                         |
|        p:=symbol p;                                                         |
|        -- And rings                                                         |
|        S1 := KK[t_0..t_k];                                                  |
|        S2 := KK[p_0..p_(k*r+k+r)];                                          |
|        S := tensor(S1,S2);                                                  |
|        -- Over S we have a generic point of a generic                       |
|        -- line, represented by a row vector, which                          |
|        -- we use to define a map from the base ring                         |
|        -- of X                                                              |
|        F := map(S,ring X,                                                   |
|                genericMatrix(S,S_0,1,k+1)*                                  |
|                genericMatrix(S,S_(k+1),k+1,r+1)                             |
|                );                                                           |
|        -- We now apply F to the ideal of X                                  |
|        FX := F X;                                                           |
|        -- and the condition we want becomes the condition                   |
|        -- that FX vanishes identically in the t_i.                          |
|        -- The following line produces the matrix of                         |
|        -- coefficients of the monomials in the                              |
|        -- variables labelled 0..k:                                          |
|        cFX := last coefficients (gens FX, Variables => toList apply(0..k, i |
|        -- We can get rid of the variables t_i                               |
|        -- to ease the computation:                                          |
|        cFX = substitute(cFX, S2);                                           |
|        -- The ring we want is the quotient                                  |
|        S2bar := S2/ideal cFX;                                               |
|        -- Now we want to move to the Grassmannian,                          |
|        -- represented by the ring GR                                        |
|        -- We define a map sending the variables of GR                       |
|        -- to the minors of the generic matrix in the                        |
|        -- p_i regarded as elements of S1bar                                 |
|        gr := map(S2bar,GR,                                                  |
|                  exteriorPower(k+1,                                         |
|                  genericMatrix(S2bar,S2bar_0,k+1,r+1)                       |
|                  )                                                          |
|                 );                                                          |
|        -- and the defining ideal of the Fano variety is                     |
|        ker gr                                                               |
|      )                                                                      |
|                                                                             |
|o22 = FunctionClosure[currentString:52:24-101:1]                             |
|                                                                             |
|o22 : FunctionClosure                                                        |
|-----------------------------------------------------------------------------|
|-> S_i));                                                                    |
+-----------------------------------------------------------------------------+

Here is the code for the second case, which reduces to the first.

+---------------------------------------------------------------+
|i23 : Fano2(ZZ, Ideal) := (k,X) -> (                           |
|        KK:=coefficientRing ring X;                            |
|        r := (numgens ring X) - 1;                             |
|        -- We can specify a private ring with binomial(r+1,k+1)|
|        -- variables as follows                                |
|        GR := KK[Variables => binomial(r+1,k+1)];              |
|        -- the work is done by                                 |
|        Fano2(k,X,GR)                                          |
|      )                                                        |
|                                                               |
|o23 = FunctionClosure[currentString:102:20-110:1]              |
|                                                               |
|o23 : FunctionClosure                                          |
+---------------------------------------------------------------+

With the zero ideal we get the Grassmannian of projective $k$-planes in
$\PP^r$:

+---------------------------------------------------+
|i24 : Grassmannian2 = method()                     |
|                                                   |
|o24 = Grassmannian2                                |
|                                                   |
|o24 : MethodFunction                               |
+---------------------------------------------------+
|i25 : Grassmannian2(ZZ,ZZ,Ring) := (k,r,R) ->(     |
|              KK := coefficientRing R;             |
|              RPr := KK[Variables => r+1];         |
|              Pr := ideal(0_RPr);                  |
|              Fano2(k,Pr)                          |
|           )                                       |
|                                                   |
|o25 = FunctionClosure[currentString:112:29-117:6]  |
|                                                   |
|o25 : FunctionClosure                              |
+---------------------------------------------------+
|i26 : Grassmannian2(ZZ,ZZ) := (r,k) -> (           |
|              R := ZZ/31991[                       |
|                     vars(0..(binomial(r+1,k+1)-1))|
|                          ];                       |
|              Grassmannian2(k,r,R)                 |
|                           )                       |
|                                                   |
|o26 = FunctionClosure[currentString:118:24-123:22] |
|                                                   |
|o26 : FunctionClosure                              |
+---------------------------------------------------+

As a first example we can try the Fano of lines on the nonsingular quadric in
$\PP^3$

+-----------------------------------------------------------------------------+
|i27 : KK = ZZ/31991                                                          |
|                                                                             |
|o27 = KK                                                                     |
|                                                                             |
|o27 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i28 : R = KK[a,b,c,d]                                                        |
|                                                                             |
|o28 = R                                                                      |
|                                                                             |
|o28 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i29 : X = ideal(a*b-c*d)                                                     |
|                                                                             |
|o29 = ideal(a*b - c*d)                                                       |
|                                                                             |
|o29 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i30 : I = Fano2(1,X)                                                         |
|                                                                             |
|                                                  2                          |
|o30 = ideal (p p , p p , p p  + 15995p p  - 15995p , p p  + p p , p p  -     |
|              3 4   2 4   1 4         0 5         5   0 4    4 5   2 3       |
|      -----------------------------------------------------------------------|
|                        2                                                    |
|      15995p p  - 15995p , p p , p p  - p p , p p , p p  - p p , p p  + p p ,|
|            0 5         5   1 3   0 3    3 5   1 2   0 2    2 5   0 1    1 5 |
|      -----------------------------------------------------------------------|
|       2    2                                                                |
|      p  - p )                                                               |
|       0    5                                                                |
|                                                                             |
|o30 : Ideal of KK[p ..p ]                                                    |
|                   0   5                                                     |
+-----------------------------------------------------------------------------+

we investigate by checking its dimension and degree

+-----------+
|i31 : dim I|
|           |
|o31 = 2    |
+-----------+

The answer ``2'' means that $I$ is the ideal of a curve in $\PP^5$, the ambient
space of the Grassmannian of lines.

+--------------+
|i32 : degree I|
|              |
|o32 = 4       |
+--------------+

The answer is 4.  In fact, the ideal $I$ represents the union of two conics.

C. Surfaces of degree $4$ in $\PP^5$

We now turn to the three surfaces of degree $4$ in $\PP^5$, and make their
ideals:

The ring of $\PP^5$

+--------------------+
|i33 : KK = ZZ/31991 |
|                    |
|o33 = KK            |
|                    |
|o33 : QuotientRing  |
+--------------------+
|i34 : P5 = KK[a..f] |
|                    |
|o34 = P5            |
|                    |
|o34 : PolynomialRing|
+--------------------+

It happens that the ideals of all three surfaces are generated by minors of
suitable matrices:

The Veronese embedding of $\PP^2$:

+-----------------------------------------------------------------------------+
|i35 : MVero = genericSymmetricMatrix(P5,a,3)                                 |
|                                                                             |
|o35 = | a b c |                                                              |
|      | b d e |                                                              |
|      | c e f |                                                              |
|                                                                             |
|               3       3                                                     |
|o35 : Matrix P5  <-- P5                                                      |
+-----------------------------------------------------------------------------+
|i36 : Vero = minors(2,MVero)                                                 |
|                                                                             |
|                2                                                  2         |
|o36 = ideal (- b  + a*d, - b*c + a*e, - c*d + b*e, - b*c + a*e, - c  + a*f, -|
|      -----------------------------------------------------------------------|
|                                              2                              |
|      c*e + b*f, - c*d + b*e, - c*e + b*f, - e  + d*f)                       |
|                                                                             |
|o36 : Ideal of P5                                                            |
+-----------------------------------------------------------------------------+

The other scrolls are defined by the minors of matrices that are made from
``catalecticant'' blocks, that is, from matrices such as $$\begin{pmatrix}b & c
& d & e \\ c & d & e & f \end{pmatrix}$$ which are manufactured by

+------------------------------------------+
|i37 : catalecticant = (R,v,m,n) ->        |
|              map(R^m,n,(i,j)-> R_(i+j+v))|
|                                          |
|o37 = catalecticant                       |
|                                          |
|o37 : FunctionClosure                     |
+------------------------------------------+

for example

+-----------------------------+
|i38 : catalecticant(P5,1,2,4)|
|                             |
|o38 = | b c d e |            |
|      | c d e f |            |
|                             |
|               2       4     |
|o38 : Matrix P5  <-- P5      |
+-----------------------------+

produces the example above. The rational normal scroll S13, which is the union
of lines joining a line with the corresponding points of a twisted cubic in a
disjoint subspace of $\PP^5$

+-----------------------------------------------------------------------------+
|i39 : M13 = catalecticant(P5,0,2,1) |                                        |
|                 catalecticant(P5,2,2,3)                                     |
|                                                                             |
|o39 = | a c d e |                                                            |
|      | b d e f |                                                            |
|                                                                             |
|               2       4                                                     |
|o39 : Matrix P5  <-- P5                                                      |
+-----------------------------------------------------------------------------+
|i40 : S13 = minors(2,M13)                                                    |
|                                                                             |
|                                          2                                  |
|o40 = ideal (- b*c + a*d, - b*d + a*e, - d  + c*e, - b*e + a*f, - d*e + c*f, |
|      -----------------------------------------------------------------------|
|         2                                                                   |
|      - e  + d*f)                                                            |
|                                                                             |
|o40 : Ideal of P5                                                            |
+-----------------------------------------------------------------------------+

Finally, the rational normal scroll S22, which is made by a similar
construction starting with two conics in $\PP^5$

+-------------------------------------------------------------+
|i41 : M22 = catalecticant(P5,0,2,2) | catalecticant(P5,3,2,2)|
|                                                             |
|o41 = | a b d e |                                            |
|      | b c e f |                                            |
|                                                             |
|               2       4                                     |
|o41 : Matrix P5  <-- P5                                      |
+-------------------------------------------------------------+

+-----------------------------------------------------------------------------+
|i42 : S22 = minors(2, M22)                                                   |
|                                                                             |
|                2                                                            |
|o42 = ideal (- b  + a*c, - b*d + a*e, - c*d + b*e, - b*e + a*f, - c*e + b*f, |
|      -----------------------------------------------------------------------|
|         2                                                                   |
|      - e  + d*f)                                                            |
|                                                                             |
|o42 : Ideal of P5                                                            |
+-----------------------------------------------------------------------------+

It is interesting to note that the numerical invariants of these surfaces are
very hard to distinguish.  In particular, the graded betti numbers

+---------------------------------------+
|i43 : Verores = res coker gens Vero    |
|                                       |
|        1       6       8       3      |
|o43 = P5  <-- P5  <-- P5  <-- P5  <-- 0|
|                                       |
|      0       1       2       3       4|
|                                       |
|o43 : ChainComplex                     |
+---------------------------------------+
|i44 : S22res = res coker gens S22      |
|                                       |
|        1       6       8       3      |
|o44 = P5  <-- P5  <-- P5  <-- P5  <-- 0|
|                                       |
|      0       1       2       3       4|
|                                       |
|o44 : ChainComplex                     |
+---------------------------------------+
|i45 : S13res = res coker gens S13      |
|                                       |
|        1       6       8       3      |
|o45 = P5  <-- P5  <-- P5  <-- P5  <-- 0|
|                                       |
|      0       1       2       3       4|
|                                       |
|o45 : ChainComplex                     |
+---------------------------------------+
|i46 : betti Verores                    |
|                                       |
|             0 1 2 3                   |
|o46 = total: 1 6 8 3                   |
|          0: 1 . . .                   |
|          1: . 6 8 3                   |
|                                       |
|o46 : BettiTally                       |
+---------------------------------------+
|i47 : betti S22res                     |
|                                       |
|             0 1 2 3                   |
|o47 = total: 1 6 8 3                   |
|          0: 1 . . .                   |
|          1: . 6 8 3                   |
|                                       |
|o47 : BettiTally                       |
+---------------------------------------+
|i48 : betti S13res                     |
|                                       |
|             0 1 2 3                   |
|o48 = total: 1 6 8 3                   |
|          0: 1 . . .                   |
|          1: . 6 8 3                   |
|                                       |
|o48 : BettiTally                       |
+---------------------------------------+

coincide, so the three cannot be distinguished on the basis of these or on the
basis of the (weaker) invariants the Hilbert series or Hilbert polynomials. But
the Fano varieties are more obviously different:

We compute the Fano varieties of lines on each of our surfaces.

+-----------------------------------------------------------------------------+
|i49 : FVero = Fano2(1, Vero)                                                 |
|                                                                             |
|              2                                                              |
|o49 = ideal (p  , p  p  , p  p  , p  p  , p  p  , p p  , p p  , p p  , p p  ,|
|              14   13 14   12 14   11 14   10 14   9 14   8 14   7 14   6 14 |
|      -----------------------------------------------------------------------|
|                                                 2                           |
|      p p  , p p  , p p  , p p  , p p  , p p  , p  , p  p  , p  p  , p  p  , |
|       5 14   4 14   3 14   2 14   1 14   0 14   13   12 13   11 13   10 13  |
|      -----------------------------------------------------------------------|
|                                                                             |
|      p p  , p p  , p p  , p p  , p p  , p p  , p p  , p p  , p p  , p p  ,  |
|       9 13   8 13   7 13   6 13   5 13   4 13   3 13   2 13   1 13   0 13   |
|      -----------------------------------------------------------------------|
|       2                                                                     |
|      p  , p  p  , p  p  , p p  , p p  , p p  , p p  , p p  , p p  , p p  ,  |
|       12   11 12   10 12   9 12   8 12   7 12   6 12   5 12   4 12   3 12   |
|      -----------------------------------------------------------------------|
|                            2                                                |
|      p p  , p p  , p p  , p  , p  p  , p p  , p p  , p p  , p p  , p p  ,   |
|       2 12   1 12   0 12   11   10 11   9 11   8 11   7 11   6 11   5 11    |
|      -----------------------------------------------------------------------|
|                                          2                                  |
|      p p  , p p  , p p  , p p  , p p  , p  , p p  , p p  , p p  , p p  ,    |
|       4 11   3 11   2 11   1 11   0 11   10   9 10   8 10   7 10   6 10     |
|      -----------------------------------------------------------------------|
|                                                 2                           |
|      p p  , p p  , p p  , p p  , p p  , p p  , p , p p , p p , p p , p p ,  |
|       5 10   4 10   3 10   2 10   1 10   0 10   9   8 9   7 9   6 9   5 9   |
|      -----------------------------------------------------------------------|
|                                     2                                       |
|      p p , p p , p p , p p , p p , p , p p , p p , p p , p p , p p , p p ,  |
|       4 9   3 9   2 9   1 9   0 9   8   7 8   6 8   5 8   4 8   3 8   2 8   |
|      -----------------------------------------------------------------------|
|                   2                                             2           |
|      p p , p p , p , p p , p p , p p , p p , p p , p p , p p , p , p p ,    |
|       1 8   0 8   7   6 7   5 7   4 7   3 7   2 7   1 7   0 7   6   5 6     |
|      -----------------------------------------------------------------------|
|                                     2                                 2     |
|      p p , p p , p p , p p , p p , p , p p , p p , p p , p p , p p , p ,    |
|       4 6   3 6   2 6   1 6   0 6   5   4 5   3 5   2 5   1 5   0 5   4     |
|      -----------------------------------------------------------------------|
|                               2                     2               2       |
|      p p , p p , p p , p p , p , p p , p p , p p , p , p p , p p , p , p p ,|
|       3 4   2 4   1 4   0 4   3   2 3   1 3   0 3   2   1 2   0 2   1   0 1 |
|      -----------------------------------------------------------------------|
|       2                                                                     |
|      p )                                                                    |
|       0                                                                     |
|                                                                             |
|o49 : Ideal of KK[p ..p  ]                                                   |
|                   0   14                                                    |
+-----------------------------------------------------------------------------+
|i50 : betti gens FVero                                                       |
|                                                                             |
|             0   1                                                           |
|o50 = total: 1 120                                                           |
|          0: 1   .                                                           |
|          1: . 120                                                           |
|                                                                             |
|o50 : BettiTally                                                             |
+-----------------------------------------------------------------------------+

The ideal contains all $120$ quadrics, and represents the empty set:  The
Veronese surface contains no lines!

+-----------------------------------------------------------------------------+
|i51 : FS13 = Fano2(1, S13)                                                   |
|                                                                             |
|              2                                                              |
|o51 = ideal (p  , p  p  , p  p  , p  p  , p  p  , p p  , p p  , p p  , p p  ,|
|              14   13 14   12 14   11 14   10 14   9 14   8 14   7 14   6 14 |
|      -----------------------------------------------------------------------|
|                                                 2                           |
|      p p  , p p  , p p  , p p  , p p  , p p  , p  , p  p  , p  p  , p  p  , |
|       5 14   4 14   3 14   2 14   1 14   0 14   13   12 13   11 13   10 13  |
|      -----------------------------------------------------------------------|
|                                                                             |
|      p p  , p p  , p p  , p p  , p p  , p p  , p p  , p p  , p p  , p p  ,  |
|       9 13   8 13   7 13   6 13   5 13   4 13   3 13   2 13   1 13   0 13   |
|      -----------------------------------------------------------------------|
|       2                                                                     |
|      p  , p  p  , p  p  , p p  , p p  , p p  , p p  , p p  , p p  , p p  ,  |
|       12   11 12   10 12   9 12   8 12   7 12   6 12   5 12   4 12   3 12   |
|      -----------------------------------------------------------------------|
|                                                                             |
|      p p  , p p  , p p  , p p  , p p  , p p   - p  p  , p p  , p p   -      |
|       2 12   1 12   0 12   9 11   8 11   7 11    10 11   5 11   4 11        |
|      -----------------------------------------------------------------------|
|                                    2                                        |
|      p p  , p p   - p p  , p p  , p   - p p  , p p  , p p  , p p   - p p  , |
|       6 11   2 11    3 11   0 11   10    6 11   9 10   8 10   7 10    6 11  |
|      -----------------------------------------------------------------------|
|                                                                             |
|      p p   - p p  , p p  , p p   - p p  , p p   - p p  , p p   - p p  ,     |
|       6 10    3 11   5 10   4 10    3 11   3 10    1 11   2 10    1 11      |
|      -----------------------------------------------------------------------|
|              2                                                         2    |
|      p p  , p , p p , p p , p p , p p , p p , p p , p p , p p , p p , p ,   |
|       0 10   9   8 9   7 9   6 9   5 9   4 9   3 9   2 9   1 9   0 9   8    |
|      -----------------------------------------------------------------------|
|                                                       2                     |
|      p p , p p , p p , p p , p p , p p , p p , p p , p  - p p  , p p  -     |
|       7 8   6 8   5 8   4 8   3 8   2 8   1 8   0 8   7    6 11   6 7       |
|      -----------------------------------------------------------------------|
|                                                                             |
|      p p  , p p , p p  - p p  , p p  - p p  , p p  - p p  , p p  - p p  ,   |
|       3 11   5 7   4 7    3 11   3 7    1 11   2 7    1 11   1 7    1 10    |
|      -----------------------------------------------------------------------|
|             2                                                               |
|      p p , p  - p p  , p p , p p  - p p  , p p  - p p  , p p  - p p  , p p ,|
|       0 7   6    1 11   5 6   4 6    1 11   3 6    1 10   2 6    1 10   0 6 |
|      -----------------------------------------------------------------------|
|       2                                 2                                   |
|      p , p p , p p , p p , p p , p p , p  - p p  , p p  - p p  , p p  -     |
|       5   4 5   3 5   2 5   1 5   0 5   4    1 11   3 4    1 10   2 4       |
|      -----------------------------------------------------------------------|
|                                 2                             2             |
|      p p  , p p  - p p , p p , p  - p p , p p  - p p , p p , p  - p p , p p |
|       1 10   1 4    1 6   0 4   3    1 6   2 3    1 6   0 3   2    1 6   1 2|
|      -----------------------------------------------------------------------|
|      - p p , p p , p p )                                                    |
|         1 3   0 2   0 1                                                     |
|                                                                             |
|o51 : Ideal of KK[p ..p  ]                                                   |
|                   0   14                                                    |
+-----------------------------------------------------------------------------+

It turns out that the dimension (1) and degree (4) of these varieties coincide!
Moreover, since the ideals are not saturated, one cannot directly compare the
Hilbert series or free resolutions (of course one could first compute a
saturation). But there is the arithmetic genus, that is, $1-H(0)$, where $H$ is
the Hilbert polynomial.

+---------------------------------------+
|i52 : hilbertPolynomial coker gens FS13|
|                                       |
|o52 = - 2*P  + 4*P                     |
|           0      1                    |
|                                       |
|o52 : ProjectiveHilbertPolynomial      |
+---------------------------------------+

The output, $4 \PP^1 - 2 \PP^0$, means ``four times the Hilbert polynomial of
the projective line minus 2''; that is, the polynomial is $H(d) = 4d + 2$; so
arithmetic genus is $-1$.

+-----------------------------------------------------------------------------+
|i53 : FS22 = Fano2(1, S22)                                                   |
|                                                                             |
|              2                                                              |
|o53 = ideal (p  , p  p  , p  p  , p  p  , p  p  , p p  , p p  , p p  , p p  ,|
|              14   13 14   12 14   11 14   10 14   9 14   8 14   7 14   6 14 |
|      -----------------------------------------------------------------------|
|                                                 2                           |
|      p p  , p p  , p p  , p p  , p p  , p p  , p  , p  p  , p  p  , p  p  , |
|       5 14   4 14   3 14   2 14   1 14   0 14   13   12 13   11 13   10 13  |
|      -----------------------------------------------------------------------|
|                                                                             |
|      p p  , p p  , p p  , p p  , p p  , p p  , p p  , p p  , p p  , p p  ,  |
|       9 13   8 13   7 13   6 13   5 13   4 13   3 13   2 13   1 13   0 13   |
|      -----------------------------------------------------------------------|
|                                                                             |
|      p p  , p p   - p  p  , p p   - p  p  , p p   - p  p  , p p   - p p  ,  |
|       9 12   8 12    11 12   7 12    10 12   5 12    10 12   4 12    6 12   |
|      -----------------------------------------------------------------------|
|                            2                                                |
|      p p  , p p  , p p  , p   - p  p  , p  p   - p p  , p p  , p p   -      |
|       2 12   1 12   0 12   11    10 12   10 11    6 12   9 11   8 11        |
|      -----------------------------------------------------------------------|
|                                                                             |
|      p  p  , p p   - p p  , p p   - p p  , p p   - p p  , p p   - p p  ,    |
|       10 12   7 11    6 12   6 11    3 12   5 11    6 12   4 11    3 12     |
|      -----------------------------------------------------------------------|
|                            2                                                |
|      p p  , p p  , p p  , p   - p p  , p p  , p p   - p p  , p p   - p p  , |
|       2 11   1 11   0 11   10    3 12   9 10   8 10    6 12   7 10    3 12  |
|      -----------------------------------------------------------------------|
|                                                                         2   |
|      p p   - p p  , p p   - p p  , p p   - p p  , p p  , p p  , p p  , p ,  |
|       6 10    3 11   5 10    3 12   4 10    3 11   2 10   1 10   0 10   9   |
|      -----------------------------------------------------------------------|
|                                                             2               |
|      p p , p p , p p , p p , p p , p p , p p , p p , p p , p  - p  p  , p p |
|       8 9   7 9   6 9   5 9   4 9   3 9   2 9   1 9   0 9   8    10 12   7 8|
|      -----------------------------------------------------------------------|
|                                                                             |
|      - p p  , p p  - p p  , p p  - p p  , p p  - p p  , p p  - p p  , p p , |
|         6 12   6 8    3 12   5 8    6 12   4 8    3 12   3 8    3 11   2 8  |
|      -----------------------------------------------------------------------|
|                   2                                                         |
|      p p , p p , p  - p p  , p p  - p p  , p p  - p p  , p p  - p p  , p p  |
|       1 8   0 8   7    3 12   6 7    3 11   5 7    3 12   4 7    3 11   3 7 |
|      -----------------------------------------------------------------------|
|                                  2                                          |
|      - p p  , p p , p p , p p , p  - p p  , p p  - p p  , p p  - p p  ,     |
|         3 10   2 7   1 7   0 7   6    3 10   5 6    3 11   4 6    3 10      |
|      -----------------------------------------------------------------------|
|                         2                                                   |
|      p p , p p , p p , p  - p p  , p p  - p p  , p p  - p p  , p p , p p ,  |
|       2 6   1 6   0 6   5    3 12   4 5    3 11   3 5    3 10   2 5   1 5   |
|      -----------------------------------------------------------------------|
|             2                                                            2  |
|      p p , p  - p p  , p p  - p p , p p , p p , p p , p p , p p , p p , p , |
|       0 5   4    3 10   3 4    3 6   2 4   1 4   0 4   2 3   1 3   0 3   2  |
|      -----------------------------------------------------------------------|
|                   2         2                                               |
|      p p , p p , p , p p , p )                                              |
|       1 2   0 2   1   0 1   0                                               |
|                                                                             |
|o53 : Ideal of KK[p ..p  ]                                                   |
|                   0   14                                                    |
+-----------------------------------------------------------------------------+
|i54 : hilbertPolynomial coker gens FS22                                      |
|                                                                             |
|o54 = - 3*P  + 4*P                                                           |
|           0      1                                                          |
|                                                                             |
|o54 : ProjectiveHilbertPolynomial                                            |
+-----------------------------------------------------------------------------+

The output, $4 \PP^1 - 3 \PP^0$, means $H(d) = 4d + 1$, arithmetic genus $-1$.
In fact, the Fano variety of S22 consists of a projective line, embedded as a
smooth rational quartic; while the Fano variety of S13 consists of a smooth
rational quartic (corresponding to the rulings of the surface S13 and an
isolated point, corresponding to the section of negative self-intersection on
the surface).

Tutorial: Divisors
******************

In this tutorial we describe one way to represent divisors on a smooth
projective subvariety $X$ of $\PP^r$, and show methods for computing the group
operations, computing the vector space of sections, and determining whether two
divisors are linearly equivalent.  We also construct the canonical divisor on
$X$.

We consider smooth varieties only, although most of this can be extended to
normal varieties. Cartier and Weil divisors on normal varieties might be the
subject of a further tutorial.

Other possible future topics would be: intersection numbers, determining
whether a divisor is very ample, and finding the base point locus of the
divisor class.

The simplest case is when the homogeneous coordinate ring $S_X$ of $X$
satisfies the $S_2$ condition of Serre: We say that a domain $R$ is $S_2$ if
every proper nonzero principal ideal has pure codimension 1 (all associated
primes of the ideal are of codimension 1).

In this tutorial, we consider the case when this holds (e.g., this holds for
complete intersections). In a further tutorial, we will make the necessary
extensions to handle the non $S_2$-case.

An example that we will use throughout is the plane cubic curve $E$, whose
homogeneous coordinate ring is SE:

+---------------------------------------------+
|i1 : KK = ZZ/31991                           |
|                                             |
|o1 = KK                                      |
|                                             |
|o1 : QuotientRing                            |
+---------------------------------------------+
|i2 : SE = KK[x,y,z]/(y^2*z - x*(x-z)*(x+3*z))|
|                                             |
|o2 = SE                                      |
|                                             |
|o2 : QuotientRing                            |
+---------------------------------------------+

The sections in this tutorial are  A. Representation of divisors

B. Group operations on divisors

C. Global Sections

D. Linear Equivalence

E. The canonical divisor

A. Representation of divisors

Let $X$ be a smooth irreducible variety.  A (Weil) divisor on $X$ is an
integral linear combination of irreducible subvarieties of $X$ of codimension
$1$. The divisor is called effective if all the coefficients are non-negative.
To any ideal $I$ in the homogeneous coordinate ring $S_X$ of $X$ we associate
the effective divisor that is the sum of the pure codimension $1$ components of
$I$, each taken with the multiplicity it has in the primary decomposition of
$I$.

Let $D = E - F$ be a divisor, where $E$ and $F$ are effective. Because $X$ is
normal, there is a unique homogeneous ideal $I$ in $S_X$ such that $V(I) = E$,
and $I$ is either $(1)$, or has pure codimension one.  Similarly, there is a
unique such ideal $J$ with $V(J) = F$. Our plan is to represent the divisor $D$
by the pair of ideals $(I,J)$.

This representation is not unique.  If $(I,J)$ and $(I',J')$ are two pairs of
ideals (such that each ideal is either $(1)$ or has pure codimension one), then
$(I,J)$ and $(I',J')$ represent the same divisor iff $$sat(I J') = sat(I' J),$$
where $sat(K)$ is the saturation of $K$ (the largest ideal $L$ such that a
power of the irrelevant ideal times $L$ is in $K$) Write $(I,J) \equiv (I',J')$
if $sat(I J') = sat(I' J)$.

This correspondence defines a bijection between $Div(X)$ and $\{(I,J) \mid I,J$
are homogeneous ideals in $S_X$ either trivial, or pure codim one$\}/\equiv$.

As we will often have to saturate ideals of codimension 1, we give here the
most efficient method we know, which has the additional advantage of throwing
away all components not of codimension 1.  That is, we define purify1S2(I), a
function that takes an arbitrary ideal $I$ in a ring satisfying $S_2$, and
returns the ideal which is the intersection of the codimension 1 primary
components of $I$. In the next divisor tutorial (not yet written), we will
write a routine purify1(I) which does not require the ring to be $S_2$.

+---------------------------------------------------------------+
|i3 : purify1S2 = I -> (                                        |
|         -- Assuming ring I is S2, and I is not 0, returns the |
|         -- pure codimension 1 part of I.                      |
|         -- Find a nonzero element of I:                       |
|         M := compress gens I;                                 |
|         -- Explanation: gens I is                             |
|         -- the matrix of generators of I; compress            |
|         -- removes the entries that are 0                     |
|         -- and := makes M a local variable.                   |
|         if numgens source M == 0                              |
|         then error "purify1S2: expected nonzero ideal";       |
|         f := ideal M_(0,0);                                   |
|         -- f is the ideal generated by the first entry.       |
|         -- Since ring I is S2, the ideal f is                 |
|         -- pure codimension 1.  Thus                          |
|         f:(f:I)                                               |
|         -- is the pure codimension 1 part. (The last          |
|         -- expression given in a function is the returned     |
|         -- value, provided the semicolon is left off.)        |
|         )                                                     |
|                                                               |
|o3 = purify1S2                                                 |
|                                                               |
|o3 : FunctionClosure                                           |
+---------------------------------------------------------------+

For example, in the ring

+-------------------+
|i4 : R = ZZ/5[a,b] |
|                   |
|o4 = R             |
|                   |
|o4 : PolynomialRing|
+-------------------+

we have

+-----------------------------+
|i5 : purify1S2 ideal(a^2,a*b)|
|                             |
|o5 = ideal a                 |
|                             |
|o5 : Ideal of R              |
+-----------------------------+

B Unfortunately at this moment the quotient code B makes this slow.  Another
possibility is B purify1S2 = saturation B which is (9/23/96) slightly faster
(88 vs 106 sec).

Throughout this tutorial, we will treat divisors as equivalence classes of
pairs, and our operations will operate on pairs.  So let's define a divisor
type in Macaulay2. The following declaration provides a new data type, the
Divisor.

+------------------------------------+
|i6 : Divisor = new Type of BasicList|
|                                    |
|o6 = Divisor                        |
|                                    |
|o6 : Type                           |
+------------------------------------+

Let's write a routine to create a divisor, from either a single ideal, or a
pair of ideals. (This routine should check that its arguments are pure
codimension one, or trivial, and in the same ring, but we will ignore that).

Defining divisor to be a method allows us to define different versions of this
routine which take different arguments.

+-----------------------+
|i7 : divisor = method()|
|                       |
|o7 = divisor           |
|                       |
|o7 : MethodFunction    |
+-----------------------+

The following allows us to define an object of class Divisor from a pair of
ideals.

+-----------------------------------------------------------------------------+
|i8 : divisor(Ideal,Ideal) := (I,J) -> new Divisor from {purify1S2 I,purify1S2|
|-----------------------------------------------------------------------------|
|J};                                                                          |
+-----------------------------------------------------------------------------+

The following routine defines an (effective) divisor from a single ideal.

+--------------------------------------------------------+
|i9 : divisor Ideal := I -> divisor(I, ideal 1_(ring I));|
+--------------------------------------------------------+

The divisors of some rational points on the elliptic curve $E$ include

+----------------------------------------------+
|i10 : P = divisor ideal(x,z)                  |
|                                              |
|o10 = Divisor{ideal (z, x), ideal 1}          |
|                                              |
|o10 : Divisor                                 |
+----------------------------------------------+
|i11 : R = divisor ideal(x,y)                  |
|                                              |
|o11 = Divisor{ideal (y, x), ideal 1}          |
|                                              |
|o11 : Divisor                                 |
+----------------------------------------------+
|i12 : R1 = divisor ideal(x-z,y)               |
|                                              |
|o12 = Divisor{ideal (y, x - z), ideal 1}      |
|                                              |
|o12 : Divisor                                 |
+----------------------------------------------+
|i13 : R2 = divisor ideal(x+3*z,y)             |
|                                              |
|o13 = Divisor{ideal (y, x + 3z), ideal 1}     |
|                                              |
|o13 : Divisor                                 |
+----------------------------------------------+
|i14 : Q1 = divisor ideal(y-6*z, x-3*z)        |
|                                              |
|o14 = Divisor{ideal (y - 6z, x - 3z), ideal 1}|
|                                              |
|o14 : Divisor                                 |
+----------------------------------------------+

Testing equality of divisors is often made simpler by having a ``normal form''
for divisors. The normal form of a divisor $D$ is $E - F$ where $E$ and $F$ are
both effective and have disjoint support. It is easy to see that the normal
form of $(I,J)$ is $(I:J, J:I)$.

In the following code, the expressions D\#0 and D\#1 refer to the first and
second ideals in the list representing $D$. (D\#0 is the first because
Macaulay2 counts everything starting from 0.)

+-------------------------------------------------------------------------+
|i15 : normalForm = method()                                              |
|                                                                         |
|o15 = normalForm                                                         |
|                                                                         |
|o15 : MethodFunction                                                     |
+-------------------------------------------------------------------------+
|i16 : normalForm Divisor := D -> new Divisor from {D#0 : D#1, D#1 : D#0};|
+-------------------------------------------------------------------------+

Two pairs $(I,J), (I',J')$ define the same divisor exactly when their normal
forms are equal. The following code establishes a method for testing the
equality of divisors.  The function "toList" converts a divisor to a list of
ideals, and then we let the built in method for comparing lists take over: it
compares corresponding elements.

+-----------------------------------------------------------------------------+
|i17 : Divisor == Divisor := (D,E) -> toList normalForm D == toList normalForm|
|-----------------------------------------------------------------------------|
|E;                                                                           |
+-----------------------------------------------------------------------------+

An important point here is that the built in method for comparing two ideals
used by the operator "==" succeeds even if the given generators differ. We
shall later show that with R1 and {\tt R2} as above, the divisor (R1 + R2) - R1
is represented by

+-----------------------------------------------------------+
|i18 : D = divisor(ideal(y, x^2+2*x*z-3*z^2), ideal(x-z, y))|
|                                                           |
|                         2            2                    |
|o18 = Divisor{ideal (y, x  + 2x*z - 3z ), ideal (y, x - z)}|
|                                                           |
|o18 : Divisor                                              |
+-----------------------------------------------------------+

so that the normal form of $D$ is {\tt R2}:

+-----------------------------------------+
|i19 : normalForm D                       |
|                                         |
|o19 = Divisor{ideal (y, x + 3z), ideal 1}|
|                                         |
|o19 : Divisor                            |
+-----------------------------------------+

and we can directly test equality by

+-------------+
|i20 : D == R2|
|             |
|o20 = true   |
+-------------+

B. Group operations on divisors

To add divisors we multiply the corresponding ideals and then saturate. This
may be coded as follows (the products are saturated in the divisor routine):

+------------------------------------------------------------------+
|i21 : Divisor + Divisor := (D,E) -> divisor(D#0 * E#0, D#1 * E#1);|
+------------------------------------------------------------------+

Negation is even simpler, since all we need do is exchange the two ideals.  We
don't use the divisor routine, since our ideals are already saturated.

+------------------------------------------------------+
|i22 : - Divisor := (D) -> new Divisor from {D#1, D#0};|
+------------------------------------------------------+

Let's also include functions to compute differences and to multiply by
integers.

+-----------------------------------------------------------------------+
|i23 : Divisor - Divisor := (D,E) -> D + (-E);                          |
+-----------------------------------------------------------------------+
|i24 : ZZ Divisor := ZZ * Divisor := (n,D) -> divisor((D#0)^n, (D#1)^n);|
+-----------------------------------------------------------------------+

Some arithmetic of divisors on our elliptic curve

+-------------------------------------+
|i25 : 2 P                            |
|                                     |
|                         2           |
|o25 = Divisor{ideal (z, x ), ideal 1}|
|                                     |
|o25 : Divisor                        |
+-------------------------------------+
|i26 : 3 P                            |
|                                     |
|o26 = Divisor{ideal z, ideal 1}      |
|                                     |
|o26 : Divisor                        |
+-------------------------------------+

Notice that $3P$ is the hyperplane section $z=0$, which is the equation of the
flex line to the cubic at the point $P$.

+-----------------------------------------------+
|i27 : D = P-R1                                 |
|                                               |
|o27 = Divisor{ideal (z, x), ideal (y, x - z)}  |
|                                               |
|o27 : Divisor                                  |
+-----------------------------------------------+
|i28 : D2 = 2 P - 2 R1                          |
|                                               |
|                         2                  2  |
|o28 = Divisor{ideal (z, x ), ideal (x - z, y )}|
|                                               |
|o28 : Divisor                                  |
+-----------------------------------------------+

C. Global Sections

Since we have assumed $X$ smooth, Weil divisors can all be represented by
Cartier divisors, that is, by sections of an invertible sheaf.  If $D = (I,J)$
is a divisor, and $sheaf(I)$ denotes the sheaf of $O_X$-modules corresponding
to $I$, then we put $$O_X(D) = sheaf(I)^{-1} \otimes sheaf(J).$$

We define $L(D)$ to be the space of global sections of the sheaf $O_X(D)$. Note
that a global section is the same as a sheaf homomorphism $O_X \rightarrow{}
O_X(D)$. If we write $D = E-F$, where $E$ and $F$ are effective, then global
sections of $O_X(E-F)$ can be identified with homomorphisms $O_X(-E)
\rightarrow{} O_X(-F)$.

If we write $D = (I,J)$, then $L(D)$ and $Hom(I,J)$ can be identified with
subsets of the field of fractions of $S_X$. Since $S_X$ satisfies $S_2$, these
sets are equal. The following proposition allows us to compute $Hom(I,J)$:
Proposition. Suppose $X$ is a smooth projective variety whose homogeneous
coordinate ring $S_X$ is $S_2$. If $D$ is the divisor $(I,J)$ and $f$ is any
non-zero element of $I$, then $L(D)$ is the degree zero part of $${sat((f*J) :
I) \over f}.$$

Proposition. If $s = g/f$ is section of the divisor $D = (I,J)$ as above, then
the zero scheme of $s$ is defined by the ideal $$ sat(f I : g) : J.$$

Consider the divisor $2P$ on our curve $E$:

+-------------------------------------+
|i29 : D = 2 P                        |
|                                     |
|                         2           |
|o29 = Divisor{ideal (z, x ), ideal 1}|
|                                     |
|o29 : Divisor                        |
+-------------------------------------+

In this case, $I = (x^2, z)$, and $J = (1)$. Compute the vector space of
sections $L(2P)$:

+-------------------+
|i30 : I = D#0      |
|                   |
|                 2 |
|o30 = ideal (z, x )|
|                   |
|o30 : Ideal of SE  |
+-------------------+
|i31 : J = D#1      |
|                   |
|o31 = ideal 1      |
|                   |
|o31 : Ideal of SE  |
+-------------------+
|i32 : f = z        |
|                   |
|o32 = z            |
|                   |
|o32 : SE           |
+-------------------+

The degree 0 part in the proposition is the degree $d$ part of $sat((fJ) : I)$,
divided by $f$, where $d = deg f$.

We can use the command basis to obtain a vector space basis of a module or
ideal in a given degree and thus compute the global sections (For an
explanation of this use of the basis routine, see the tutorial on canonical
embeddings of plane curves and gonality)

+------------------------------------------------+
|i33 : LD = basis(degree f, purify1S2((f*J) : I))|
|                                                |
|o33 = {1} | 1 0 |                               |
|      {1} | 0 1 |                               |
|                                                |
|o33 : Matrix                                    |
+------------------------------------------------+
|i34 : LD = super (LD ** (ring target LD))       |
|                                                |
|o34 = | z x |                                   |
|                                                |
|               1       2                        |
|o34 : Matrix SE  <-- SE                         |
+------------------------------------------------+

so the vector space $L(2P)$ is generated by $1=z/z$, and $x/z$. Since $J =
(1)$, the zero locus of the section $(z+x)/z$ is defined by the ideal

+------------------------------------+
|i35 : imI = purify1S2(((z+x)*I) : z)|
|                                    |
|                     2     2        |
|o35 = ideal (x + z, y  - 4z )       |
|                                    |
|o35 : Ideal of SE                   |
+------------------------------------+

and its degree is:

+----------------+
|i36 : degree imI|
|                |
|o36 = 2         |
+----------------+

Let's now package this into a routine globalSections which takes an argument D
of class Divisor, and computes a basis of $L(D)$, represented as fractions with
a common denominator. The output is a row vector of the numerators, followed by
the denominator.

+--------------------------------------------------------------+
|i37 : globalSections = method()                               |
|                                                              |
|o37 = globalSections                                          |
|                                                              |
|o37 : MethodFunction                                          |
+--------------------------------------------------------------+
|i38 : globalSections Divisor := (D) -> (                      |
|          -- First let's grab the parts (I,J) of D.           |
|          I := D#0;                                           |
|          J := D#1;                                           |
|          -- Let 'f' be the first element of the              |
|          -- matrix of generators of the ideal I.             |
|          f := (gens I)_(0,0);                                |
|          -- Now compute the basis of global sections         |
|          -- just as above                                    |
|          LD := basis(degree f, purify1S2((f*J) : I));        |
|          LD = super (LD ** (ring target LD));                |
|          -- Return both this vector space and the denominator|
|          {LD, f});                                           |
+--------------------------------------------------------------+

Another important task is to find the ideal of zeros of a section $s = f/g$ of
a divisor $D$.

+---------------------------------+
|i39 : sectionIdeal = (f,g,D) -> (|
|          I := D#0;              |
|          J := D#1;              |
|          purify1S2((f*I):g) : J |
|          );                     |
+---------------------------------+

Let's find the image of the elliptic curve $E$ under the linear system $4P$. To
do this we define a ring homomorphism from the global sections with the command
map. Its kernel defines the image of $E$.

+----------------------------------------------+
|i40 : D = 4 P                                 |
|                                              |
|                      2                       |
|o40 = Divisor{ideal (z , x*z), ideal 1}       |
|                                              |
|o40 : Divisor                                 |
+----------------------------------------------+
|i41 : L = globalSections D                    |
|                                              |
|                         2                    |
|o41 = {| xz yz z2 x2 |, z }                   |
|                                              |
|o41 : List                                    |
+----------------------------------------------+
|i42 : phi = map(SE, ZZ/31991[a..d], L#0)      |
|                                              |
|                                     2   2    |
|o42 = map (SE, KK[a..d], {x*z, y*z, z , x })  |
|                                              |
|o42 : RingMap SE <-- KK[a..d]                 |
+----------------------------------------------+
|i43 : ker phi                                 |
|                                              |
|              2                       2       |
|o43 = ideal (b  + 3a*c - a*d - 2c*d, a  - c*d)|
|                                              |
|o43 : Ideal of KK[a..d]                       |
+----------------------------------------------+

The image in $\PP^3$ is a complete intersection of two quadrics: the elliptic
normal curve in $\PP^3$.

For a less obvious example, consider the divisor $4P - R$, which is not
effective. Since it has degree 3 as a divisor on an elliptic curve, the Riemann
Roch theorem tells us that it is equivalent to an effective divisor; in fact
that it has  three sections. We can check this as follows:

+--------------------------------------------------------------------+
|i44 : D = 4 P - R                                                   |
|                                                                    |
|                      2                                             |
|o44 = Divisor{ideal (z , x*z), ideal (y, x)}                        |
|                                                                    |
|o44 : Divisor                                                       |
+--------------------------------------------------------------------+
|i45 : L = globalSections D                                          |
|                                                                    |
|                      2                                             |
|o45 = {| yz xz x2 |, z }                                            |
|                                                                    |
|o45 : List                                                          |
+--------------------------------------------------------------------+
|i46 : II = sectionIdeal(y*z+x*z+x^2, z^2, D)                        |
|                                                                    |
|              2                  2                2   2             |
|o46 = ideal (y  + 3x*z + y*z + 3z , x*y + x*z - 3z , x  + x*z + y*z)|
|                                                                    |
|o46 : Ideal of SE                                                   |
+--------------------------------------------------------------------+
|i47 : degree II                                                     |
|                                                                    |
|o47 = 3                                                             |
+--------------------------------------------------------------------+

D. Linear Equivalence

Testing whether two divisors $E$ and $F$ are linearly equivalent boils down to
testing whether $D = E-F$ is principal and thus linearly equivalent to 0.

One method to determine whether $D$ is principal is to compute the global
sections of $D$. A divisor $D$ is principal iff $L(D)$ has dimension one, and
the zero locus of its generator is the empty set.

For example, on the elliptic curve $E$, consider $P - R$:

+--------------------------+
|i48 : globalSections (P-R)|
|                          |
|o48 = {0, z}              |
|                          |
|o48 : List                |
+--------------------------+

$P-R$ has no global sections, so it is not equivalent to 0. Now consider $2 P -
2 R$

+-------------------------------------------+
|i49 : D = 2 P - 2 R                        |
|                                           |
|                         2              2  |
|o49 = Divisor{ideal (z, x ), ideal (x, y )}|
|                                           |
|o49 : Divisor                              |
+-------------------------------------------+
|i50 : LB = globalSections D                |
|                                           |
|o50 = {| x |, z}                           |
|                                           |
|o50 : List                                 |
+-------------------------------------------+

Since the divisor $D = 2P-2R$ has degree 0 and has a section, $D$ is linearly
equivalent to 0. The result shows that the rational function $x/z$ has divisor
$2P-2R$.

To check that a divisor of unknown degree is equivalent to 0, we attempt to
find a section and show it does not vanish anywhere. We include this in the
routine below.

Remember that in this tutorial we are assuming that $S_X$ is $S_2$ and that $X$
is smooth.  These computations are easily modified in the non-$S_2$ case.  See
the corresponding tutorial, once it is written!

+-----------------------------------------------------------------+
|i51 : linearlyEquivalent = (D,E) -> (                            |
|          F := normalForm(D-E);                                  |
|          LB := globalSections F;                                |
|          L := LB#0;                                             |
|          -- L is the matrix of numerators. Thus numgens source L|
|          -- is the dimension of the space of global sections.   |
|          if numgens source L != 1                               |
|          then false                                             |
|          else (                                                 |
|              R := ring L;                                       |
|              V := sectionIdeal(L_(0,0), LB#1, F);               |
|              if V == ideal(1_R)                                 |
|                then L_(0,0)/LB#1                                |
|                else false)                                      |
|          );                                                     |
+-----------------------------------------------------------------+

We get the same answers as before:

+----------------------------------+
|i52 : linearlyEquivalent(P,R)     |
|                                  |
|o52 = false                       |
+----------------------------------+
|i53 : linearlyEquivalent(2 P, 2 R)|
|                                  |
|      x                           |
|o53 = -                           |
|      z                           |
|                                  |
|o53 : frac SE                     |
+----------------------------------+

We now look at the group law on the cubic: We take the point $P$ to be 0; we
can then identify the natural group of divisor classes of degree 0 with the set
of points on the curve. With this identification, the group law $++$ on points
of the curve is defined by: $R ++ S =$ the unique point $T$ for which the
divisor $(R-P)+(S-P)$ is linearly equivalent to $(T-P)$. i.e. $R ++ S := $
unique effective divisor in $R+S-P$.

What we need to do is: given a divisor $R+S-P$, find an effective divisor
equivalent to it.

+-------------------------------------------------------+
|i54 : effective = (D) -> (                             |
|          LB := globalSections D;                      |
|          L := LB#0;  -- the matrix of numerators      |
|          if numgens source L == 0                     |
|          then error(toString D + " is not effective") |
|          else divisor sectionIdeal(L_(0,0), LB#1, D));|
+-------------------------------------------------------+
|i55 : effective(2 R - P)                               |
|                                                       |
|o55 = Divisor{ideal (z, x), ideal 1}                   |
|                                                       |
|o55 : Divisor                                          |
+-------------------------------------------------------+
|i56 : addition = (R,S) -> effective(R + S - P);        |
+-------------------------------------------------------+
|i57 : addition(R1,R2)                                  |
|                                                       |
|o57 = Divisor{ideal (y, x), ideal 1}                   |
|                                                       |
|o57 : Divisor                                          |
+-------------------------------------------------------+

Some points are in the torsion subgroup:

+----------------------------------------------+
|i58 : Q2 = addition(Q1, Q1)                   |
|                                              |
|o58 = Divisor{ideal (y, x - z), ideal 1}      |
|                                              |
|o58 : Divisor                                 |
+----------------------------------------------+
|i59 : Q3 = addition(Q2, Q1)                   |
|                                              |
|o59 = Divisor{ideal (y + 6z, x - 3z), ideal 1}|
|                                              |
|o59 : Divisor                                 |
+----------------------------------------------+
|i60 : Q4 = addition(Q3, Q1)                   |
|                                              |
|o60 = Divisor{ideal (z, x), ideal 1}          |
|                                              |
|o60 : Divisor                                 |
+----------------------------------------------+
|i61 : Q4a = addition(Q2,Q2)                   |
|                                              |
|o61 = Divisor{ideal (z, x), ideal 1}          |
|                                              |
|o61 : Divisor                                 |
+----------------------------------------------+

So the point $Q_1 = (3,6,1)$ is a point of order 4 in the group.

Exercise:  Write a routine that computes $n$ times a point in this group law.

E. The canonical divisor

The most important divisor class on a variety is the canonical class. For
example, consider the twisted cubic curve whose ideal is the ideal of $2\times
2$ minors of the ``catalecticant'' matrix

+-------------------------------------------------+
|i62 : S = ZZ/31991[a,b,c,d];                     |
+-------------------------------------------------+
|i63 : catalect = map(S^2, 3, (i,j)->S_(i+j))     |
|                                                 |
|o63 = | a b c |                                  |
|      | b c d |                                  |
|                                                 |
|              2      3                           |
|o63 : Matrix S  <-- S                            |
+-------------------------------------------------+
|i64 : IC = minors(2, catalect)                   |
|                                                 |
|                2                        2       |
|o64 = ideal (- b  + a*c, - b*c + a*d, - c  + b*d)|
|                                                 |
|o64 : Ideal of S                                 |
+-------------------------------------------------+
|i65 : SX = S/IC                                  |
|                                                 |
|o65 = SX                                         |
|                                                 |
|o65 : QuotientRing                               |
+-------------------------------------------------+

As a graded module, the canonical class is given as $K_X = Ext^c(S_X,
S(-r-1))$, where $c = codim X$, $X \subset \PP^r$, and $S = k[x_0,\ldots,x_r]$
is the polynomial ring.

+------------------------------------------------+
|i66 : KX = Ext^2(coker gens IC,S^{-4})          |
|                                                |
|o66 = cokernel {1} | -c b  -a |                 |
|               {1} | d  -c b  |                 |
|                                                |
|                             2                  |
|o66 : S-module, quotient of S                   |
+------------------------------------------------+
|i67 : canpres = substitute(presentation(KX), SX)|
|                                                |
|o67 = {1} | -c b  -a |                          |
|      {1} | d  -c b  |                          |
|                                                |
|               2       3                        |
|o67 : Matrix SX  <-- SX                         |
+------------------------------------------------+
|i68 : betti canpres                             |
|                                                |
|             0 1                                |
|o68 = total: 2 3                                |
|          1: 2 3                                |
|                                                |
|o68 : BettiTally                                |
+------------------------------------------------+

Thus we need a routine that takes a rank 1 torsion free module over a domain
and finds an ideal isomorphic to it. We wish to compute homomorphisms from the
canonical module into $S_X$, and take the divisor whose first ideal is the
image of a homomorphism of non-negative degree, and whose second ideal is an
arbitrary nonzero element of $S_X$ whose degree is equal to the degree of the
homomorphism. First we find a homomorphism of lowest degree:

+------------------------------------------------+
|i69 : I1 = transpose (syz transpose canpres)_{0}|
|                                                |
|o69 = | d c |                                   |
|                                                |
|               1       2                        |
|o69 : Matrix SX  <-- SX                         |
+------------------------------------------------+

The degree is

+------------------------------------+
|i70 : dg = (degrees (target I1))_0_0|
|                                    |
|o70 = 0                             |
+------------------------------------+

We need to balance the degree dg with a power of the first nonzero generator of
the ring. This is done in the following packaged version.

+-------------------------------------------------------------+
|i71 : divisorFromModule = M -> (                             |
|        -- given a module M, returns the divisor of the image|
|        -- of a nonzero homomorphism to R, suitably twisted. |
|        -- first get the presentation of M                   |
|          I1 := transpose (syz transpose presentation M)_{0};|
|        -- The degree is                                     |
|          d := (degrees target I1)_0_0;                      |
|        -- We need to balance the degree d with a power      |
|        -- of the first nonzero generator of the ring.       |
|          var1 := (compress vars ring M)_{0};                |
|        -- Now fix up the degrees.                           |
|          if d==0 then divisor ideal I1                      |
|          else if d>0 then divisor(                          |
|                        ideal (I1**dual(target I1)),         |
|                        ideal var1^d                         |
|                       )                                     |
|          else divisor ideal(                                |
|                     var1^(-d)**I1**dual target I1           |
|                     )                                       |
|      );                                                     |
+-------------------------------------------------------------+

We start from a module over the ring SX:

+------------------------------------+
|i72 : M = coker canpres             |
|                                    |
|o72 = cokernel {1} | -c b  -a |     |
|               {1} | d  -c b  |     |
|                                    |
|                               2    |
|o72 : SX-module, quotient of SX     |
+------------------------------------+
|i73 : divisorFromModule M           |
|                                    |
|o73 = Divisor{ideal (d, c), ideal 1}|
|                                    |
|o73 : Divisor                       |
+------------------------------------+

Some tests:

+-------------------------------------------+
|i74 : use SX                               |
|                                           |
|o74 = SX                                   |
|                                           |
|o74 : QuotientRing                         |
+-------------------------------------------+
|i75 : divisorFromModule image matrix{{d^2}}|
|                                           |
|                              2            |
|o75 = Divisor{ideal 1, ideal a }           |
|                                           |
|o75 : Divisor                              |
+-------------------------------------------+
|i76 : divisorFromModule SX^{1}             |
|                                           |
|o76 = Divisor{ideal a, ideal 1}            |
|                                           |
|o76 : Divisor                              |
+-------------------------------------------+

Here is the canonical divisor routine in packaged form:

+---------------------------------------------------------------+
|i77 : canonicalDivisor= SX ->(                                 |
|        -- Given a ring SX, computes a canonical divisor for SX|
|        I := ideal presentation SX;                            |
|        S := ring I;                                           |
|        embcodim := codim I;                                   |
|        M := Ext^embcodim(coker gens I,S^{-numgens S});        |
|        M = coker substitute(presentation M, SX);              |
|        divisorFromModule M                                    |
|        );                                                     |
+---------------------------------------------------------------+

+------------------------------------+
|i78 : canonicalDivisor SX           |
|                                    |
|o78 = Divisor{ideal (d, c), ideal 1}|
|                                    |
|o78 : Divisor                       |
+------------------------------------+

There are other ways of computing the canonical class. Perhaps we have already
written a tutorial on this subject.

basic commutative algebra
*************************

This section includes tutorials showing how to do basic commutative algebra
constructions in Macaulay2. This section is being written by Mike Stillman, for
use with his Fall 2005 course: Math 634, Commutative algebra, at Cornell
University.  This course covers basic commutative algebra, at the level of
Atiyah-Macdonald, and Greuel-Pfister.

Macaulay2 examples corresponding to the Singular examples in the book by
Greuel-Pfister may also be found here.

Elementary uses of Groebner bases I. Math 634 Fall 2005
*******************************************************

-*- coding: utf-8 -*- In this tutorial we introduce a number of basic
operations using Gröbner bases, and at the same time become familiar with a
range of useful Macaulay2 constructs.

A. A first Gröbner basis

To compute the Gröbner basis of an ideal $(x^2y,xy^2+x^3)$ in the polynomial
ring in four variables we proceed as follows:

Our favorite field

+------------------+
|i1 : KK = ZZ/32003|
|                  |
|o1 = KK           |
|                  |
|o1 : QuotientRing |
+------------------+

The polynomial ring

+--------------------+
|i2 : R = KK[x,y,z,w]|
|                    |
|o2 = R              |
|                    |
|o2 : PolynomialRing |
+--------------------+

and the ideal

+-------------------------------+
|i3 : I = ideal(x^2*y,x*y^2+x^3)|
|                               |
|             2    3      2     |
|o3 = ideal (x y, x  + x*y )    |
|                               |
|o3 : Ideal of R                |
+-------------------------------+

now the punch line:

+-----------------------+
|i4 : J = gens gb I     |
|                       |
|o4 = | x2y x3+xy2 xy3 ||
|                       |
|             1      3  |
|o4 : Matrix R  <-- R   |
+-----------------------+

This is the Gröbner basis of $I$ under the graded reverse lexicographic order.
In Macaulay2, monomial orders are associated with a polynomial ring. For
example, the lexicographic order is specified using:

+---------------------------------------+
|i5 : R = KK[x,y,z,w,MonomialOrder=>Lex]|
|                                       |
|o5 = R                                 |
|                                       |
|o5 : PolynomialRing                    |
+---------------------------------------+
|i6 : I = substitute(I,R)               |
|                                       |
|             2    3      2             |
|o6 = ideal (x y, x  + x*y )            |
|                                       |
|o6 : Ideal of R                        |
+---------------------------------------+
|i7 : gens gb I                         |
|                                       |
|o7 = | xy3 x2y x3+xy2 |                |
|                                       |
|             1      3                  |
|o7 : Matrix R  <-- R                   |
+---------------------------------------+

The Gröbner basis is the same, since this is a small example.  The polynomials
are sorted in ascending monomial order by their lead terms, but otherwise the
two Gröbner bases are the same here.

B. Random regular sequences

An interesting and illustrative open problem is to understand the initial ideal
(and the Gröbner basis) of a ``generic'' regular sequence.  To study a very
simple case we take a matrix of 2 random forms in a polynomial ring in 3
variables:

+-----------------------------------------------------------------------------+
|i8 : R = KK[x,y,z]                                                           |
|                                                                             |
|o8 = R                                                                       |
|                                                                             |
|o8 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i9 : F = random(R^1, R^{-2,-3})                                              |
|                                                                             |
|o9 = | 107x2+4376xy+3187y2-5570xz+3783yz-5307z2                              |
|     ------------------------------------------------------------------------|
|     8570x3-15344x2y-10480xy2-8251y3+8444x2z+10359xyz+2653y2z-7464xz2+5071yz2|
|     ------------------------------------------------------------------------|
|     -6203z3 |                                                               |
|                                                                             |
|             1      2                                                        |
|o9 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+

makes $F$ into a $1 \times 2$ matrix whose elements have degrees $2,3$ (that
is, $F$ is a random map to the free module $R^1$, which has its one generator
in the (default) degree, $0$, from the free module with generators in the
listed degrees, $\{2,3\}$).  We now can compute

+-----------------------------------------------------------------------------+
|i10 : GB = gens gb F                                                         |
|                                                                             |
|o10 = | x2-9231xy+3918y2+6528xz+11700yz-4536z2                               |
|      -----------------------------------------------------------------------|
|      xy2+10930y3+4639xyz+2060y2z+1339xz2+14261yz2+12812z3                   |
|      -----------------------------------------------------------------------|
|      y4-15921y3z+15391xyz2-3537y2z2-14321xz3+7226yz3-14465z4 |              |
|                                                                             |
|              1      3                                                       |
|o10 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i11 : LT = leadTerm GB                                                       |
|                                                                             |
|o11 = | x2 xy2 y4 |                                                          |
|                                                                             |
|              1      3                                                       |
|o11 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i12 : betti LT                                                               |
|                                                                             |
|             0 1                                                             |
|o12 = total: 1 3                                                             |
|          0: 1 .                                                             |
|          1: . 1                                                             |
|          2: . 1                                                             |
|          3: . 1                                                             |
|                                                                             |
|o12 : BettiTally                                                             |
+-----------------------------------------------------------------------------+

betti is a routine that displays degrees of generators and also in free
resolutions (which we will learn about later). In this case, the output shows
that there are Gröbner basis elements of degrees 2,3, and 4.  This result is
dependent on the monomial order in the ring $R$; for example we could take the
lexicographic order

+-----------------------------------------+
|i13 : R = KK[x,y,z, MonomialOrder => Lex]|
|                                         |
|o13 = R                                  |
|                                         |
|o13 : PolynomialRing                     |
+-----------------------------------------+

(see help MonomialOrder for other possibilities). We get

+-----------------------------------------------------------------------------+
|i14 : F = random(R^1, R^{-2,-3})                                             |
|                                                                             |
|o14 = | 12365x2-13508xy-9480xz-11950y2+8231yz+5864z2                         |
|      -----------------------------------------------------------------------|
|      5026x3+10259x2y-7501x2z+9534xy2-7216xyz-10125xz2+7256y3-5321y2z+6230yz2|
|      -----------------------------------------------------------------------|
|      +9033z3 |                                                              |
|                                                                             |
|              1      2                                                       |
|o14 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i15 : GB = gens gb F                                                         |
|                                                                             |
|o15 = | y6+10526y5z-2376y4z2+5954y3z3+4992y2z4+12208yz5-83z6                 |
|      -----------------------------------------------------------------------|
|      xz4+9709y5-12534y4z+5436y3z2-12036y2z3+754yz4+9317z5                   |
|      -----------------------------------------------------------------------|
|      xyz2-904xz3+1531y4-7686y3z-14508y2z2+11404yz3-7z4                      |
|      -----------------------------------------------------------------------|
|      xy2+12914xyz+3687xz2+3377y3+2831y2z-15591yz2-13423z3                   |
|      -----------------------------------------------------------------------|
|      x2-5589xy-3676xz-1528y2-9542yz+10889z2 |                               |
|                                                                             |
|              1      5                                                       |
|o15 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i16 : LT = leadTerm GB                                                       |
|                                                                             |
|o16 = | y6 xz4 xyz2 xy2 x2 |                                                 |
|                                                                             |
|              1      5                                                       |
|o16 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i17 : betti LT                                                               |
|                                                                             |
|             0 1                                                             |
|o17 = total: 1 5                                                             |
|          0: 1 .                                                             |
|          1: . 1                                                             |
|          2: . 1                                                             |
|          3: . 1                                                             |
|          4: . 1                                                             |
|          5: . 1                                                             |
|                                                                             |
|o17 : BettiTally                                                             |
+-----------------------------------------------------------------------------+

and there are Gröbner basis elements of degrees $2,3,4,5,6.$

C. Division With Remainder

A major application of Gröbner bases is to decide whether an element is in a
given ideal, and whether two elements reduce to the same thing modulo an ideal.
For example, everyone knows that the trace of a nilpotent matrix is 0. We can
produce an ideal $I$ that defines the variety $X$ of nilpotent $3 \times 3$
matrices by taking the cube of a generic matrix and setting the entries equal
to zero.  Here's how:

+-----------------------------------------------------------------------------+
|i18 : R = KK[a..i]                                                           |
|                                                                             |
|o18 = R                                                                      |
|                                                                             |
|o18 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i19 : M = genericMatrix(R,a,3,3)                                             |
|                                                                             |
|o19 = | a d g |                                                              |
|      | b e h |                                                              |
|      | c f i |                                                              |
|                                                                             |
|              3      3                                                       |
|o19 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i20 : N = M^3                                                                |
|                                                                             |
|o20 = | a3+2abd+bde+2acg+bfg+cdh+cgi                                         |
|      | a2b+b2d+abe+be2+bcg+ach+ceh+bfh+chi                                  |
|      | a2c+bcd+abf+bef+c2g+cfh+aci+bfi+ci2                                  |
|      -----------------------------------------------------------------------|
|      a2d+bd2+ade+de2+cdg+afg+efg+dfh+fgi a2g+bdg+cg2+adh+deh+fgh+agi+dhi+gi2|
|      abd+2bde+e3+bfg+cdh+2efh+fhi        abg+beg+bdh+e2h+cgh+fh2+bgi+ehi+hi2|
|      acd+cde+bdf+e2f+cfg+f2h+cdi+efi+fi2 acg+bfg+cdh+efh+2cgi+2fhi+i3       |
|      -----------------------------------------------------------------------|
|      |                                                                      |
|      |                                                                      |
|      |                                                                      |
|                                                                             |
|              3      3                                                       |
|o20 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i21 : I = flatten N                                                          |
|                                                                             |
|o21 = | a3+2abd+bde+2acg+bfg+cdh+cgi a2b+b2d+abe+be2+bcg+ach+ceh+bfh+chi     |
|      -----------------------------------------------------------------------|
|      a2c+bcd+abf+bef+c2g+cfh+aci+bfi+ci2 a2d+bd2+ade+de2+cdg+afg+efg+dfh+fgi|
|      -----------------------------------------------------------------------|
|      abd+2bde+e3+bfg+cdh+2efh+fhi acd+cde+bdf+e2f+cfg+f2h+cdi+efi+fi2       |
|      -----------------------------------------------------------------------|
|      a2g+bdg+cg2+adh+deh+fgh+agi+dhi+gi2 abg+beg+bdh+e2h+cgh+fh2+bgi+ehi+hi2|
|      -----------------------------------------------------------------------|
|      acg+bfg+cdh+efh+2cgi+2fhi+i3 |                                         |
|                                                                             |
|              1      9                                                       |
|o21 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+

(actually this produces a 1 x 9 matrix of of forms, not the ideal: J = ideal I;
the matrix will be more useful to us). But the trace is not in $I$!  This is
obvious from the fact that the trace has degree $1$, but the polynomials in $I$
are of degree $3$. We could also check by division with remainder:

+-------------------------------------------------+
|i22 : Tr = trace M                               |
|                                                 |
|o22 = a + e + i                                  |
|                                                 |
|o22 : R                                          |
+-------------------------------------------------+
|i23 : Tr //I  -- the quotient, which is 0        |
|                                                 |
|o23 = 0                                          |
|                                                 |
|              9      1                           |
|o23 : Matrix R  <-- R                            |
+-------------------------------------------------+
|i24 : Tr % I  -- the remainder, which is Tr again|
|                                                 |
|o24 = a + e + i                                  |
|                                                 |
|o24 : R                                          |
+-------------------------------------------------+

(Here Tr is an element of $R$, not a matrix. We could do the same thing with a
$1 \times 1$ matrix with Tr as its element.) This is of course because the
entries of $I$ do NOT generate the ideal of all forms vanishing on $X$ -- this
we may find with J = radical ideal I, (but this takes a while: see the
documentation for radical on a faster way to find this) which shows that the
radical is generated by the trace, the determinant, and the sum of the
principal $2 \times 2$ minors, that is, by the coefficients of the
characteristic polynomial. In particular, we can try the powers of the radical:

+-----------------------------------------------------------------------------+
|i25 : Tr^2 % I                                                               |
|                                                                             |
|       2           2                  2                                      |
|o25 = a  + 2a*e + e  + 2a*i + 2e*i + i                                       |
|                                                                             |
|o25 : R                                                                      |
+-----------------------------------------------------------------------------+
|i26 : Tr^3 % I                                                               |
|                                                                             |
|        2                 2     3                                2           |
|o26 = 3a e + 3b*d*e + 3a*e  + 3e  + 3b*f*g + 3c*d*h + 6e*f*h + 3a i + 6a*e*i |
|      -----------------------------------------------------------------------|
|          2                          2       2     3                         |
|      + 3e i + 3c*g*i + 6f*h*i + 3a*i  + 3e*i  + 3i                          |
|                                                                             |
|o26 : R                                                                      |
+-----------------------------------------------------------------------------+
|i27 : Tr^4 % I                                                               |
|                                                                             |
|        2 2         2       3     4                                          |
|o27 = 6a e  + 6b*d*e  + 6a*e  + 6e  + 6b*e*f*g + 6c*d*e*h - 6b*d*f*h +       |
|      -----------------------------------------------------------------------|
|                    2                   2 2      2                       2   |
|      6a*e*f*h + 12e f*h - 6c*f*g*h - 6f h  + 12a e*i + 12b*d*e*i + 12a*e i +|
|      -----------------------------------------------------------------------|
|         3                                                               2 2 |
|      12e i + 12c*e*g*i + 6b*f*g*i + 6c*d*h*i + 6a*f*h*i + 36e*f*h*i + 6a i  |
|      -----------------------------------------------------------------------|
|               2     2 2         2          2       3        3     4         |
|      + 12a*e*i  + 6e i  + 6c*g*i  + 12f*h*i  + 6a*i  + 12e*i  + 6i          |
|                                                                             |
|o27 : R                                                                      |
+-----------------------------------------------------------------------------+
|i28 : Tr^5 % I                                                               |
|                                                                             |
|         2 2           2         3       4         2         2               |
|o28 = 30a e i + 30b*d*e i + 30a*e i + 30e i + 30c*e g*i + 30a f*h*i +        |
|      -----------------------------------------------------------------------|
|                                     2                         2 2           |
|      30b*d*f*h*i + 60a*e*f*h*i + 90e f*h*i + 30c*f*g*h*i + 30f h i +        |
|      -----------------------------------------------------------------------|
|         2   2            2        2 2      3 2            2            2    |
|      30a e*i  + 30b*d*e*i  + 30a*e i  + 30e i  + 30c*e*g*i  + 60a*f*h*i  +  |
|      -----------------------------------------------------------------------|
|                2      2 3          3          3      2 3          3         |
|      120e*f*h*i  + 30a i  + 30b*d*i  + 30a*e*i  + 30e i  + 30c*g*i  +       |
|      -----------------------------------------------------------------------|
|             3        4        4      5                                      |
|      90f*h*i  + 30a*i  + 30e*i  + 30i                                       |
|                                                                             |
|o28 : R                                                                      |
+-----------------------------------------------------------------------------+
|i29 : Tr^6 % I                                                               |
|                                                                             |
|         2 2 2          2 2        3 2      4 2        2   2      2     2    |
|o29 = 90a e i  + 90b*d*e i  + 90a*e i  + 90e i  + 90c*e g*i  + 90a f*h*i  +  |
|      -----------------------------------------------------------------------|
|                 2               2       2     2              2      2 2 2   |
|      90b*d*f*h*i  + 180a*e*f*h*i  + 270e f*h*i  + 90c*f*g*h*i  + 90f h i  + |
|      -----------------------------------------------------------------------|
|         2   3            3        2 3      3 3            3             3   |
|      90a e*i  + 90b*d*e*i  + 90a*e i  + 90e i  + 90c*e*g*i  + 180a*f*h*i  + |
|      -----------------------------------------------------------------------|
|                3      2 4          4          4      2 4          4         |
|      360e*f*h*i  + 90a i  + 90b*d*i  + 90a*e*i  + 90e i  + 90c*g*i  +       |
|      -----------------------------------------------------------------------|
|              4        5        5      6                                     |
|      270f*h*i  + 90a*i  + 90e*i  + 90i                                      |
|                                                                             |
|o29 : R                                                                      |
+-----------------------------------------------------------------------------+
|i30 : Tr^7 % I                                                               |
|                                                                             |
|o30 = 0                                                                      |
|                                                                             |
|o30 : R                                                                      |
+-----------------------------------------------------------------------------+

The seventh power is the first one in the ideal!  (Bernard Mourrain has worked
out a formula for which power in general.) In this case

+-----------------------------------------------------------------------------+
|i31 : Tr^6 // I                                                              |
|                                                                             |
|o31 = {3} | a3+6a2e+3bde+15ae2+22e3+6efh+6a2i+30aei+60e2i+6fhi+15ai2+60ei2+22|
|      {3} | 0                                                                |
|      {3} | 0                                                                |
|      {3} | -27abe-45be2+9ceh+30bfh-72abi-144bei+75chi                       |
|      {3} | -2a3+15a2e+21bde+6ae2+e3+33bfg+9cdh-36afh+51efh+60a2i+72bdi+30aei|
|      {3} | 18abg+45beg+3a2h+9bdh-21aeh+3e2h+9cgh+36fh2+114bgi-135ahi-39ehi+3|
|      {3} | 18ace+6abf-36bef-18cfh+66aci+36cei-57bfi+132ci2                  |
|      {3} | -3a2f-39bdf+75aef-12e2f+9cfg-36f2h-66cdi+135afi+51efi+69fi2      |
|      {3} | -2a3-18abd-30a2e-60bde-30ae2-44e3-18ceg-33bfg-9cdh+18afh-93efh-75|
|      -----------------------------------------------------------------------|
|      i3                                                  |                  |
|                                                          |                  |
|                                                          |                  |
|                                                          |                  |
|      +6e2i+66cgi+147fhi-30ai2-75ei2-26i3                 |                  |
|      6hi2                                                |                  |
|                                                          |                  |
|                                                          |                  |
|      a2i-90bdi-60aei-75e2i-66cgi-171fhi-84ai2-84ei2-89i3 |                  |
|                                                                             |
|              9      1                                                       |
|o31 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+

is not 0.  It is a matrix that makes the following true:

+------------------------------------------+
|i32 : Tr^6 == I * (Tr^6 // I) + (Tr^6 % I)|
|                                          |
|o32 = true                                |
+------------------------------------------+

D. Elimination Theory

Computing the elimination ideal $I \cap k[xi, \ldots, xn]$ is one of the most
important applications of Gröbner bases.

+------------------------------------------------------------------+
|i33 : R = KK[t,y,z,MonomialOrder=>Lex]                            |
|                                                                  |
|o33 = R                                                           |
|                                                                  |
|o33 : PolynomialRing                                              |
+------------------------------------------------------------------+
|i34 : I = ideal(y-(t^2+t+1), z-(t^3+1))                           |
|                                                                  |
|                2                 3                               |
|o34 = ideal (- t  - t + y - 1, - t  + z - 1)                      |
|                                                                  |
|o34 : Ideal of R                                                  |
+------------------------------------------------------------------+
|i35 : GB = gens gb I                                              |
|                                                                  |
|o35 = | y3-3y2-3yz+6y-z2+4z-4 tz-2t-y2+3y+2z-4 ty-y-z+2 t2+t-y+1 ||
|                                                                  |
|              1      4                                            |
|o35 : Matrix R  <-- R                                             |
+------------------------------------------------------------------+
|i36 : F = GB_(0,0)                                                |
|                                                                  |
|       3     2                2                                   |
|o36 = y  - 3y  - 3y*z + 6y - z  + 4z - 4                          |
|                                                                  |
|o36 : R                                                           |
+------------------------------------------------------------------+
|i37 : substitute(F, {y =>t^2+t+1, z=>t^3+1})                      |
|                                                                  |
|o37 = 0                                                           |
|                                                                  |
|o37 : R                                                           |
+------------------------------------------------------------------+

F is the polynomial that gives an algebraic relation between $t^2+t+1$ and
$t^3+1$. Another way to accomplish this in Macaulay2 is to use the eliminate
function.  In this case, the monomial order of the ring is not important.

+-----------------------------------------------+
|i38 : R = KK[y,z,t]                            |
|                                               |
|o38 = R                                        |
|                                               |
|o38 : PolynomialRing                           |
+-----------------------------------------------+
|i39 : I = substitute(I,R)                      |
|                                               |
|                2                 3            |
|o39 = ideal (- t  + y - t - 1, - t  + z - 1)   |
|                                               |
|o39 : Ideal of R                               |
+-----------------------------------------------+
|i40 : eliminate(I,t)                           |
|                                               |
|             3     2           2               |
|o40 = ideal(y  - 3y  - 3y*z - z  + 6y + 4z - 4)|
|                                               |
|o40 : Ideal of R                               |
+-----------------------------------------------+

Yet another method is to use ring maps.

+-----------------------------------------------+
|i41 : A = KK[t]                                |
|                                               |
|o41 = A                                        |
|                                               |
|o41 : PolynomialRing                           |
+-----------------------------------------------+
|i42 : B = KK[y,z]                              |
|                                               |
|o42 = B                                        |
|                                               |
|o42 : PolynomialRing                           |
+-----------------------------------------------+
|i43 : G = map(A,B,{t^2+t+1, t^3+1})            |
|                                               |
|                   2           3               |
|o43 = map (A, B, {t  + t + 1, t  + 1})         |
|                                               |
|o43 : RingMap A <-- B                          |
+-----------------------------------------------+
|i44 : kernel G                                 |
|                                               |
|             3     2           2               |
|o44 = ideal(y  - 3y  - 3y*z - z  + 6y + 4z - 4)|
|                                               |
|o44 : Ideal of B                               |
+-----------------------------------------------+

E. Intersections and ideal quotients

An interesting problem is to investigate ideals of the form $I = (x^d, y^d,
z^d, f)$, where $f$ is a polynomial, in three variables $x,y,z$.  First, let's
compute the ideal quotient for an example, by using the method given in class.

+-----------------------------------------------------------------------------+
|i45 : R = KK[t,x,y,z]                                                        |
|                                                                             |
|o45 = R                                                                      |
|                                                                             |
|o45 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i46 : I = ideal(x^3,y^3,z^3)                                                 |
|                                                                             |
|              3   3   3                                                      |
|o46 = ideal (x , y , z )                                                     |
|                                                                             |
|o46 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i47 : F = x+y+z                                                              |
|                                                                             |
|o47 = x + y + z                                                              |
|                                                                             |
|o47 : R                                                                      |
+-----------------------------------------------------------------------------+
|i48 : L = t*I + (1-t)*ideal(F)                                               |
|                                                                             |
|                3     3     3                                                |
|o48 = ideal (t*x , t*y , t*z , - t*x - t*y - t*z + x + y + z)                |
|                                                                             |
|o48 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i49 : L1 = eliminate(L,t)                                                    |
|                                                                             |
|                3      3    4     3    4    3    3     4    3      3        3|
|o49 = ideal (x*z  + y*z  + z , x*y  + y  + y z, x y + y  - x z + 2y z - 2y*z |
|      -----------------------------------------------------------------------|
|         4   4    4     3      3        3    4   3 2    3 2     2 3       4  |
|      - z , x  - y  + 2x z - 2y z + 2y*z  + z , x z  + y z  + 3y z  + 3y*z  +|
|      -----------------------------------------------------------------------|
|       5                                                                     |
|      z )                                                                    |
|                                                                             |
|o49 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i50 : gens gb L1                                                             |
|                                                                             |
|o50 = | xz3+yz3+z4 xy3+y4+y3z x3y+y4-x3z+2y3z-2yz3-z4 x4-y4+2x3z-2y3z+2yz3+z4|
|      -----------------------------------------------------------------------|
|      x3z2+y3z2+3y2z3+3yz4+z5 |                                              |
|                                                                             |
|              1      5                                                       |
|o50 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+

Each of these is divisible by F:

+----------------------+
|i51 : (gens L1) % F   |
|                      |
|o51 = 0               |
|                      |
|              1      5|
|o51 : Matrix R  <-- R |
+----------------------+

Divide by F.

+-----------------------------------------------------------------------------+
|i52 : J = ideal ((gens L1)//F)                                               |
|                                                                             |
|              3   3   2       2    3    2     2       2      2    3   3    2 |
|o52 = ideal (z , y , x y - x*y  + y  - x z + y z + x*z  - y*z  - z , x  - x y|
|      -----------------------------------------------------------------------|
|           2    3    2     2       2      2    3   2 2        2    2 2      3|
|      + x*y  - y  + x z - y z - x*z  + y*z  + z , x z  - x*y*z  + y z  - x*z |
|      -----------------------------------------------------------------------|
|            3    4                                                           |
|      + 2y*z  + z )                                                          |
|                                                                             |
|o52 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i53 : mingens J                                                              |
|                                                                             |
|o53 = | z3 y3 x2y-xy2-x2z+y2z+xz2-yz2 x3 x2z2-xyz2+y2z2 |                    |
|                                                                             |
|              1      5                                                       |
|o53 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i54 : betti oo                                                               |
|                                                                             |
|             0 1                                                             |
|o54 = total: 1 5                                                             |
|          0: 1 .                                                             |
|          1: . .                                                             |
|          2: . 4                                                             |
|          3: . 1                                                             |
|                                                                             |
|o54 : BettiTally                                                             |
+-----------------------------------------------------------------------------+

J is defined by 5 equations: the original 3, another cubic and also a quartic.
(oo is the previous output). Now, let's do this the easier way.

+-----------------------------------------------------------------------------+
|i55 : R = KK[x,y,z]                                                          |
|                                                                             |
|o55 = R                                                                      |
|                                                                             |
|o55 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i56 : I = ideal(x^3,y^3,z^3)                                                 |
|                                                                             |
|              3   3   3                                                      |
|o56 = ideal (x , y , z )                                                     |
|                                                                             |
|o56 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i57 : F = x+y+z                                                              |
|                                                                             |
|o57 = x + y + z                                                              |
|                                                                             |
|o57 : R                                                                      |
+-----------------------------------------------------------------------------+
|i58 : J = I : F                                                              |
|                                                                             |
|              3   3   2       2    2     2       2      2   3   2 2        2 |
|o58 = ideal (z , y , x y - x*y  - x z + y z + x*z  - y*z , x , x z  - x*y*z  |
|      -----------------------------------------------------------------------|
|         2 2                                                                 |
|      + y z )                                                                |
|                                                                             |
|o58 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i59 : betti J                                                                |
|                                                                             |
|             0 1                                                             |
|o59 = total: 1 5                                                             |
|          0: 1 .                                                             |
|          1: . .                                                             |
|          2: . 4                                                             |
|          3: . 1                                                             |
|                                                                             |
|o59 : BettiTally                                                             |
+-----------------------------------------------------------------------------+
|i60 : transpose gens J                                                       |
|                                                                             |
|o60 = {-3} | z3                      |                                       |
|      {-3} | y3                      |                                       |
|      {-3} | x2y-xy2-x2z+y2z+xz2-yz2 |                                       |
|      {-3} | x3                      |                                       |
|      {-4} | x2z2-xyz2+y2z2          |                                       |
|                                                                             |
|              5      1                                                       |
|o60 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i61 : transpose gens gb J                                                    |
|                                                                             |
|o61 = {-3} | z3                      |                                       |
|      {-3} | y3                      |                                       |
|      {-3} | x2y-xy2-x2z+y2z+xz2-yz2 |                                       |
|      {-3} | x3                      |                                       |
|      {-4} | x2z2-xyz2+y2z2          |                                       |
|                                                                             |
|              5      1                                                       |
|o61 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+

Problem: how many generators can you obtain using this construction, where you
may try different positive integers $d$, and polynomials $f$?

F. Saturation

A very useful construction is the saturation of an ideal $I$ with respect to a
polynomial $f$, or another ideal $J$.

+-----------------------------------------------------------------------------+
|i62 : R = KK[t,a..f]                                                         |
|                                                                             |
|o62 = R                                                                      |
|                                                                             |
|o62 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i63 : I = ideal(a*b*c-d*e*f, a^2*b-c^2*d, a*f^2-d*b*c)                       |
|                                                                             |
|                             2     2                2                        |
|o63 = ideal (a*b*c - d*e*f, a b - c d, - b*c*d + a*f )                       |
|                                                                             |
|o63 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i64 : F = a*b*c*d*e*f                                                        |
|                                                                             |
|o64 = a*b*c*d*e*f                                                            |
|                                                                             |
|o64 : R                                                                      |
+-----------------------------------------------------------------------------+
|i65 : J = eliminate(I + ideal(t*F-1), t)                                     |
|                                                                             |
|              2     2            2              2   3                        |
|o65 = ideal (d e - a f, b*d*e - c f, b*c*d - a*f , c  - a*e*f, a*b*c - d*e*f,|
|      -----------------------------------------------------------------------|
|         2      2   2     2    3     4   2 2      3                          |
|      a*b  - c*f , a b - c d, b d - f , b c  - e*f )                         |
|                                                                             |
|o65 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i66 : transpose gens J                                                       |
|                                                                             |
|o66 = {-3} | d2e-a2f  |                                                      |
|      {-3} | bde-c2f  |                                                      |
|      {-3} | bcd-af2  |                                                      |
|      {-3} | c3-aef   |                                                      |
|      {-3} | abc-def  |                                                      |
|      {-3} | ab2-cf2  |                                                      |
|      {-3} | a2b-c2d  |                                                      |
|      {-4} | b3d-f4   |                                                      |
|      {-4} | b2c2-ef3 |                                                      |
|                                                                             |
|              9      1                                                       |
|o66 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+

There is a builtin routine in Macaulay2 for computing saturations:

+-----------------------------------------------------------------------------+
|i67 : R = KK[a..f]                                                           |
|                                                                             |
|o67 = R                                                                      |
|                                                                             |
|o67 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i68 : I = substitute(I,R)                                                    |
|                                                                             |
|                             2     2                2                        |
|o68 = ideal (a*b*c - d*e*f, a b - c d, - b*c*d + a*f )                       |
|                                                                             |
|o68 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i69 : F = product gens R                                                     |
|                                                                             |
|o69 = a*b*c*d*e*f                                                            |
|                                                                             |
|o69 : R                                                                      |
+-----------------------------------------------------------------------------+
|i70 : J' = saturate(I,F)                                                     |
|                                                                             |
|              2     2            2              2   3                        |
|o70 = ideal (d e - a f, b*d*e - c f, b*c*d - a*f , c  - a*e*f, a*b*c - d*e*f,|
|      -----------------------------------------------------------------------|
|         2      2   2     2    3     4   2 2      3                          |
|      a*b  - c*f , a b - c d, b d - f , b c  - e*f )                         |
|                                                                             |
|o70 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i71 : transpose gens J'                                                      |
|                                                                             |
|o71 = {-3} | d2e-a2f  |                                                      |
|      {-3} | bde-c2f  |                                                      |
|      {-3} | bcd-af2  |                                                      |
|      {-3} | c3-aef   |                                                      |
|      {-3} | abc-def  |                                                      |
|      {-3} | ab2-cf2  |                                                      |
|      {-3} | a2b-c2d  |                                                      |
|      {-4} | b3d-f4   |                                                      |
|      {-4} | b2c2-ef3 |                                                      |
|                                                                             |
|              9      1                                                       |
|o71 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+

modules in Macaulay2
********************

In this tutorial, we describe how to work with modules in Macaulay2.

A. Making modules from matrices

First, let's define a ring.

+------------------------------------+
|i1 : R = QQ[a..f];                  |
+------------------------------------+
|i2 : m = matrix{{a,b,d,e},{b,c,e,f}}|
|                                    |
|o2 = | a b d e |                    |
|     | b c e f |                    |
|                                    |
|             2      4               |
|o2 : Matrix R  <-- R                |
+------------------------------------+

Use standard notation for cokernels, images and kernels (coker, cokernel,
image, ker, kernel).

+----------------------------------------------+
|i3 : M = coker m                              |
|                                              |
|o3 = cokernel | a b d e |                     |
|              | b c e f |                     |
|                                              |
|                            2                 |
|o3 : R-module, quotient of R                  |
+----------------------------------------------+
|i4 : N = image m                              |
|                                              |
|o4 = image | a b d e |                        |
|           | b c e f |                        |
|                                              |
|                             2                |
|o4 : R-module, submodule of R                 |
+----------------------------------------------+
|i5 : K = kernel m                             |
|                                              |
|o5 = image {1} | cd-be  0      e2-df  ce-bf  ||
|           {1} | -bd+ae e2-df  0      -be+af ||
|           {1} | b2-ac  -ce+bf -be+af 0      ||
|           {1} | 0      cd-be  bd-ae  b2-ac  ||
|                                              |
|                             4                |
|o5 : R-module, submodule of R                 |
+----------------------------------------------+

Given a module, one can find its presentation matrix.

+-------------------------------------------------------+
|i6 : presentation M -- this is just the original matrix|
|                                                       |
|o6 = | a b d e |                                       |
|     | b c e f |                                       |
|                                                       |
|             2      4                                  |
|o6 : Matrix R  <-- R                                   |
+-------------------------------------------------------+
|i7 : presentation N -- this one requires computation   |
|                                                       |
|o7 = {1} | cd-be  0      e2-df  ce-bf  |               |
|     {1} | -bd+ae e2-df  0      -be+af |               |
|     {1} | b2-ac  -ce+bf -be+af 0      |               |
|     {1} | 0      cd-be  bd-ae  b2-ac  |               |
|                                                       |
|             4      4                                  |
|o7 : Matrix R  <-- R                                   |
+-------------------------------------------------------+

B. Submodules and quotients

To define a submodule $IN$ of a module $N$, where $I$ is an ideal, use

+--------------------------------------+
|i8 : ideal(a,b)*N                     |
|                                      |
|o8 = image | a2 ab ad ae ab b2 bd be ||
|           | ab ac ae af b2 bc be bf ||
|                                      |
|                             2        |
|o8 : R-module, submodule of R         |
+--------------------------------------+
|i9 : a*N + b*N                        |
|                                      |
|o9 = image | a2 ab ad ae ab b2 bd be ||
|           | ab ac ae af b2 bc be bf ||
|                                      |
|                             2        |
|o9 : R-module, submodule of R         |
+--------------------------------------+

In order to define a submodule of N generated by some elements of N, one way is
the following.

+---------------------------------------+
|i10 : N0 = image (a**N_{1}|N_{2}-N_{3})|
|                                       |
|o10 = image | ab d-e |                 |
|            | ac e-f |                 |
|                                       |
|                              2        |
|o10 : R-module, submodule of R         |
+---------------------------------------+

To understand what Macaulay2 is doing here, let's break this down.  N_{i}
defines a matrix $R^1 \to N$, which maps 1 to the i th generator of N. (See
Section XX below for more information about module homomorphisms).

+---------------------+
|i11 : N_{1}          |
|                     |
|o11 = {1} | 0 |      |
|      {1} | 1 |      |
|      {1} | 0 |      |
|      {1} | 0 |      |
|                     |
|                    1|
|o11 : Matrix N <-- R |
+---------------------+

One could use a*N_{1}, but it turns out that a ** N_{1} works better:

+---------------------+
|i12 : a ** N_{1}     |
|                     |
|o12 = {1} | 0 |      |
|      {1} | a |      |
|      {1} | 0 |      |
|      {1} | 0 |      |
|                     |
|                    1|
|o12 : Matrix N <-- R |
+---------------------+

Next, remember that the vertical bar concatenates matrices.

+------------------------------+
|i13 : a ** N_{1} | N_{2}-N_{3}|
|                              |
|o13 = {1} | 0 0  |            |
|      {1} | a 0  |            |
|      {1} | 0 1  |            |
|      {1} | 0 -1 |            |
|                              |
|                    2         |
|o13 : Matrix N <-- R          |
+------------------------------+

Now take the image of this matrix

+------------------------------------------+
|i14 : N0 = image(a ** N_{1} | N_{2}-N_{3})|
|                                          |
|o14 = image | ab d-e |                    |
|            | ac e-f |                    |
|                                          |
|                              2           |
|o14 : R-module, submodule of R            |
+------------------------------------------+

The main advantage for using ** rather than * is that ** preservers homogeneity
if possible.

+----------------------+
|i15 : isHomogeneous N0|
|                      |
|o15 = true            |
+----------------------+

Quotients are defined using standard mathematical notation.

+-------------------------------------------+
|i16 : Nbar = N/N0                          |
|                                           |
|o16 = subquotient (| a b d e |, | ab d-e |)|
|                   | b c e f |  | ac e-f | |
|                                           |
|                                2          |
|o16 : R-module, subquotient of R           |
+-------------------------------------------+

Notice that this returns a subquotient module.  We treat these later. Ideals
and modules are treated differently in Macaulay2 (and in commutative algebra in
general).  For example, asking for the dimension of an ideal I in a ring R
gives the dimension of the quotient R/I, but the dimension of the module I
gives a potentially very different answer. Use ideal and module to move between
the two.

+-------------------------------+
|i17 : I = ideal(a^2, a*b, c^2) |
|                               |
|              2        2       |
|o17 = ideal (a , a*b, c )      |
|                               |
|o17 : Ideal of R               |
+-------------------------------+
|i18 : J = module I             |
|                               |
|o18 = image | a2 ab c2 |       |
|                               |
|                              1|
|o18 : R-module, submodule of R |
+-------------------------------+
|i19 : I == ideal J             |
|                               |
|o19 = true                     |
+-------------------------------+
|i20 : codim I                  |
|                               |
|o20 = 2                        |
+-------------------------------+
|i21 : codim J                  |
|                               |
|o21 = 0                        |
+-------------------------------+

C. Syzygies and free resolutions

Create a free resolution of an ideal (or module) using res.

+-----------------------------------+
|i22 : C = res I                    |
|                                   |
|       1      3      3      1      |
|o22 = R  <-- R  <-- R  <-- R  <-- 0|
|                                   |
|      0      1      2      3      4|
|                                   |
|o22 : ChainComplex                 |
+-----------------------------------+

View the differential

+-------------------------------------------+
|i23 : C.dd                                 |
|                                           |
|           1                    3          |
|o23 = 0 : R  <---------------- R  : 1      |
|                | a2 ab c2 |               |
|                                           |
|           3                          3    |
|      1 : R  <---------------------- R  : 2|
|                {2} | -b -c2 0   |         |
|                {2} | a  0   -c2 |         |
|                {2} | 0  a2  ab  |         |
|                                           |
|           3                  1            |
|      2 : R  <-------------- R  : 3        |
|                {3} | c2 |                 |
|                {4} | -b |                 |
|                {4} | a  |                 |
|                                           |
|           1                               |
|      3 : R  <----- 0 : 4                  |
|                0                          |
|                                           |
|o23 : ChainComplexMap                      |
+-------------------------------------------+

The (graded) betti numbers

+--------------------+
|i24 : betti C       |
|                    |
|             0 1 2 3|
|o24 = total: 1 3 3 1|
|          0: 1 . . .|
|          1: . 3 1 .|
|          2: . . 2 1|
|                    |
|o24 : BettiTally    |
+--------------------+

Use help (betti,GradedModule) for a detailed description of what this display
means.  Basically, it says that I has three generators of degree 2, one syzygy
of degree 3, 2 syzygies of degree 4, and one second syzygy of degree 5. The
free resolution of a module that is not a cokernel:

+-----------------------------------------------------------------------------+
|i25 : C = res Nbar                                                           |
|                                                                             |
|       4      6      2                                                       |
|o25 = R  <-- R  <-- R  <-- 0                                                 |
|                                                                             |
|      0      1      2      3                                                 |
|                                                                             |
|o25 : ChainComplex                                                           |
+-----------------------------------------------------------------------------+
|i26 : betti C                                                                |
|                                                                             |
|             0 1 2                                                           |
|o26 = total: 4 6 2                                                           |
|          0: . 1 .                                                           |
|          1: 4 1 .                                                           |
|          2: . 4 2                                                           |
|                                                                             |
|o26 : BettiTally                                                             |
+-----------------------------------------------------------------------------+
|i27 : C.dd                                                                   |
|                                                                             |
|           4                                                               6 |
|o27 = 0 : R  <----------------------------------------------------------- R  |
|                {1} | 0  0 ce-bf -cd+be+ce-bf e2-df       0           |      |
|                {1} | 0  a -be   bd-be        0           e2-df       |      |
|                {1} | -1 0 b2-ac 0            bd-ae-be+af cd-be-ce+bf |      |
|                {1} | 1  0 0     0            0           0           |      |
|                                                                             |
|           6                         2                                       |
|      1 : R  <--------------------- R  : 2                                   |
|                {1} | 0     0   |                                            |
|                {2} | e2-df 0   |                                            |
|                {3} | -d+e  e-f |                                            |
|                {3} | -e    f   |                                            |
|                {3} | b     -c  |                                            |
|                {3} | -a    b   |                                            |
|                                                                             |
|           2                                                                 |
|      2 : R  <----- 0 : 3                                                    |
|                0                                                            |
|                                                                             |
|o27 : ChainComplexMap                                                        |
|-----------------------------------------------------------------------------|
|: 1                                                                          |
+-----------------------------------------------------------------------------+

Here is a problem to experiment with.  What different betti diagrams are
possible with an ideal generated by 3 homogeneous quadric polynomials, in a
polynomial ring in any number of variables? Here is one to get you started.

+---------------------------------------------+
|i28 : R = QQ[a..h];                          |
+---------------------------------------------+
|i29 : J = ideal(a*c+b*d,a*e+b*f,a*g+b*h)     |
|                                             |
|o29 = ideal (a*c + b*d, a*e + b*f, a*g + b*h)|
|                                             |
|o29 : Ideal of R                             |
+---------------------------------------------+
|i30 : betti res J                            |
|                                             |
|             0 1 2 3                         |
|o30 = total: 1 3 4 2                         |
|          0: 1 . . .                         |
|          1: . 3 . .                         |
|          2: . . 4 2                         |
|                                             |
|o30 : BettiTally                             |
+---------------------------------------------+

After that, try ideals generated by 4 quadrics.

D. Subquotients

Recall that the module N/N0 above displayed as something called a subquotient
module.  As Macaulay2 often returns such objects, it is useful to understand
and be able to manipulate them. P The most common modules are quotients of free
modules, or submodules of free modules.  A useful generalization, which covers
both of these types, are subquotients: submodules of quotients of free modules.
P A subquotient module is determined by two matrices $f : R^m \to R^n$ and $g :
R^p \to R^n$.  The subquotient module with generators f, relations g is by
definition the module M = (image f) + (image g) / (image g). Thus, if f is the
identity map, M = coker g, and if g = 0, then M = image f.

+-------------------------------------------------+
|i31 : use ring M                                 |
|                                                 |
|o31 = QQ[a..f]                                   |
|                                                 |
|o31 : PolynomialRing                             |
+-------------------------------------------------+
|i32 : M                                          |
|                                                 |
|o32 = cokernel | a b d e |                       |
|               | b c e f |                       |
|                                                 |
|                                             2   |
|o32 : QQ[a..f]-module, quotient of (QQ[a..f])    |
+-------------------------------------------------+
|i33 : N = a*M                                    |
|                                                 |
|o33 = subquotient (| a 0 |, | a b d e |)         |
|                   | 0 a |  | b c e f |          |
|                                                 |
|                                                2|
|o33 : QQ[a..f]-module, subquotient of (QQ[a..f]) |
+-------------------------------------------------+
|i34 : M/N                                        |
|                                                 |
|o34 = cokernel | a 0 a b d e |                   |
|               | 0 a b c e f |                   |
|                                                 |
|                                             2   |
|o34 : QQ[a..f]-module, quotient of (QQ[a..f])    |
+-------------------------------------------------+

The two matrices f and g mentioned above are recovered using the routines:
generators, relations.

+----------------------------------------+
|i35 : generators N                      |
|                                        |
|o35 = | a 0 |                           |
|      | 0 a |                           |
|                                        |
|                       2               2|
|o35 : Matrix (QQ[a..f])  <-- (QQ[a..f]) |
+----------------------------------------+
|i36 : relations N                       |
|                                        |
|o36 = | a b d e |                       |
|      | b c e f |                       |
|                                        |
|                       2               4|
|o36 : Matrix (QQ[a..f])  <-- (QQ[a..f]) |
+----------------------------------------+

It is often necessary to find a presentation matrix for such modules.

+----------------------------------------+
|i37 : presentation N                    |
|                                        |
|o37 = {1} | e d b a |                   |
|      {1} | f e c b |                   |
|                                        |
|                       2               4|
|o37 : Matrix (QQ[a..f])  <-- (QQ[a..f]) |
+----------------------------------------+

Often the given representation of a module is not very efficient. Use trim to
keep the module as a subquotient of the same ambient free module, but change
the generators and relations to be minimal, or in the nonlocal or non-graded
case, at least more efficient.

+-------------------------------------------------+
|i38 : trim N                                     |
|                                                 |
|o38 = subquotient (| a 0 |, | e d b a |)         |
|                   | 0 a |  | f e c b |          |
|                                                 |
|                                                2|
|o38 : QQ[a..f]-module, subquotient of (QQ[a..f]) |
+-------------------------------------------------+

Use minimalPresentation  to also allow the ambient free module to be improved.
This returns a quotient of a free module, but in the future might not do that.

+----------------------------------------------+
|i39 : minimalPresentation N                   |
|                                              |
|o39 = cokernel {1} | e d b a |                |
|               {1} | f e c b |                |
|                                              |
|                                             2|
|o39 : QQ[a..f]-module, quotient of (QQ[a..f]) |
+----------------------------------------------+

prune is a synonym for minimalPresentation N

+----------------------------------------------+
|i40 : prune N                                 |
|                                              |
|o40 = cokernel {1} | e d b a |                |
|               {1} | f e c b |                |
|                                              |
|                                             2|
|o40 : QQ[a..f]-module, quotient of (QQ[a..f]) |
+----------------------------------------------+

Given a subquotient module N, there are several useful modules associated to N.
The free module of which N is a subquotient is obtained using ambient.

+---------------------------+
|i41 : ambient N            |
|                           |
|                2          |
|o41 = (QQ[a..f])           |
|                           |
|o41 : QQ[a..f]-module, free|
+---------------------------+

This is the same as the target of either the generator or relation matrix.

+--------------------------------------+
|i42 : ambient N == target generators N|
|                                      |
|o42 = true                            |
+--------------------------------------+
|i43 : ambient N == target relations N |
|                                      |
|o43 = true                            |
+--------------------------------------+

N is a submodule of a quotient module $R^n/image(g)$.  The routine super
returns this quotient module

+----------------------------------------------+
|i44 : super N                                 |
|                                              |
|o44 = cokernel | a b d e |                    |
|               | b c e f |                    |
|                                              |
|                                             2|
|o44 : QQ[a..f]-module, quotient of (QQ[a..f]) |
+----------------------------------------------+

This is the same as

+----------------------------------+
|i45 : super N == coker relations N|
|                                  |
|o45 = true                        |
+----------------------------------+

The cover of N is basically the source of the matrix of generators.

+------------------------------------------+
|i46 : cover N                             |
|                                          |
|                2                         |
|o46 = (QQ[a..f])                          |
|                                          |
|o46 : QQ[a..f]-module, free, degrees {2:1}|
+------------------------------------------+
|i47 : cover N == source generators N      |
|                                          |
|o47 = true                                |
+------------------------------------------+

E. Homomorphisms between modules

A homomorphism $f : M \to N$ is represented as a matrix from the generators of
M to the generators of N.

+-------------------------------+
|i48 : A = QQ[x,y]/(y^2-x^3)    |
|                               |
|o48 = A                        |
|                               |
|o48 : QuotientRing             |
+-------------------------------+
|i49 : M = module ideal(x,y)    |
|                               |
|o49 = image | x y |            |
|                               |
|                              1|
|o49 : A-module, submodule of A |
+-------------------------------+

One homomorphism $F : M \to A$ is $x \mapsto y, y \mapsto x^2$ (multiplication
by y/x) We write this as:

+------------------------------------+
|i50 : F = map(A^1,M,matrix{{y,x^2}})|
|                                    |
|o50 = | y x2 |                      |
|                                    |
|              1                     |
|o50 : Matrix A  <-- M               |
+------------------------------------+

Notice that as is usual in Macaulay2, the target comes before the source.

+----------------------+
|i51 : source F == M   |
|                      |
|o51 = true            |
+----------------------+
|i52 : target F == A^1 |
|                      |
|o52 = true            |
+----------------------+
|i53 : matrix F        |
|                      |
|o53 = | y x2 |        |
|                      |
|              1      2|
|o53 : Matrix A  <-- A |
+----------------------+

The image of F lies in the submodule M of $A^1$.  To obtain the map $M \to M$,
we use //.  But first we need the inclusion map of M into $A^1$: Later we
explain this, but for now, we just write down this map:

+-----------------------+
|i54 : inducedMap(A^1,M)|
|                       |
|o54 = | x y |          |
|                       |
|              1        |
|o54 : Matrix A  <-- M  |
+-----------------------+

Now we use // to lift $F : M \to A$ along $M \to A^1$, to get $M \to M$:

+--------------------------------+
|i55 : G = F // inducedMap(A^1,M)|
|                                |
|o55 = {1} | 0 x |               |
|      {1} | 1 0 |               |
|                                |
|o55 : Matrix M <-- M            |
+--------------------------------+
|i56 : source G                  |
|                                |
|o56 = image | x y |             |
|                                |
|                              1 |
|o56 : A-module, submodule of A  |
+--------------------------------+
|i57 : target G                  |
|                                |
|o57 = image | x y |             |
|                                |
|                              1 |
|o57 : A-module, submodule of A  |
+--------------------------------+

G is now a map from $M \to M$.

+---------------------+
|i58 : isWellDefined G|
|                     |
|o58 = true           |
+---------------------+

F. Canonical maps associated with modules

Let's start with a module M, and a submodule N.

+----------------------------------------------------+
|i59 : R = QQ[x,y,z,w]                               |
|                                                    |
|o59 = R                                             |
|                                                    |
|o59 : PolynomialRing                                |
+----------------------------------------------------+
|i60 : M = ideal(x,y,z)/ideal(x^2,y^2,z*w)           |
|                                                    |
|o60 = subquotient (| x y z |, | x2 y2 zw |)         |
|                                                    |
|                                1                   |
|o60 : R-module, subquotient of R                    |
+----------------------------------------------------+
|i61 : N = z*M                                       |
|                                                    |
|o61 = subquotient (| xz yz z2 |, | x2 y2 zw |)      |
|                                                    |
|                                1                   |
|o61 : R-module, subquotient of R                    |
+----------------------------------------------------+
|i62 : M/N                                           |
|                                                    |
|o62 = subquotient (| x y z |, | xz yz z2 x2 y2 zw |)|
|                                                    |
|                                1                   |
|o62 : R-module, subquotient of R                    |
+----------------------------------------------------+

If two modules have the same ambient free module, then there is often a
canonical map between them. Some modules having the same ambient free module:

+----------------------------------------------+
|i63 : M                                       |
|                                              |
|o63 = subquotient (| x y z |, | x2 y2 zw |)   |
|                                              |
|                                1             |
|o63 : R-module, subquotient of R              |
+----------------------------------------------+
|i64 : ambient M                               |
|                                              |
|       1                                      |
|o64 = R                                       |
|                                              |
|o64 : R-module, free                          |
+----------------------------------------------+
|i65 : N = z*M                                 |
|                                              |
|o65 = subquotient (| xz yz z2 |, | x2 y2 zw |)|
|                                              |
|                                1             |
|o65 : R-module, subquotient of R              |
+----------------------------------------------+
|i66 : ambient(M/N)                            |
|                                              |
|       1                                      |
|o66 = R                                       |
|                                              |
|o66 : R-module, free                          |
+----------------------------------------------+
|i67 : super M                                 |
|                                              |
|o67 = cokernel | x2 y2 zw |                   |
|                                              |
|                             1                |
|o67 : R-module, quotient of R                 |
+----------------------------------------------+
|i68 : super N                                 |
|                                              |
|o68 = cokernel | x2 y2 zw |                   |
|                                              |
|                             1                |
|o68 : R-module, quotient of R                 |
+----------------------------------------------+
|i69 : image generators M                      |
|                                              |
|o69 = image | x y z |                         |
|                                              |
|                              1               |
|o69 : R-module, submodule of R                |
+----------------------------------------------+

If two modules M and N have the same ambient module $R^n$, then inducedMap(M,N)
makes the canonical map $N \to M$ between them, if one exists.  If a map
doesn't exist, the returned map might not be a homomorphism.

+-----------------------------------------------------------------------------+
|i70 : inducedMap(M,M) == id_M                                                |
|                                                                             |
|o70 = true                                                                   |
+-----------------------------------------------------------------------------+
|i71 : inducedMap(super M,M) == map(super id_M) -- the map $(P+Q)/Q \to       |
|                                                                             |
|o71 = true                                                                   |
|-----------------------------------------------------------------------------|
|R^n/Q$, where $M=(P+Q)/Q$.                                                   |
+-----------------------------------------------------------------------------+
|i72 : inducedMap(super M,ambient M) -- the quotient map $R^n \to R^n/Q$      |
|                                                                             |
|o72 = | 1 |                                                                  |
|                                                                             |
|o72 : Matrix                                                                 |
+-----------------------------------------------------------------------------+
|i73 : inducedMap(M,N) -- the inclusion map                                   |
|                                                                             |
|o73 = {1} | z 0 0 |                                                          |
|      {1} | 0 z 0 |                                                          |
|      {1} | 0 0 z |                                                          |
|                                                                             |
|o73 : Matrix M <-- N                                                         |
+-----------------------------------------------------------------------------+

The projection map $M \to M/N$

+---------------------------------------------+
|i74 : inducedMap(M/N,M) -- the projection map|
|                                             |
|o74 = {1} | 1 0 0 |                          |
|      {1} | 0 1 0 |                          |
|      {1} | 0 0 1 |                          |
|                                             |
|o74 : Matrix                                 |
+---------------------------------------------+

The projection map $N \to M/N$, which is the zero map

+---------------------------------------+
|i75 : inducedMap(M/N,N) -- the zero map|
|                                       |
|o75 = 0                                |
|                                       |
|o75 : Matrix                           |
+---------------------------------------+

Not all such maps can be defined.  The functions 'inducedMap' normally checks
that the result is a well-defined homomorphism.  The option 'Verify' controls
that behavior.

+------------------------------------------------------------------+
|i76 : inducedMap(M,M/N,Verify => false)                           |
|                                                                  |
|o76 = {1} | 1 0 0 |                                               |
|      {1} | 0 1 0 |                                               |
|      {1} | 0 0 1 |                                               |
|                                                                  |
|o76 : Matrix                                                      |
+------------------------------------------------------------------+
|i77 : inducedMap(M/N,x*M)                                         |
|                                                                  |
|o77 = {1} | 0 y 0 |                                               |
|      {1} | 0 0 0 |                                               |
|      {1} | 0 0 0 |                                               |
|                                                                  |
|o77 : Matrix                                                      |
+------------------------------------------------------------------+
|i78 : inducedMap(M/N,M) * inducedMap(M,x*M) == inducedMap(M/N,x*M)|
|                                                                  |
|o78 = true                                                        |
+------------------------------------------------------------------+

 Before doing interesting homomorphisms, let's see how to write down some
canonical homomorphisms associated to M. exercises: 1. isomorphism theorems.
Given submodules M and N of a module P, (a) find $(M+N)/M$ (b) find $N/(M \cap
N)$ (c) find in Macaulay2, an isomorphism between them.

2. Given a homomorphism $M \to A$.  Suppose that the image lies in M (M is a
submodule of $A^1$). Find the map $M \to M$.

G. Homomorphisms and Hom

+------------------------------------------+
|i79 : A = QQ[x,y,Degrees=>{2,3}]/(y^2-x^3)|
|                                          |
|o79 = A                                   |
|                                          |
|o79 : QuotientRing                        |
+------------------------------------------+
|i80 : M = module ideal(x,y)               |
|                                          |
|o80 = image | x y |                       |
|                                          |
|                              1           |
|o80 : A-module, submodule of A            |
+------------------------------------------+
|i81 : H = Hom(M,M)                        |
|                                          |
|o81 = image {-2} | x y  |                 |
|            {-3} | y x2 |                 |
|                                          |
|                              2           |
|o81 : A-module, submodule of A            |
+------------------------------------------+

The elements of H correspond to homomorphisms $M \to A$. The homomorphism
associated to elements of H may be obtained using the routine homomorphism.

+------------------------------------+
|i82 : F = homomorphism(H_{0})       |
|                                    |
|o82 = {2} | 1 0 |                   |
|      {3} | 0 1 |                   |
|                                    |
|o82 : Matrix M <-- M                |
+------------------------------------+
|i83 : G = homomorphism(H_{1})       |
|                                    |
|o83 = {2} | 0 x |                   |
|      {3} | 1 0 |                   |
|                                    |
|o83 : Matrix M <-- M                |
+------------------------------------+
|i84 : source F == M                 |
|                                    |
|o84 = true                          |
+------------------------------------+
|i85 : target F == M                 |
|                                    |
|o85 = true                          |
+------------------------------------+
|i86 : ker F                         |
|                                    |
|o86 = image 0                       |
|                                    |
|                              1     |
|o86 : A-module, submodule of A      |
+------------------------------------+
|i87 : coker F                       |
|                                    |
|o87 = subquotient (| x y |, | x y |)|
|                                    |
|                                1   |
|o87 : A-module, subquotient of A    |
+------------------------------------+
|i88 : m = matrix{{x,y},{y,x}}       |
|                                    |
|o88 = | x y |                       |
|      | y x |                       |
|                                    |
|              2      2              |
|o88 : Matrix A  <-- A               |
+------------------------------------+
|i89 : Hom(m,A^2)                    |
|                                    |
|o89 = {-3} | x 0 y 0 |              |
|      {-3} | 0 x 0 y |              |
|      {-3} | y 0 x 0 |              |
|      {-3} | 0 y 0 x |              |
|                                    |
|              4      4              |
|o89 : Matrix A  <-- A               |
+------------------------------------+
|i90 : Hom(A^2,m)                    |
|                                    |
|o90 = | x y 0 0 |                   |
|      | y x 0 0 |                   |
|      | 0 0 x y |                   |
|      | 0 0 y x |                   |
|                                    |
|              4      4              |
|o90 : Matrix A  <-- A               |
+------------------------------------+

H. Tensor products

In Macaulay2, ** denotes the tensor product operator.

+----------------------------------+
|i91 : m ** m                      |
|                                  |
|o91 = | x2 xy xy y2 |             |
|      | xy x2 y2 xy |             |
|      | xy y2 x2 xy |             |
|      | y2 xy xy x2 |             |
|                                  |
|              4      4            |
|o91 : Matrix A  <-- A             |
+----------------------------------+
|i92 : (coker m) ** (coker m)      |
|                                  |
|o92 = cokernel | x y 0 0 x y 0 0 ||
|               | y x 0 0 0 0 x y ||
|               | 0 0 x y y x 0 0 ||
|               | 0 0 y x 0 0 y x ||
|                                  |
|                             4    |
|o92 : A-module, quotient of A     |
+----------------------------------+

Notice that tensor products of matrices and of modules are very different.

+--------------------------------+
|i93 : M = coker m               |
|                                |
|o93 = cokernel | x y |          |
|               | y x |          |
|                                |
|                             2  |
|o93 : A-module, quotient of A   |
+--------------------------------+
|i94 : M2 = prune(M ** M)        |
|                                |
|o94 = cokernel | 0  -x y x x 0 ||
|               | -x 0  x y 0 x ||
|               | x  0  0 0 y 0 ||
|               | 0  x  0 0 0 y ||
|                                |
|                             4  |
|o94 : A-module, quotient of A   |
+--------------------------------+
|i95 : A = QQ[a,b,c]             |
|                                |
|o95 = A                         |
|                                |
|o95 : PolynomialRing            |
+--------------------------------+
|i96 : A ** A                    |
|                                |
|o96 = QQ[a , b , c , a , b , c ]|
|          0   0   0   1   1   1 |
|                                |
|o96 : PolynomialRing            |
+--------------------------------+

Macaulay2 renames variables whose names collide. Alternatively, one can give
the variables as an option to tensor.

+------------------------------------------+
|i97 : tensor(A,A,Variables=>{a,b,c,d,e,f})|
|                                          |
|o97 = QQ[a..f]                            |
|                                          |
|o97 : PolynomialRing                      |
+------------------------------------------+

M2SingularBook -- Macaulay2 examples for the Singular book
**********************************************************

M2SingularBook consists of Macaulay2 translations of the examples in the book A
Singular introduction to commutative algebra

Each example is numbered as it is in Greuel and Pfister's book.  Links to
Macaulay2 routines and concepts are also provided.

Chapter 1

Chapter 2

Singular Book 1.1.8 -- computation in fields
********************************************

Computation over ZZ and QQ
==========================

In Macaulay2, Integers are arbitrary precision.  The ring of integers is
denoted ZZ.
+--------------------------------------------------------+
|i1 : 123456789^5                                        |
|                                                        |
|o1 = 28679718602997181072337614380936720482949          |
+--------------------------------------------------------+
|i2 : matrix{{123456789^5}}                              |
|                                                        |
|o2 = | 28679718602997181072337614380936720482949 |      |
|                                                        |
|              1       1                                 |
|o2 : Matrix ZZ  <-- ZZ                                  |
+--------------------------------------------------------+
|i3 : gcd(3782621293644611237896400,85946734897630958700)|
|                                                        |
|o3 = 100                                                |
+--------------------------------------------------------+
The ring of rational numbers is denoted by QQ.
+------------------------------------------+
|i4 : n = 12345/6789                       |
|                                          |
|     4115                                 |
|o4 = ----                                 |
|     2263                                 |
|                                          |
|o4 : QQ                                   |
+------------------------------------------+
|i5 : n^5                                  |
|                                          |
|     1179910858126071875                  |
|o5 = -------------------                  |
|      59350279669807543                   |
|                                          |
|o5 : QQ                                   |
+------------------------------------------+
|i6 : toString(n^5)                        |
|                                          |
|o6 = 1179910858126071875/59350279669807543|
+------------------------------------------+

Computation in finite fields
============================

+------------------+
|i7 : A = ZZ/32003;|
+------------------+
In order to do arithmetic in this ring, you must construct elements of this
ring. n_A gives the image of the integer n in A.
+--------------------+
|i8 : 123456789 * 1_A|
|                    |
|o8 = -10785         |
|                    |
|o8 : A              |
+--------------------+
|i9 : (123456789_A)^5|
|                    |
|o9 = 8705           |
|                    |
|o9 : A              |
+--------------------+
+----------------------------+
|i10 : A2 = GF(8,Variable=>a)|
|                            |
|o10 = A2                    |
|                            |
|o10 : GaloisField           |
+----------------------------+
|i11 : ambient A2            |
|                            |
|         ZZ                 |
|         --[a]              |
|          2                 |
|o11 = ----------            |
|       3                    |
|      a  + a + 1            |
|                            |
|o11 : QuotientRing          |
+----------------------------+
|i12 : a^3+a+1               |
|                            |
|o12 = 0                     |
|                            |
|o12 : A2                    |
+----------------------------+
+--------------------------------+
|i13 : A3 = ZZ/2[a]/(a^20+a^3+1);|
+--------------------------------+
|i14 : n = a+a^2                 |
|                                |
|       2                        |
|o14 = a  + a                    |
|                                |
|o14 : A3                        |
+--------------------------------+
|i15 : n^5                       |
|                                |
|       10    9    6    5        |
|o15 = a   + a  + a  + a         |
|                                |
|o15 : A3                        |
+--------------------------------+

Computing with real and complex numbers
=======================================

+--------------------------+
|i16 : n = 123456789.0     |
|                          |
|o16 = 123456789           |
|                          |
|o16 : RR (of precision 53)|
+--------------------------+
|i17 : n = n * 1_RR        |
|                          |
|o17 = 123456789           |
|                          |
|o17 : RR (of precision 53)|
+--------------------------+
|i18 : n^5                 |
|                          |
|o18 = 2.867971860299718e40|
|                          |
|o18 : RR (of precision 53)|
+--------------------------+

Computing with parameters
=========================

+-----------------------------------------------------+
|i19 : R3 = frac(ZZ[a,b,c])                           |
|                                                     |
|o19 = R3                                             |
|                                                     |
|o19 : FractionField                                  |
+-----------------------------------------------------+
|i20 : n = 12345*a + 12345/(78*b*c)                   |
|                                                     |
|      320970a*b*c + 4115                             |
|o20 = ------------------                             |
|             26b*c                                   |
|                                                     |
|o20 : R3                                             |
+-----------------------------------------------------+
|i21 : n^2                                            |
|                                                     |
|                   2 2 2                             |
|      103021740900a b c  + 2641583100a*b*c + 16933225|
|o21 = -----------------------------------------------|
|                              2 2                    |
|                          676b c                     |
|                                                     |
|o21 : R3                                             |
+-----------------------------------------------------+
|i22 : n/(9*c)                                        |
|                                                     |
|      320970a*b*c + 4115                             |
|o22 = ------------------                             |
|                  2                                  |
|            234b*c                                   |
|                                                     |
|o22 : R3                                             |
+-----------------------------------------------------+

Singular Book 1.1.9 -- computation in polynomial rings
******************************************************

Create a polynomial ring using reasonably standard notation.
+--------------------------------------------------------+
|i1 : A = QQ[x,y,z];                                     |
+--------------------------------------------------------+
|i2 : f = x^3+y^2+z^2                                    |
|                                                        |
|      3    2    2                                       |
|o2 = x  + y  + z                                        |
|                                                        |
|o2 : A                                                  |
+--------------------------------------------------------+
|i3 : f^2-f                                              |
|                                                        |
|      6     3 2     3 2    4     2 2    4    3    2    2|
|o3 = x  + 2x y  + 2x z  + y  + 2y z  + z  - x  - y  - z |
|                                                        |
|o3 : A                                                  |
+--------------------------------------------------------+
Here are several more examples.
+----------------------------------+
|i4 : B = ZZ/32003[x,y,z];         |
+----------------------------------+
|i5 : C = GF(8)[x,y,z];            |
+----------------------------------+
|i6 : D = ZZ[x,y,z];               |
+----------------------------------+
|i7 : E = (frac(ZZ[a,b,c]))[x,y,z];|
+----------------------------------+
In Macaulay2, there is no concept of current ring.  When you assign a ring to a
variable, the variables in the ring are made global variables.  To get the
variables in a previous ring to be available, use use(Ring).
+-------------------+
|i8 : x             |
|                   |
|o8 = x             |
|                   |
|o8 : E             |
+-------------------+
|i9 : use D         |
|                   |
|o9 = D             |
|                   |
|o9 : PolynomialRing|
+-------------------+
|i10 : x            |
|                   |
|o10 = x            |
|                   |
|o10 : D            |
+-------------------+
Now x is an element of the ring D.
+---------------------------------------------+
|i11 : describe D                             |
|                                             |
|o11 = ZZ[x..z, Degrees => {3:1}, Heft => {1}]|
+---------------------------------------------+

Singular Book 1.1.10 -- methods for creating ring maps
******************************************************

In Macaulay2, ring maps from a polynomial ring are defined and used as follows.
+----------------------------------+
|i1 : A = QQ[a,b,c];               |
+----------------------------------+
|i2 : f = a+b+a*b+c^3;             |
+----------------------------------+
|i3 : B = QQ[x,y,z];               |
+----------------------------------+
|i4 : F = map(B,A,{x+y, x-y, z})   |
|                                  |
|o4 = map (B, A, {x + y, x - y, z})|
|                                  |
|o4 : RingMap B <-- A              |
+----------------------------------+
Notice that ring maps are defined by first giving the target ring, then the
source ring, and finally the data.

Parentheses for functions with one parameter are optional.
+--------------------------+
|i5 : g = F f              |
|                          |
|      3    2    2         |
|o5 = z  + x  - y  + 2x    |
|                          |
|o5 : B                    |
+--------------------------+
|i6 : A1 = QQ[x,y,c,b,a,z];|
+--------------------------+
|i7 : substitute(f,A1)     |
|                          |
|      3                   |
|o7 = c  + b*a + b + a     |
|                          |
|o7 : A1                   |
+--------------------------+
To map the first variable of A to the first variable of A1, the second variable
of A to the second variable of A1, and so on, create the list of the first
generators of A1
+---------------------------------+
|i8 : v = take(gens A1, numgens A)|
|                                 |
|o8 = {x, y, c}                   |
|                                 |
|o8 : List                        |
+---------------------------------+
|i9 : G = map(A1,A,v)             |
|                                 |
|o9 = map (A1, A, {x, y, c})      |
|                                 |
|o9 : RingMap A1 <-- A            |
+---------------------------------+
|i10 : G f                        |
|                                 |
|       3                         |
|o10 = c  + x*y + x + y           |
|                                 |
|o10 : A1                         |
+---------------------------------+

See also
========

  * substitution and maps between rings
  * map -- make a map
  * substitute -- substituting values for variables
  * RingMap -- the class of all ring maps
  * generators -- provide matrix or list of generators
  * numgens -- the number of generators
  * take -- Take some elements from a list or sequence.

Singular Book 1.2.3 -- leading data
***********************************

+------------------------------------------------+
|i1 : A = QQ[x,y,z,MonomialOrder=>Lex];          |
+------------------------------------------------+
|i2 : f = y^4*z^3+2*x^2*y^2*z^2+3*x^5+4*z^4+5*y^2|
|                                                |
|       5     2 2 2    4 3     2     4           |
|o2 = 3x  + 2x y z  + y z  + 5y  + 4z            |
|                                                |
|o2 : A                                          |
+------------------------------------------------+
|i3 : leadMonomial f                             |
|                                                |
|      5                                         |
|o3 = x                                          |
|                                                |
|o3 : A                                          |
+------------------------------------------------+
|i4 : exponents leadMonomial f                   |
|                                                |
|o4 = {{5, 0, 0}}                                |
|                                                |
|o4 : List                                       |
+------------------------------------------------+
|i5 : leadTerm f                                 |
|                                                |
|       5                                        |
|o5 = 3x                                         |
|                                                |
|o5 : A                                          |
+------------------------------------------------+
|i6 : leadCoefficient f                          |
|                                                |
|o6 = 3                                          |
|                                                |
|o6 : QQ                                         |
+------------------------------------------------+
|i7 : someTerms(f,1,size f - 1)                  |
|                                                |
|       2 2 2    4 3     2     4                 |
|o7 = 2x y z  + y z  + 5y  + 4z                  |
|                                                |
|o7 : A                                          |
+------------------------------------------------+
|i8 : someTerms(f,1,-1)                          |
|                                                |
|       2 2 2    4 3     2     4                 |
|o8 = 2x y z  + y z  + 5y  + 4z                  |
|                                                |
|o8 : A                                          |
+------------------------------------------------+

Singular Book 1.2.13 -- monomial orderings
******************************************

Monomial orderings are specified when defining a polynomial ring.

global orderings
================

The default order is the graded (degree) reverse lexicographic order.
+-------------------------------------------+
|i1 : A2 = QQ[x,y,z];                       |
+-------------------------------------------+
|i2 : A2 = QQ[x,y,z,MonomialOrder=>GRevLex];|
+-------------------------------------------+
|i3 : f = x^3*y*z+y^5+z^4+x^3+x*y^2         |
|                                           |
|      5    3       4    3      2           |
|o3 = y  + x y*z + z  + x  + x*y            |
|                                           |
|o3 : A2                                    |
+-------------------------------------------+
Lexicographic order.
+---------------------------------------+
|i4 : A1 = QQ[x,y,z,MonomialOrder=>Lex];|
+---------------------------------------+
|i5 : substitute(f,A1)                  |
|                                       |
|      3       3      2    5    4       |
|o5 = x y*z + x  + x*y  + y  + z        |
|                                       |
|o5 : A1                                |
+---------------------------------------+
Graded (degree) lexicographic order.
+----------------------------------------------------------+
|i6 : A3 = QQ[x,y,z,MonomialOrder=>{Weights=>{1,1,1},Lex}];|
+----------------------------------------------------------+
|i7 : substitute(f,A3)                                     |
|                                                          |
|      3       5    4    3      2                          |
|o7 = x y*z + y  + z  + x  + x*y                           |
|                                                          |
|o7 : A3                                                   |
+----------------------------------------------------------+
Graded (degree) lexicographic order, with nonstandard weights.
+----------------------------------------------------------+
|i8 : A4 = QQ[x,y,z,MonomialOrder=>{Weights=>{5,3,2},Lex}];|
+----------------------------------------------------------+
|i9 : substitute(f,A4)                                     |
|                                                          |
|      3       3    5      2    4                          |
|o9 = x y*z + x  + y  + x*y  + z                           |
|                                                          |
|o9 : A4                                                   |
+----------------------------------------------------------+
A product order, with each block being GRevLex.
+-----------------------------------------+
|i10 : A = QQ[x,y,z,MonomialOrder=>{1,2}];|
+-----------------------------------------+
|i11 : substitute(f,A)                    |
|                                         |
|       3       3      2    5    4        |
|o11 = x y*z + x  + x*y  + y  + z         |
|                                         |
|o11 : A                                  |
+-----------------------------------------+

local orderings
===============

Negative lexicographic order.
+-----------------------------------------------------------------------------+
|i12 : A = QQ[x,y,z,MonomialOrder=>{Weights=>{-1,0,0},Weights=>{0,-1,0},      |
|-----------------------------------------------------------------------------|
|Weights=>{0,0,-1}},Global=>false];                                           |
+-----------------------------------------------------------------------------+
|i13 : substitute(f,A)                                                        |
|                                                                             |
|       4    5      2    3    3                                               |
|o13 = z  + y  + x*y  + x  + x y*z                                            |
|                                                                             |
|o13 : A                                                                      |
+-----------------------------------------------------------------------------+
Negative graded reverse lexicographic order.
+-----------------------------------------------------------------------------+
|i14 : A = QQ[x,y,z,MonomialOrder=>{Weights=>{-1,-1,-1},GRevLex},Global=>false|
|-----------------------------------------------------------------------------|
|];                                                                           |
+-----------------------------------------------------------------------------+
|i15 : substitute(f,A)                                                        |
|                                                                             |
|       3      2    4    5    3                                               |
|o15 = x  + x*y  + z  + y  + x y*z                                            |
|                                                                             |
|o15 : A                                                                      |
+-----------------------------------------------------------------------------+

Singular Book 1.3.3 -- properties of ring maps
**********************************************

+----------------------------------+
|i1 : S = QQ[a,b,c];               |
+----------------------------------+
|i2 : R = QQ[x,y,z];               |
+----------------------------------+
|i3 : phi = map(R,S,{x,y,x^2-y^3}) |
|                                  |
|                          3    2  |
|o3 = map (R, S, {x, y, - y  + x })|
|                                  |
|o3 : RingMap R <-- S              |
+----------------------------------+
|i4 : isInjective phi              |
|                                  |
|o4 = false                        |
+----------------------------------+
|i5 : ker phi                      |
|                                  |
|            3    2                |
|o5 = ideal(b  - a  + c)           |
|                                  |
|o5 : Ideal of S                   |
+----------------------------------+
Packaged code for computing preimage is missing, but it's easy to do, as
follows.
+----------------------------------------+
|i6 : psi = map(R,S,{x,x+y,z-x^2+y^3})   |
|                                        |
|                            3    2      |
|o6 = map (R, S, {x, x + y, y  - x  + z})|
|                                        |
|o6 : RingMap R <-- S                    |
+----------------------------------------+
|i7 : isInjective psi                    |
|                                        |
|o7 = true                               |
+----------------------------------------+
|i8 : ker psi                            |
|                                        |
|o8 = ideal ()                           |
|                                        |
|o8 : Ideal of S                         |
+----------------------------------------+

Singular Book 1.3.13 -- computation in quotient rings
*****************************************************

In Macaulay2, we define a quotient ring using the usual mathematical notation.
+--------------------------------------+
|i1 : R = ZZ/32003[x,y,z];             |
+--------------------------------------+
|i2 : Q = R/(x^2+y^2-z^5, z-x-y^2)     |
|                                      |
|o2 = Q                                |
|                                      |
|o2 : QuotientRing                     |
+--------------------------------------+
|i3 : f = z^2+y^2                      |
|                                      |
|      2                               |
|o3 = z  - x + z                       |
|                                      |
|o3 : Q                                |
+--------------------------------------+
|i4 : g = z^2+2*x-2*z-3*z^5+3*x^2+6*y^2|
|                                      |
|      2                               |
|o4 = z  - x + z                       |
|                                      |
|o4 : Q                                |
+--------------------------------------+
|i5 : f == g                           |
|                                      |
|o5 = true                             |
+--------------------------------------+
Testing for zerodivisors in Macaulay2:
+---------------+
|i6 : ann f     |
|               |
|o6 = ideal ()  |
|               |
|o6 : Ideal of Q|
+---------------+
This is the zero ideal, meaning that $f$ is not a zero divisor in the ring $Q$.

Singular Book 1.3.15 -- computing with radicals
***********************************************

Compute the radical of an ideal with radical (MinimalPrimes).
+-------------------------------+
|i1 : R = QQ[x,y,z];            |
+-------------------------------+
|i2 : radical ideal(z^4+2*z^2+1)|
|                               |
|            2                  |
|o2 = ideal(z  + 1)             |
|                               |
|o2 : Ideal of R                |
+-------------------------------+
A somewhat more complicated example:
+-------------------------------+
|i3 : I = ideal"xyz,x2,y4+y5"   |
|                               |
|                    2   5    4 |
|o3 = ideal (x*y*z, x , y  + y )|
|                               |
|o3 : Ideal of R                |
+-------------------------------+
|i4 : radical I                 |
|                               |
|                2              |
|o4 = ideal (x, y  + y)         |
|                               |
|o4 : Ideal of R                |
+-------------------------------+
The index of nilpotency.  We compute the minimal integer $k$ such that
$(y^2+y)^k \in I$.
+-----------------------------------------+
|i5 : k = 0;                              |
+-----------------------------------------+
|i6 : while (y^2+y)^k % I != 0 do k = k+1;|
+-----------------------------------------+
|i7 : k                                   |
|                                         |
|o7 = 4                                   |
+-----------------------------------------+
The index of nilpotency is 4.

Singular Book 1.4.9 -- global versus local rings
************************************************

Consider the union of a line and a plane in affine 3-space.
+---------------------------------+
|i1 : S = QQ[x,y,z];              |
+---------------------------------+
|i2 : I = ideal(y*(x-1), z*(x-1));|
|                                 |
|o2 : Ideal of S                  |
+---------------------------------+
The dimension is 2, the maximum of the dimensions of the two components.  In
order to find the dimension, Macaulay2 requires the Groebner basis of I.  It
computes this behind the scenes, and caches the value with I.
+---------------------+
|i3 : dim I           |
|                     |
|o3 = 2               |
+---------------------+
|i4 : gens gb I       |
|                     |
|o4 = | xz-z xy-y |   |
|                     |
|             1      2|
|o4 : Matrix S  <-- S |
+---------------------+
Notice that $y$ is not in $I$.
+----------+
|i5 : y % I|
|          |
|o5 = y    |
|          |
|o5 : S    |
+----------+
Now let's use a local order.
+-----------------------------------------------------------------------------+
|i6 : R = QQ[x,y,z,MonomialOrder=>{Weights=>{-1,-1,-1},RevLex},Global=>false];|
+-----------------------------------------------------------------------------+
|i7 : J = substitute(I,R)                                                     |
|                                                                             |
|o7 = ideal (- y + x*y, - z + x*z)                                            |
|                                                                             |
|o7 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i8 : gens gb J                                                               |
|                                                                             |
|o8 = | y-xy z-xz |                                                           |
|                                                                             |
|             1      2                                                        |
|o8 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
The dimension in this case is 1.
+----------+
|i9 : dim J|
|          |
|o9 = 1    |
+----------+

The following is WRONG.  In this local ring, $y$ is in the ideal $J$.
+-----------+
|i10 : y % J|
|           |
|o10 = 0    |
|           |
|o10 : R    |
+-----------+

Translate the origin to $(1,0,0)$.  The plane $x-1 = 0$ goes through this new
origin.
+---------------------------------+
|i11 : J = substitute(J, {x=>x+1})|
|                                 |
|o11 = ideal (x*y, x*z)           |
|                                 |
|o11 : Ideal of R                 |
+---------------------------------+
|i12 : dim J                      |
|                                 |
|o12 = 2                          |
+---------------------------------+

Compute the global dimension after translation.
+----------------------------------+
|i13 : use ring I                  |
|                                  |
|o13 = S                           |
|                                  |
|o13 : PolynomialRing              |
+----------------------------------+
|i14 : I1 = substitute(I, {x=>x+1})|
|                                  |
|o14 = ideal (x*y, x*z)            |
|                                  |
|o14 : Ideal of S                  |
+----------------------------------+
|i15 : dim I1                      |
|                                  |
|o15 = 2                           |
+----------------------------------+
See also dim.

See also
========

  * dim -- compute the Krull dimension

Singular Book 1.5.10 -- realization of rings
********************************************

We define the rings of example 1.5.3, in the Singular book.
+----------------------------------------------------------------------------+
|i1 : (n,m) = (2,3);                                                         |
+----------------------------------------------------------------------------+
|i2 : A1 = QQ[x_1..x_n,y_1..y_m,MonomialOrder=>{n, RevLex=>m},Global=>false];|
+----------------------------------------------------------------------------+
|i3 : f = x_1*x_2^2 + 1 + y_1^10 + x_1*y_2^5 + y_3                           |
|                                                                            |
|        2      5             10                                             |
|o3 = x x  + x y  + 1 + y  + y                                               |
|      1 2    1 2        3    1                                              |
|                                                                            |
|o3 : A1                                                                     |
+----------------------------------------------------------------------------+
|i4 : 1_A1 > y_1^10                                                          |
|                                                                            |
|o4 = true                                                                   |
+----------------------------------------------------------------------------+

The second monomial order has the first block local, and the second block
polynomial.
+----------------------------------------------------------------------------+
|i5 : A2 = QQ[x_1..x_n,y_1..y_m,MonomialOrder=>{RevLex=>n, m},Global=>false];|
+----------------------------------------------------------------------------+
|i6 : substitute(f,A2)                                                       |
|                                                                            |
|      10               5      2                                             |
|o6 = y   + y  + 1 + x y  + x x                                              |
|      1     3        1 2    1 2                                             |
|                                                                            |
|o6 : A2                                                                     |
+----------------------------------------------------------------------------+
|i7 : x_1*y_2^5 < 1_A2                                                       |
|                                                                            |
|o7 = true                                                                   |
+----------------------------------------------------------------------------+

The third example has three blocks of variables.
+-----------------------------------------------------------------------------+
|i8 : A3 = QQ[x_1..x_n,y_1..y_m,MonomialOrder=>{n, RevLex=>2,                 |
|-----------------------------------------------------------------------------|
|m-2},Global=>false];                                                         |
+-----------------------------------------------------------------------------+
|i9 : substitute(f,A3)                                                        |
|                                                                             |
|        2      5             10                                              |
|o9 = x x  + x y  + y  + 1 + y                                                |
|      1 2    1 2    3        1                                               |
|                                                                             |
|o9 : A3                                                                      |
+-----------------------------------------------------------------------------+

Singular Book 1.6.13 -- normal form
***********************************

Normal forms in Macaulay2 are done using the remainder operator %.
+---------------------------------------+
|i1 : R = QQ[x,y,z];                    |
+---------------------------------------+
|i2 : f = x^2*y*z+x*y^2*z+y^2*z+z^3+x*y;|
+---------------------------------------+
|i3 : f1 = x*y+y^2-1                    |
|                                       |
|            2                          |
|o3 = x*y + y  - 1                      |
|                                       |
|o3 : R                                 |
+---------------------------------------+
|i4 : f2 = x*y                          |
|                                       |
|o4 = x*y                               |
|                                       |
|o4 : R                                 |
+---------------------------------------+
|i5 : G = ideal(f1,f2)                  |
|                                       |
|                   2                   |
|o5 = ideal (x*y + y  - 1, x*y)         |
|                                       |
|o5 : Ideal of R                        |
+---------------------------------------+
Macaulay2 computes a Groebner basis of G, and uses that to find the normal form
of f. In Macaulay2, all remainders are reduced normal forms (at least for
non-local orders).
+-----------+
|i6 : f % G |
|           |
|      3    |
|o6 = z  + z|
|           |
|o6 : R     |
+-----------+

In order to reduce using a non Groebner basis, use forceGB,
+----------------------------+
|i7 : f % (forceGB gens G)   |
|                            |
|      2     3    2          |
|o7 = y z + z  - y  + x*z + 1|
|                            |
|o7 : R                      |
+----------------------------+
This is a different answer from the SINGULAR book, since the choice of divisor
affects the answer.
+----------------------------------+
|i8 : f % (forceGB matrix{{f2,f1}})|
|                                  |
|      2     3                     |
|o8 = y z + z                      |
|                                  |
|o8 : R                            |
+----------------------------------+

Singular Book 1.7.10 -- standard bases
**************************************

We show the Groebner and standard bases of an ideal under several different
orders and localizations.  First, the default order is graded (degree) reverse
lexicographic.
+----------------------------------+
|i1 : A = QQ[x,y];                 |
+----------------------------------+
|i2 : I = ideal "x10+x9y2,y8-x2y7";|
|                                  |
|o2 : Ideal of A                   |
+----------------------------------+
|i3 : transpose gens gb I          |
|                                  |
|o3 = {-9}  | x2y7-y8   |          |
|     {-11} | x9y2+x10  |          |
|     {-13} | x12y+xy11 |          |
|     {-13} | x13-xy12  |          |
|     {-14} | y14+xy12  |          |
|     {-14} | xy13+y12  |          |
|                                  |
|             6      1             |
|o3 : Matrix A  <-- A              |
+----------------------------------+

Lexicographic order:
+-------------------------------------+
|i4 : A1 = QQ[x,y,MonomialOrder=>Lex];|
+-------------------------------------+
|i5 : I = substitute(I,A1)            |
|                                     |
|             10    9 2     2 7    8  |
|o5 = ideal (x   + x y , - x y  + y ) |
|                                     |
|o5 : Ideal of A1                     |
+-------------------------------------+
|i6 : transpose gens gb I             |
|                                     |
|o6 = {-15} | y15-y12  |              |
|     {-14} | xy12+y14 |              |
|     {-9}  | x2y7-y8  |              |
|     {-11} | x10+x9y2 |              |
|                                     |
|              4       1              |
|o6 : Matrix A1  <-- A1               |
+-------------------------------------+

Now we change to a local order
+-------------------------------------------------------------------+
|i7 : B = QQ[x,y,MonomialOrder=>{Weights=>{-1,-1},2},Global=>false];|
+-------------------------------------------------------------------+
|i8 : I = substitute(I,B)                                           |
|                                                                   |
|             10    9 2   8    2 7                                  |
|o8 = ideal (x   + x y , y  - x y )                                 |
|                                                                   |
|o8 : Ideal of B                                                    |
+-------------------------------------------------------------------+
|i9 : transpose gens gb I                                           |
|                                                                   |
|o9 = {-9}  | y8-x2y7  |                                            |
|     {-11} | x10+x9y2 |                                            |
|                                                                   |
|             2      1                                              |
|o9 : Matrix B  <-- B                                               |
+-------------------------------------------------------------------+

Another local order: negative lexicographic.
+-----------------------------------------------------------------------------+
|i10 : B = QQ[x,y,MonomialOrder=>{Weights=>{-1,0},Weights=>{0,-1}},Global=>   |
|-----------------------------------------------------------------------------|
|false];                                                                      |
+-----------------------------------------------------------------------------+
|i11 : I = substitute(I,B)                                                    |
|                                                                             |
|              9 2    10   8    2 7                                           |
|o11 = ideal (x y  + x  , y  - x y )                                          |
|                                                                             |
|o11 : Ideal of B                                                             |
+-----------------------------------------------------------------------------+
|i12 : transpose gens gb I                                                    |
|                                                                             |
|o12 = {-9}  | y8-x2y7   |                                                    |
|      {-11} | x9y2+x10  |                                                    |
|      {-16} | x13-x13y3 |                                                    |
|                                                                             |
|              3      1                                                       |
|o12 : Matrix B  <-- B                                                        |
+-----------------------------------------------------------------------------+

One method to compute a standard basis is via homogenization.  The example
below does this, obtaining a standard basis which is not minimal.
+-----------------------------------------------------------------------------+
|i13 : M = matrix{{1,1,1},{0,-1,-1},{0,0,-1}}                                 |
|                                                                             |
|o13 = | 1 1  1  |                                                            |
|      | 0 -1 -1 |                                                            |
|      | 0 0  -1 |                                                            |
|                                                                             |
|               3       3                                                     |
|o13 : Matrix ZZ  <-- ZZ                                                      |
+-----------------------------------------------------------------------------+
|i14 : mo = apply(entries M, e -> Weights => e)                               |
|                                                                             |
|o14 = {Weights => {1, 1, 1}, Weights => {0, -1, -1}, Weights => {0, 0, -1}}  |
|                                                                             |
|o14 : List                                                                   |
+-----------------------------------------------------------------------------+
|i15 : C = QQ[t,x,y,MonomialOrder=>mo];                                       |
+-----------------------------------------------------------------------------+
|i16 : I = homogenize(substitute(I,C),t)                                      |
|                                                                             |
|                  8    2 7     10    9 2       11    12    13      12        |
|o16 = ideal (- t*y  + x y , t*x   + x y , t*x*y   + x  y, x   - x*y  ,       |
|      -----------------------------------------------------------------------|
|           12    14   2 12      13                                           |
|      t*x*y   + y  , t y   + x*y  )                                          |
|                                                                             |
|o16 : Ideal of C                                                             |
+-----------------------------------------------------------------------------+
|i17 : transpose gens gb I                                                    |
|                                                                             |
|o17 = {-9}  | ty8-x2y7   |                                                   |
|      {-11} | tx10+x9y2  |                                                   |
|      {-13} | x12y+x3y10 |                                                   |
|      {-13} | x13-xy12   |                                                   |
|      {-14} | x3y11+y14  |                                                   |
|      {-14} | x4y10+xy13 |                                                   |
|      {-14} | x11y3-x5y9 |                                                   |
|      {-15} | x6y9-y15   |                                                   |
|      {-15} | x10y5+x7y8 |                                                   |
|      {-16} | x8y8-x2y14 |                                                   |
|                                                                             |
|              10      1                                                      |
|o17 : Matrix C   <-- C                                                       |
+-----------------------------------------------------------------------------+
|i18 : substitute(transpose gens gb I, {t=>1})                                |
|                                                                             |
|o18 = {-9}  | -x2y7+y8   |                                                   |
|      {-11} | x9y2+x10   |                                                   |
|      {-13} | x12y+x3y10 |                                                   |
|      {-13} | x13-xy12   |                                                   |
|      {-14} | x3y11+y14  |                                                   |
|      {-14} | x4y10+xy13 |                                                   |
|      {-14} | x11y3-x5y9 |                                                   |
|      {-15} | x6y9-y15   |                                                   |
|      {-15} | x10y5+x7y8 |                                                   |
|      {-16} | x8y8-x2y14 |                                                   |
|                                                                             |
|              10      1                                                      |
|o18 : Matrix C   <-- C                                                       |
+-----------------------------------------------------------------------------+
The first two elements form a standard basis.

Singular Book 1.7.12 -- highest corner
**************************************

This is not implemented in macaulay2 yet.

Singular Book 1.8.1 -- ideal membership
***************************************

+------------------------------------------+
|i1 : A = QQ[x,y];                         |
+------------------------------------------+
|i2 : I = ideal(x^10+x^9*y^2, y^8-x^2*y^7);|
|                                          |
|o2 : Ideal of A                           |
+------------------------------------------+
|i3 : f = x^2*y^7+y^14;                    |
+------------------------------------------+
|i4 : f % I                                |
|                                          |
|          12    8                         |
|o4 = - x*y   + y                          |
|                                          |
|o4 : A                                    |
+------------------------------------------+
So this f is not in the ideal I.
+---------------------+
|i5 : f = x*y^13+y^12;|
+---------------------+
|i6 : f % I           |
|                     |
|o6 = 0               |
|                     |
|o6 : A               |
+---------------------+
This f is in the ideal I.

Check inclusion and equality of ideals.
+-------------------------------+
|i7 : K = ideal(f,x^2*y^7+y^14);|
|                               |
|o7 : Ideal of A                |
+-------------------------------+
|i8 : (gens K) % I              |
|                               |
|o8 = | 0 -xy12+y8 |            |
|                               |
|             1      2          |
|o8 : Matrix A  <-- A           |
+-------------------------------+
In Macaulay2, inclusion of ideals can be tested using
isSubset(Ideal,Ideal), and equality can be checked
using Ideal == Ideal (missing documentation).  In both cases the necessary
Groebner bases are computed, if they have not already been computed.
+------------------+
|i9 : isSubset(K,I)|
|                  |
|o9 = false        |
+------------------+
|i10 : K == I      |
|                  |
|o10 = false       |
+------------------+
+-------------------------------+
|i11 : K = ideal(f,y^14+x*y^12);|
|                               |
|o11 : Ideal of A               |
+-------------------------------+
|i12 : (gens K) % I             |
|                               |
|o12 = 0                        |
|                               |
|              1      2         |
|o12 : Matrix A  <-- A          |
+-------------------------------+
|i13 : isSubset(K,I)            |
|                               |
|o13 = true                     |
+-------------------------------+
|i14 : K == I                   |
|                               |
|o14 = false                    |
+-------------------------------+

Singular Book 1.8.2 -- linear combination of ideal members
**********************************************************

Singular Book 1.8.4 -- elimination of variables
***********************************************

There are several methods to eliminate variables in Macaulay2.
+-------------------------------------------------------------------+
|i1 : A = QQ[t,x,y,z];                                              |
+-------------------------------------------------------------------+
|i2 : I = ideal"t2+x2+y2+z2,t2+2x2-xy-z2,t+y3-z3";                  |
|                                                                   |
|o2 : Ideal of A                                                    |
+-------------------------------------------------------------------+
|i3 : eliminate(I,t)                                                |
|                                                                   |
|             2          2     2   6     3 3    6           2     2 |
|o3 = ideal (x  - x*y - y  - 2z , y  - 2y z  + z  + x*y + 2y  + 3z )|
|                                                                   |
|o3 : Ideal of A                                                    |
+-------------------------------------------------------------------+

Alternatively, one may do it by hand: the elements of the Groebner basis under
an elimination order not involving t generate the elimination ideal.
+-------------------------------------------+
|i4 : A1 = QQ[t,x,y,z,MonomialOrder=>{1,3}];|
+-------------------------------------------+
|i5 : I = substitute(I,A1);                 |
|                                           |
|o5 : Ideal of A1                           |
+-------------------------------------------+
|i6 : transpose gens gb I                   |
|                                           |
|o6 = {-2} | x2-xy-y2-2z2           |       |
|     {-6} | y6-2y3z3+z6+xy+2y2+3z2 |       |
|     {-3} | t+y3-z3                |       |
|                                           |
|              3       1                    |
|o6 : Matrix A1  <-- A1                     |
+-------------------------------------------+

Here is another elimination ideal.  Weights not given are assumed to be zero.
+--------------------------------------------------+
|i7 : A2 = QQ[t,x,y,z,MonomialOrder=>Weights=>{1}];|
+--------------------------------------------------+
|i8 : I = substitute(I,A2);                        |
|                                                  |
|o8 : Ideal of A2                                  |
+--------------------------------------------------+
|i9 : transpose gens gb I                          |
|                                                  |
|o9 = {-2} | x2-xy-y2-2z2           |              |
|     {-6} | y6-2y3z3+z6+xy+2y2+3z2 |              |
|     {-3} | t+y3-z3                |              |
|                                                  |
|              3       1                           |
|o9 : Matrix A2  <-- A2                            |
+--------------------------------------------------+

The same order as the previous one:
+--------------------------------------------------+
|i10 : A3 = QQ[t,x,y,z,MonomialOrder=>Eliminate 1];|
+--------------------------------------------------+
|i11 : I = substitute(I,A3);                       |
|                                                  |
|o11 : Ideal of A3                                 |
+--------------------------------------------------+
|i12 : transpose gens gb I                         |
|                                                  |
|o12 = {-2} | x2-xy-y2-2z2           |             |
|      {-6} | y6-2y3z3+z6+xy+2y2+3z2 |             |
|      {-3} | t+y3-z3                |             |
|                                                  |
|               3       1                          |
|o12 : Matrix A3  <-- A3                           |
+--------------------------------------------------+

Singular Book 1.8.6 -- Zariski closure of the image
***************************************************

We compute an implicit equation for the surface defined parametrically by the
map $f : A^2 \rightarrow{} A^3, (u,v) \mapsto{} (uv,uv^2,u^2)$.
+--------------------------------------------+
|i1 : A = QQ[u,v,x,y,z];                     |
+--------------------------------------------+
|i2 : I = ideal "x-uv,y-uv2,z-u2"            |
|                                            |
|                            2         2     |
|o2 = ideal (- u*v + x, - u*v  + y, - u  + z)|
|                                            |
|o2 : Ideal of A                             |
+--------------------------------------------+
|i3 : eliminate(I,{u,v})                     |
|                                            |
|            4    2                          |
|o3 = ideal(x  - y z)                        |
|                                            |
|o3 : Ideal of A                             |
+--------------------------------------------+
This ideal defines the closure of the map $f$, the Whitney umbrella.

Alternatively, we could take the coimage of the ring homomorphism g
corresponding to f.

+----------------------------------------------------------------+
|i4 : g = map(QQ[u,v],QQ[x,y,z],{x => u*v, y => u*v^2, z => u^2})|
|                                                                |
|                                       2   2                    |
|o4 = map (QQ[u..v], QQ[x..z], {u*v, u*v , u })                  |
|                                                                |
|o4 : RingMap QQ[u..v] <-- QQ[x..z]                              |
+----------------------------------------------------------------+
|i5 : coimage g                                                  |
|                                                                |
|     QQ[x..z]                                                   |
|o5 = --------                                                   |
|      4    2                                                    |
|     x  - y z                                                   |
|                                                                |
|o5 : QuotientRing                                               |
+----------------------------------------------------------------+

Singular Book 1.8.7 -- solving equations
****************************************

+------------------------------------------------+
|i1 : A = QQ[x,y,z,MonomialOrder=>Lex];          |
+------------------------------------------------+
|i2 : I = ideal(x^2+y+z-1, x+y^2+z-1, x+y+z^2-1);|
|                                                |
|o2 : Ideal of A                                 |
+------------------------------------------------+
|i3 : transpose gens gb I                        |
|                                                |
|o3 = {-6} | z6-4z4+4z3-z2 |                     |
|     {-4} | 2yz2+z4-z2    |                     |
|     {-2} | y2-y-z2+z     |                     |
|     {-2} | x+y+z2-1      |                     |
|                                                |
|             4      1                           |
|o3 : Matrix A  <-- A                            |
+------------------------------------------------+
Now we need to implement the solver!

Singular Book 1.8.9 -- radical membership
*****************************************

Recall that an element $f$ is in an ideal $I$ if $1 \in (I, tf-1) \subset
R[t]$.
+---------------------------------+
|i1 : A = QQ[x,y,z];              |
+---------------------------------+
|i2 : I = ideal"x5,xy3,y7,z3+xyz";|
|                                 |
|o2 : Ideal of A                  |
+---------------------------------+
|i3 : f = x+y+z;                  |
+---------------------------------+
+-------------------------------------------------------+
|i4 : B = A[t];                                         |
+-------------------------------------------------------+
|i5 : J = substitute(I,B) + ideal(f*t-1)                |
|                                                       |
|             5     3   7           3                   |
|o5 = ideal (x , x*y , y , x*y*z + z , (x + y + z)t - 1)|
|                                                       |
|o5 : Ideal of B                                        |
+-------------------------------------------------------+
|i6 : 1 % J                                             |
|                                                       |
|o6 = 0                                                 |
|                                                       |
|o6 : B                                                 |
+-------------------------------------------------------+
The polynomial f is in the radical. Let's compute the radical to make sure.
+--------------------+
|i7 : radical I      |
|                    |
|o7 = ideal (z, y, x)|
|                    |
|o7 : Ideal of A     |
+--------------------+

Singular Book 1.8.11 -- intersection of ideals
**********************************************

Intersecting ideals using the Macaulay2 intersect, function.
+-------------------------+
|i1 : A = QQ[x,y,z];      |
+-------------------------+
|i2 : I1 = ideal(x,y);    |
|                         |
|o2 : Ideal of A          |
+-------------------------+
|i3 : I2 = ideal(y^2,z);  |
|                         |
|o3 : Ideal of A          |
+-------------------------+
|i4 : intersect(I1,I2)    |
|                         |
|                       2 |
|o4 = ideal (y*z, x*z, y )|
|                         |
|o4 : Ideal of A          |
+-------------------------+
Now we use the method described in the Singular book in section 1.8.7.
+---------------------------------------------+
|i5 : B = QQ[t,x,y,z];                        |
+---------------------------------------------+
|i6 : I1 = substitute(I1,B);                  |
|                                             |
|o6 : Ideal of B                              |
+---------------------------------------------+
|i7 : I2 = substitute(I2,B);                  |
|                                             |
|o7 : Ideal of B                              |
+---------------------------------------------+
|i8 : J = t*I1 + (1-t)*I2                     |
|                                             |
|                           2    2            |
|o8 = ideal (t*x, t*y, - t*y  + y , - t*z + z)|
|                                             |
|o8 : Ideal of B                              |
+---------------------------------------------+
|i9 : eliminate(J,t)                          |
|                                             |
|                       2                     |
|o9 = ideal (y*z, x*z, y )                    |
|                                             |
|o9 : Ideal of B                              |
+---------------------------------------------+

Singular Book 1.8.13 -- quotient of ideals
******************************************

+-----------------------+
|i1 : A = QQ[x,y,z];    |
+-----------------------+
|i2 : I1 = ideal(x,y);  |
|                       |
|o2 : Ideal of A        |
+-----------------------+
|i3 : I2 = ideal(y^2,z);|
|                       |
|o3 : Ideal of A        |
+-----------------------+
|i4 : I1 : I2           |
|                       |
|o4 = ideal (y, x)      |
|                       |
|o4 : Ideal of A        |
+-----------------------+
The quotient function is the same as the colon operator, except that optional
arguments may be given.
+--------------------+
|i5 : quotient(I1,I2)|
|                    |
|o5 = ideal (y, x)   |
|                    |
|o5 : Ideal of A     |
+--------------------+
Now we use the method described in Lemma 1.8.12 in the Singular book.
+-----------------------------------+
|i6 : J1 = intersect(I1,ideal(I2_0))|
|                                   |
|            2                      |
|o6 = ideal y                       |
|                                   |
|o6 : Ideal of A                    |
+-----------------------------------+
|i7 : J2 = intersect(I1,ideal(I2_1))|
|                                   |
|o7 = ideal (y*z, x*z)              |
|                                   |
|o7 : Ideal of A                    |
+-----------------------------------+
Now divide each generator of J1 by x, and each generator of J2 by y.  Notice
that division uses two slashes.  Using only one slash gives the quotient in the
fraction ring.
+---------------------------------------+
|i8 : K1 = ideal(J1_0//I2_0)            |
|                                       |
|o8 = ideal 1                           |
|                                       |
|o8 : Ideal of A                        |
+---------------------------------------+
|i9 : K2 = ideal(J2_0//I2_1, J2_1//I2_1)|
|                                       |
|o9 = ideal (y, x)                      |
|                                       |
|o9 : Ideal of A                        |
+---------------------------------------+
|i10 : intersect(K1,K2)                 |
|                                       |
|o10 = ideal (y, x)                     |
|                                       |
|o10 : Ideal of A                       |
+---------------------------------------+

Singular Book 1.8.15 -- saturation
**********************************

+---------------------------------------+
|i1 : A = QQ[x,y,z];                    |
+---------------------------------------+
|i2 : I1 = ideal(x^5*z^3, x*y*z, y*z^4);|
|                                       |
|o2 : Ideal of A                        |
+---------------------------------------+
|i3 : saturate(I1,z)                    |
|                                       |
|                5                      |
|o3 = ideal (y, x )                     |
|                                       |
|o3 : Ideal of A                        |
+---------------------------------------+
Now we compute the saturation using a loop.
+----------------------------------+
|i4 : J = I1:z                     |
|                                  |
|                    3   5 2       |
|o4 = ideal (x*y, y*z , x z )      |
|                                  |
|o4 : Ideal of A                   |
+----------------------------------+
|i5 : k = 0;                       |
+----------------------------------+
|i6 : while not isSubset(J,I1) do (|
|        k = k+1;                  |
|        I1 = J;                   |
|        J = I1 : z;               |
|        );                        |
+----------------------------------+
|i7 : J                            |
|                                  |
|                5                 |
|o7 = ideal (y, x )                |
|                                  |
|o7 : Ideal of A                   |
+----------------------------------+
|i8 : k                            |
|                                  |
|o8 = 4                            |
+----------------------------------+
We needed to use quotient four times.

Singular Book 1.8.18 -- kernel of a ring map
********************************************

First, we use Macaulay2's kernel(RingMap), function.
+---------------------------------+
|i1 : A = QQ[x,y,z];              |
+---------------------------------+
|i2 : B = QQ[a,b];                |
+---------------------------------+
|i3 : phi = map(B,A,{a^2,a*b,b^2})|
|                                 |
|                  2        2     |
|o3 = map (B, A, {a , a*b, b })   |
|                                 |
|o3 : RingMap B <-- A             |
+---------------------------------+
|i4 : kernel phi                  |
|                                 |
|            2                    |
|o4 = ideal(y  - x*z)             |
|                                 |
|o4 : Ideal of A                  |
+---------------------------------+
Now use the elimination of variables method.
+------------------------------------+
|i5 : C = QQ[x,y,z,a,b]              |
|                                    |
|o5 = C                              |
|                                    |
|o5 : PolynomialRing                 |
+------------------------------------+
|i6 : H = ideal(x-a^2, y-a*b, z-b^2);|
|                                    |
|o6 : Ideal of C                     |
+------------------------------------+
|i7 : eliminate(H, {a,b})            |
|                                    |
|            2                       |
|o7 = ideal(y  - x*z)                |
|                                    |
|o7 : Ideal of C                     |
+------------------------------------+

Singular Book 1.8.19 -- algebraic dependence
********************************************

Singular Book 1.8.20 -- subalgebra membership
*********************************************

Singular Book 2.1.6 -- matrix operations
****************************************

In Macaulay2, matrices are defined over a ring.  There are many ways to make a
matrix, but the easiest is to use the matrix, routine.
+---------------------------------------------+
|i1 : A = QQ[x,y,z];                          |
+---------------------------------------------+
|i2 : M = matrix{{1, x+y, z^2},               |
|                {x, 0,   x*y*z}}             |
|                                             |
|o2 = | 1 x+y z2  |                           |
|     | x 0   xyz |                           |
|                                             |
|             2      3                        |
|o2 : Matrix A  <-- A                         |
+---------------------------------------------+
|i3 : N = matrix(A, {{1,2,3},{4,5,6},{7,8,9}})|
|                                             |
|o3 = | 1 2 3 |                               |
|     | 4 5 6 |                               |
|     | 7 8 9 |                               |
|                                             |
|             3      3                        |
|o3 : Matrix A  <-- A                         |
+---------------------------------------------+
The usual matrix arithmetic operations work.
+-----------------------------------------------------------------------------+
|i4 : M+M                                                                     |
|                                                                             |
|o4 = | 2  2x+2y 2z2  |                                                       |
|     | 2x 0     2xyz |                                                       |
|                                                                             |
|             2      3                                                        |
|o4 : Matrix A  <-- A                                                         |
+-----------------------------------------------------------------------------+
|i5 : x*N                                                                     |
|                                                                             |
|o5 = | x  2x 3x |                                                            |
|     | 4x 5x 6x |                                                            |
|     | 7x 8x 9x |                                                            |
|                                                                             |
|             3      3                                                        |
|o5 : Matrix A  <-- A                                                         |
+-----------------------------------------------------------------------------+
|i6 : M*N                                                                     |
|                                                                             |
|o6 = | 7z2+4x+4y+1 8z2+5x+5y+2 9z2+6x+6y+3 |                                 |
|     | 7xyz+x      8xyz+2x     9xyz+3x     |                                 |
|                                                                             |
|             2      3                                                        |
|o6 : Matrix A  <-- A                                                         |
+-----------------------------------------------------------------------------+
|i7 : N^3                                                                     |
|                                                                             |
|o7 = | 468  576  684  |                                                      |
|     | 1062 1305 1548 |                                                      |
|     | 1656 2034 2412 |                                                      |
|                                                                             |
|             3      3                                                        |
|o7 : Matrix A  <-- A                                                         |
+-----------------------------------------------------------------------------+
|i8 : ((x+y+z)*N)^3                                                           |
|                                                                             |
|o8 = | 468x3+1404x2y+1404xy2+                                                |
|     | 1062x3+3186x2y+3186xy2                                                |
|     | 1656x3+4968x2y+4968xy2                                                |
|     ------------------------------------------------------------------------|
|     468y3+1404x2z+2808xyz+1404y2z+1404xz2+1404yz2+468z3                     |
|     +1062y3+3186x2z+6372xyz+3186y2z+3186xz2+3186yz2+1062z3                  |
|     +1656y3+4968x2z+9936xyz+4968y2z+4968xz2+4968yz2+1656z3                  |
|     ------------------------------------------------------------------------|
|     576x3+1728x2y+1728xy2+576y3+1728x2z+3456xyz+1728y2z+1728xz2+1728yz2+576z|
|     1305x3+3915x2y+3915xy2+1305y3+3915x2z+7830xyz+3915y2z+3915xz2+3915yz2+13|
|     2034x3+6102x2y+6102xy2+2034y3+6102x2z+12204xyz+6102y2z+6102xz2+6102yz2+2|
|     ------------------------------------------------------------------------|
|     3     684x3+2052x2y+2052xy2+                                            |
|     05z3  1548x3+4644x2y+4644xy2                                            |
|     034z3 2412x3+7236x2y+7236xy2                                            |
|     ------------------------------------------------------------------------|
|     684y3+2052x2z+4104xyz+2052y2z+2052xz2+2052yz2+684z3     |               |
|     +1548y3+4644x2z+9288xyz+4644y2z+4644xz2+4644yz2+1548z3  |               |
|     +2412y3+7236x2z+14472xyz+7236y2z+7236xz2+7236yz2+2412z3 |               |
|                                                                             |
|             3      3                                                        |
|o8 : Matrix A  <-- A                                                         |
+-----------------------------------------------------------------------------+
Indices in Macaulay2 are always 0 based, so the upper left entry is (0,0).
Indexing is performed using _.
+------------+
|i9 : M_(1,2)|
|            |
|o9 = x*y*z  |
|            |
|o9 : A      |
+------------+
Matrices cannot be modified.  Make a MutableMatrix if you want to modify a
matrix.
+--------------------------+
|i10 : M1 = mutableMatrix M|
|                          |
|o10 = | 1 x+y z2  |       |
|      | x 0   xyz |       |
|                          |
|o10 : MutableMatrix       |
+--------------------------+
|i11 : M1_(1,2) = 37_A     |
|                          |
|o11 = 37                  |
|                          |
|o11 : A                   |
+--------------------------+
|i12 : M1                  |
|                          |
|o12 = | 1 x+y z2 |        |
|      | x 0   37 |        |
|                          |
|o12 : MutableMatrix       |
+--------------------------+
|i13 : matrix M1           |
|                          |
|o13 = | 1 x+y z2 |        |
|      | x 0   37 |        |
|                          |
|              2      3    |
|o13 : Matrix A  <-- A     |
+--------------------------+
Matrices can be concatenated, either horizontally or vertically.  The number of
rows must match for horizontal concatenation, and the number of columns must
match for vertical concatenation.
+-----------------------------+
|i14 : M | M                  |
|                             |
|o14 = | 1 x+y z2  1 x+y z2  ||
|      | x 0   xyz x 0   xyz ||
|                             |
|              2      6       |
|o14 : Matrix A  <-- A        |
+-----------------------------+
|i15 : M || N                 |
|                             |
|o15 = | 1 x+y z2  |          |
|      | x 0   xyz |          |
|      | 1 2   3   |          |
|      | 4 5   6   |          |
|      | 7 8   9   |          |
|                             |
|              5      3       |
|o15 : Matrix A  <-- A        |
+-----------------------------+
Use ideal(Matrix), to obtain the ideal generated by
the entries of a matrix.
+---------------------------------------+
|i16 : ideal M                          |
|                                       |
|                              2        |
|o16 = ideal (1, x, x + y, 0, z , x*y*z)|
|                                       |
|o16 : Ideal of A                       |
+---------------------------------------+
The $n$ by $n$ identity matrix is the identity map of the freemodule $A^n$.
+----------------------+
|i17 : F = A^5         |
|                      |
|       5              |
|o17 = A               |
|                      |
|o17 : A-module, free  |
+----------------------+
|i18 : id_(A^5)        |
|                      |
|o18 = | 1 0 0 0 0 |   |
|      | 0 1 0 0 0 |   |
|      | 0 0 1 0 0 |   |
|      | 0 0 0 1 0 |   |
|      | 0 0 0 0 1 |   |
|                      |
|              5      5|
|o18 : Matrix A  <-- A |
+----------------------+
In Macaulay2, integer matrices are just matrices defined over the ring of
integers ZZ.
+-----------------------------+
|i19 : matrix{{1,2,3},{4,5,6}}|
|                             |
|o19 = | 1 2 3 |              |
|      | 4 5 6 |              |
|                             |
|               2       3     |
|o19 : Matrix ZZ  <-- ZZ      |
+-----------------------------+

See also
========

  * matrices

Singular Book 2.1.7 -- maps induced by Hom
******************************************

+---------------------------------------------+
|i1 : A = QQ[x,y,z]                           |
|                                             |
|o1 = A                                       |
|                                             |
|o1 : PolynomialRing                          |
+---------------------------------------------+
|i2 : M = matrix(A, {{1,2,3},{4,5,6},{7,8,9}})|
|                                             |
|o2 = | 1 2 3 |                               |
|     | 4 5 6 |                               |
|     | 7 8 9 |                               |
|                                             |
|             3      3                        |
|o2 : Matrix A  <-- A                         |
+---------------------------------------------+
|i3 : Hom(M,A^2)                              |
|                                             |
|o3 = | 1 0 4 0 7 0 |                         |
|     | 0 1 0 4 0 7 |                         |
|     | 2 0 5 0 8 0 |                         |
|     | 0 2 0 5 0 8 |                         |
|     | 3 0 6 0 9 0 |                         |
|     | 0 3 0 6 0 9 |                         |
|                                             |
|             6      6                        |
|o3 : Matrix A  <-- A                         |
+---------------------------------------------+
|i4 : Hom(A^2,M)                              |
|                                             |
|o4 = | 1 2 3 0 0 0 |                         |
|     | 4 5 6 0 0 0 |                         |
|     | 7 8 9 0 0 0 |                         |
|     | 0 0 0 1 2 3 |                         |
|     | 0 0 0 4 5 6 |                         |
|     | 0 0 0 7 8 9 |                         |
|                                             |
|             6      6                        |
|o4 : Matrix A  <-- A                         |
+---------------------------------------------+
Notice that the basis that Macaulay2 uses for Hom(A^3,A^2) is different than
the basis used by Singular.

The function contraHom of the Singular book in example 2.1.7 could be coded in
the following way.
+-------------------------------------------------------+
|i5 : contraHom = (M, s) -> (                           |
|         (n,m) := (numgens target M, numgens source M);|
|         R := mutableMatrix(ring M, s*n, s*m);         |
|         for b from 0 to m-1 do                        |
|           for a from 0 to s-1 do                      |
|             for c from 0 to n-1 do                    |
|               R_(a*n+c,a*m+b) = M_(b,c);              |
|         matrix R                                      |
|         )                                             |
|                                                       |
|o5 = contraHom                                         |
|                                                       |
|o5 : FunctionClosure                                   |
+-------------------------------------------------------+
Let's try an example.
+---------------------+
|i6 : contraHom(M,2)  |
|                     |
|o6 = | 1 4 7 0 0 0 | |
|     | 2 5 8 0 0 0 | |
|     | 3 6 9 0 0 0 | |
|     | 0 0 0 1 4 7 | |
|     | 0 0 0 2 5 8 | |
|     | 0 0 0 3 6 9 | |
|                     |
|             6      6|
|o6 : Matrix A  <-- A |
+---------------------+

Singular Book 2.1.10 -- Submodules of A^n
*****************************************

A common method of creating a submodule of A^n in Macaulay2 is to take the
image of a matrix.  This will be a submodule generated by the columns of the
matrix.
+----------------------------------------------------+
|i1 : A = QQ[x,y,z];                                 |
+----------------------------------------------------+
|i2 : f = matrix{{x*y-1,y^4},{z^2+3,x^3},{x*y*z,z^2}}|
|                                                    |
|o2 = | xy-1 y4 |                                    |
|     | z2+3 x3 |                                    |
|     | xyz  z2 |                                    |
|                                                    |
|             3      2                               |
|o2 : Matrix A  <-- A                                |
+----------------------------------------------------+
|i3 : M = image f                                    |
|                                                    |
|o3 = image | xy-1 y4 |                              |
|           | z2+3 x3 |                              |
|           | xyz  z2 |                              |
|                                                    |
|                             3                      |
|o3 : A-module, submodule of A                       |
+----------------------------------------------------+
|i4 : numgens M                                      |
|                                                    |
|o4 = 2                                              |
+----------------------------------------------------+
|i5 : ambient M                                      |
|                                                    |
|      3                                             |
|o5 = A                                              |
|                                                    |
|o5 : A-module, free                                 |
+----------------------------------------------------+
A submodule can easily be moved to quotient rings.
+------------------------------+
|i6 : Q = A/(x^2+y^2+z^2);     |
+------------------------------+
|i7 : substitute(M,Q)          |
|                              |
|o7 = image | xy-1 y4       |  |
|           | z2+3 -xy2-xz2 |  |
|           | xyz  z2       |  |
|                              |
|                             3|
|o7 : Q-module, submodule of Q |
+------------------------------+

Singular Book 2.1.13 -- kernel, image and cokernel of a module homomorphism
***************************************************************************

In Macaulay2, a Matrix is the same thing as a module homomorphism. The
computation of the kernel of a module homomorphism is based on a Groebner basis
computation.
+------------------------------------------+
|i1 : A = QQ[x,y,z];                       |
+------------------------------------------+
|i2 : M = matrix{{x,x*y,z},{x^2,x*y*z,y*z}}|
|                                          |
|o2 = | x  xy  z  |                        |
|     | x2 xyz yz |                        |
|                                          |
|             2      3                     |
|o2 : Matrix A  <-- A                      |
+------------------------------------------+
|i3 : K = kernel M                         |
|                                          |
|o3 = image {2} | -y2z+yz2 |               |
|           {3} | -xz+yz   |               |
|           {2} | x2y-xyz  |               |
|                                          |
|                             3            |
|o3 : A-module, submodule of A             |
+------------------------------------------+
The image and cokernel of a matrix require no computation.
+------------------------------+
|i4 : I = image M              |
|                              |
|o4 = image | x  xy  z  |      |
|           | x2 xyz yz |      |
|                              |
|                             2|
|o4 : A-module, submodule of A |
+------------------------------+
|i5 : N = cokernel M           |
|                              |
|o5 = cokernel | x  xy  z  |   |
|              | x2 xyz yz |   |
|                              |
|                            2 |
|o5 : A-module, quotient of A  |
+------------------------------+
|i6 : P = coimage M            |
|                              |
|o6 = cokernel {2} | -y2z+yz2 ||
|              {3} | -xz+yz   ||
|              {2} | x2y-xyz  ||
|                              |
|                            3 |
|o6 : A-module, quotient of A  |
+------------------------------+

Singular Book 2.1.20 -- sum, intersection, module quotient
**********************************************************

+--------------------------------------+
|i1 : A = QQ[x,y,z];                   |
+--------------------------------------+
|i2 : M = image matrix{{x*y,x},{x*z,x}}|
|                                      |
|o2 = image | xy x |                   |
|           | xz x |                   |
|                                      |
|                             2        |
|o2 : A-module, submodule of A         |
+--------------------------------------+
|i3 : N = image matrix{{y^2,x},{z^2,x}}|
|                                      |
|o3 = image | y2 x |                   |
|           | z2 x |                   |
|                                      |
|                             2        |
|o3 : A-module, submodule of A         |
+--------------------------------------+
|i4 : M + N                            |
|                                      |
|o4 = image | xy x y2 x |              |
|           | xz x z2 x |              |
|                                      |
|                             2        |
|o4 : A-module, submodule of A         |
+--------------------------------------+
Notice that, in Macaulay2, each module comes equipped with a list of
generators, and operations such as sum do not try to simplify the list of
generators.

Intersection, quotients, annihilators are found using standard notation:
+-------------------------------+
|i5 : intersect(M,N)            |
|                               |
|o5 = image | x xy2-xz2 |       |
|           | x 0       |       |
|                               |
|                             2 |
|o5 : A-module, submodule of A  |
+-------------------------------+
|i6 : M : N                     |
|                               |
|o6 = ideal x                   |
|                               |
|o6 : Ideal of A                |
+-------------------------------+
|i7 : N : M                     |
|                               |
|o7 = ideal(y + z)              |
|                               |
|o7 : Ideal of A                |
+-------------------------------+
|i8 : Q = A/x^5;                |
+-------------------------------+
|i9 : M = substitute(M,Q)       |
|                               |
|o9 = image | xy x |            |
|           | xz x |            |
|                               |
|                             2 |
|o9 : Q-module, submodule of Q  |
+-------------------------------+
|i10 : ann M                    |
|                               |
|             4                 |
|o10 = ideal x                  |
|                               |
|o10 : Ideal of Q               |
+-------------------------------+
|i11 : M : x                    |
|                               |
|o11 = image | 1 y-z x4 |       |
|            | 1 0   0  |       |
|                               |
|                              2|
|o11 : Q-module, submodule of Q |
+-------------------------------+

Singular Book 2.1.24 -- submodules, presentation of a module
************************************************************

+------------------------------------------------+
|i1 : A = QQ[x,y,z]                              |
|                                                |
|o1 = A                                          |
|                                                |
|o1 : PolynomialRing                             |
+------------------------------------------------+
|i2 : N = image matrix{{x*y,0},{0,x*z},{y*z,z^2}}|
|                                                |
|o2 = image | xy 0  |                            |
|           | 0  xz |                            |
|           | yz z2 |                            |
|                                                |
|                             3                  |
|o2 : A-module, submodule of A                   |
+------------------------------------------------+
The submodule is generated by the two columns of this matrix.
+------------------------------+
|i3 : N + x*N                  |
|                              |
|o3 = image | xy 0  x2y 0   |  |
|           | 0  xz 0   x2z |  |
|           | yz z2 xyz xz2 |  |
|                              |
|                             3|
|o3 : A-module, submodule of A |
+------------------------------+
It is easy to go between matrices and submodules.  Use
generators(Module), and image(Matrix),
(gens and generators are synonyms). There is no automatic conversion
between modules and matrices in Macaulay2.
+------------------------------------+
|i4 : f = matrix{{x*y,x*z},{y*z,z^2}}|
|                                    |
|o4 = | xy xz |                      |
|     | yz z2 |                      |
|                                    |
|             2      2               |
|o4 : Matrix A  <-- A                |
+------------------------------------+
|i5 : M = image f                    |
|                                    |
|o5 = image | xy xz |                |
|           | yz z2 |                |
|                                    |
|                             2      |
|o5 : A-module, submodule of A       |
+------------------------------------+
|i6 : g = gens M                     |
|                                    |
|o6 = | xy xz |                      |
|     | yz z2 |                      |
|                                    |
|             2      2               |
|o6 : Matrix A  <-- A                |
+------------------------------------+
|i7 : f == g                         |
|                                    |
|o7 = true                           |
+------------------------------------+
In Macaulay2, matrices are not automatically either presentation matrices or
generating matrices for a module.  You use whichever you have in mind.
+-----------------------------+
|i8 : N = cokernel f          |
|                             |
|o8 = cokernel | xy xz |      |
|              | yz z2 |      |
|                             |
|                            2|
|o8 : A-module, quotient of A |
+-----------------------------+
|i9 : presentation N          |
|                             |
|o9 = | xy xz |               |
|     | yz z2 |               |
|                             |
|             2      2        |
|o9 : Matrix A  <-- A         |
+-----------------------------+
|i10 : presentation M         |
|                             |
|o10 = {2} | -z |             |
|      {2} | y  |             |
|                             |
|              2      1       |
|o10 : Matrix A  <-- A        |
+-----------------------------+
Notice that the presentation of N requires no computation, whereas the
presentation of M requires a syzygy computation.

See kernel(Matrix), gives a submodule, while
syz(Matrix), returns the matrix.
+-------------------------------+
|i11 : syz f                    |
|                               |
|o11 = {2} | -z |               |
|      {2} | y  |               |
|                               |
|              2      1         |
|o11 : Matrix A  <-- A          |
+-------------------------------+
|i12 : kernel f                 |
|                               |
|o12 = image {2} | -z |         |
|            {2} | y  |         |
|                               |
|                              2|
|o12 : A-module, submodule of A |
+-------------------------------+

Singular Book 2.1.26 -- computation of Hom
******************************************

+------------------------------------------------------+
|i1 : A = QQ[x,y,z];                                   |
+------------------------------------------------------+
|i2 : M = cokernel matrix(A, {{1,2,3},{4,5,6},{7,8,9}})|
|                                                      |
|o2 = cokernel | 1 2 3 |                               |
|              | 4 5 6 |                               |
|              | 7 8 9 |                               |
|                                                      |
|                            3                         |
|o2 : A-module, quotient of A                          |
+------------------------------------------------------+
|i3 : N = cokernel matrix{{x,y},{z,0}}                 |
|                                                      |
|o3 = cokernel | x y |                                 |
|              | z 0 |                                 |
|                                                      |
|                            2                         |
|o3 : A-module, quotient of A                          |
+------------------------------------------------------+
|i4 : H = Hom(M,N)                                     |
|                                                      |
|o4 = subquotient (| 1  0  |, | y x 0 0 0 0 |)         |
|                  | 0  1  |  | 0 z 0 0 0 0 |          |
|                  | -2 0  |  | 0 0 y x 0 0 |          |
|                  | 0  -2 |  | 0 0 0 z 0 0 |          |
|                  | 1  0  |  | 0 0 0 0 y x |          |
|                  | 0  1  |  | 0 0 0 0 0 z |          |
|                                                      |
|                               6                      |
|o4 : A-module, subquotient of A                       |
+------------------------------------------------------+
H is a subquotient module.  In Macaulay2, the most general form of a module is
as a subquotient: a submodule of a cokernel module.  For more about subquotient
modules, see modules.
+---------------------------+
|i5 : f = homomorphism H_{0}|
|                           |
|o5 = | 1 -2 1 |            |
|     | 0 0  0 |            |
|                           |
|o5 : Matrix N <-- M        |
+---------------------------+
|i6 : target f === N        |
|                           |
|o6 = true                  |
+---------------------------+
|i7 : source f === M        |
|                           |
|o7 = true                  |
+---------------------------+
|i8 : matrix f              |
|                           |
|o8 = | 1 -2 1 |            |
|     | 0 0  0 |            |
|                           |
|             2      3      |
|o8 : Matrix A  <-- A       |
+---------------------------+
Macaulay2 has a modulo command (it was initially introduced in the original
Macaulay, in the late 1980's), but it is not needed very often.  It is used
internally in Macaulay2 to implement kernels of module homomorphisms.

Singular Book 2.1.34 -- minimal presentations, prune
****************************************************

+----------------------------------------------------------------------------+
|i1 : R = QQ[x,y,z,MonomialOrder=>{Weights=>{-1,-1,-1},RevLex},Global=>false]|
|                                                                            |
|o1 = R                                                                      |
|                                                                            |
|o1 : PolynomialRing                                                         |
+----------------------------------------------------------------------------+
|i2 : M = cokernel matrix{{0,y},{x*y-1,x*z},{x*y+1,x*z}}                     |
|                                                                            |
|o2 = cokernel | 0     y  |                                                  |
|              | -1+xy xz |                                                  |
|              | 1+xy  xz |                                                  |
|                                                                            |
|                            3                                               |
|o2 : R-module, quotient of R                                                |
+----------------------------------------------------------------------------+
|i3 : null -- prune M -- doesn't work yet                                    |
+----------------------------------------------------------------------------+
|i4 : stderr << "--this example doesn't work yet" << endl;                   |
|--this example doesn't work yet                                             |
+----------------------------------------------------------------------------+

Singular Book 2.2.15 -- graded rings and modules
************************************************

Singular Book 2.3.10 -- normal form
***********************************

Singular Book 2.3.12 -- standard bases
**************************************

Singular Book 2.4.12 -- resolution and Betti numbers
****************************************************

Singular Book 2.4.15 -- homogeneous resolution and graded Betti numbers
***********************************************************************

Singular Book 2.5.5 -- syzygies
*******************************

Singular Book 2.5.18 -- Schreyer resolution
*******************************************

Singular Book 2.6.3 -- diagonal form
************************************

Singular Book 2.6.11 -- cyclic decomposition
********************************************

Singular Book 2.6.15 -- Jordan normal form
******************************************

Singular Book 2.7.5 -- tensor product of maps
*********************************************

Singular Book 2.7.9 -- tensor product of modules
************************************************

Singular Book 2.7.14 -- tensor product of rings
***********************************************

Singular Book 2.8.1 -- module membership
****************************************

Singular Book 2.8.3 -- elimination of module components
*******************************************************

Singular Book 2.8.5 -- intersection of modules
**********************************************

Singular Book 2.8.6 -- quotient of modules
******************************************

Singular Book 2.8.7 -- radical, zerodivisors of modules
*******************************************************

Singular Book 2.8.8 -- annihilator and Fitting ideal
****************************************************

Singular Book 2.8.9 -- kernel of a module homomorphism
******************************************************

Singular Book 2.8.10 -- solving linear equations
************************************************

replacements for commands and scripts from Macaulay
***************************************************

Macaulay2 aims to provide all of the functionality of Macaulay, but the names
of the functions are not the same, and there are other differences.  One major
difference is the introduction of the notion of module, whereas in Macaulay,
the pervasive concept was the matrix.

Here is a list of old Macaulay functions, together with pointers to functions
in Macaulay2 that might be used to replace them.

  * Macaulay commands:
      * ac -- such destructive changes are not allowed
      * add -- see +,
      * ar -- see not documented yet,
      * betti -- see betti,
      * calc -- see not documented yet,
      * cat -- see not documented yet,
      * ce -- see not documented yet,
      * characteristic -- see char,
      * chcalc -- see not documented yet,
      * codim -- see codim,
      * coef -- see not documented yet,
      * col_degree -- see not documented yet,
      * col_degs -- see not documented yet,
      * commands -- see not documented yet,
      * compress -- see compress,
      * concat -- see |,||,
      * continue -- see not documented yet,
      * contract -- see contract,
      * copy -- see not documented yet,
      * degree -- see degree,
      * determinants -- see minors,
      * diag -- The command diag m n is equivalent to the Macaulay2 expression
        n = map((ring m)^(numgens source m), source m,(i,j) -> if i === j then
        m_(0,i) else 0)
      * diag -- see not documented yet,
      * diff -- see diff,
      * dshift -- see not documented yet,
      * dsum -- see ++,
      * edit -- see not documented yet,
      * edit_map -- see not documented yet,
      * elim -- see selectInSubring,
      * ev -- see substitute,RingMap,
      * exit -- see quit,
      * fetch -- see substitute,
      * flatten -- see flatten,
      * forcestd -- see forceGB,
      * help -- see help,
      * help_file -- see not documented yet,
      * hilb -- see hilbertSeries,hilbertPolynomial,
        see hilbertFunction,
        poincare,
      * hilb_numer -- see hilbertSeries,
      * homog -- see homogenize,
      * hulb -- see not documented yet,
      * ideal -- see ideal, matrix,
      * iden -- see id,
      * if -- see if,
      * imap -- see map,
      * in -- see leadTerm,
      * inpart -- see not documented yet,
      * int -- see not documented yet,
      * intersect -- see intersect,
      * is_zero -- see ==,
      * jacob -- see jacobian,
      * jump -- see not documented yet,
      * k-basis -- see basis,
      * k_basis -- see basis,
      * keep -- see not documented yet,
      * kill -- see not documented yet,
      * koszul -- see koszul,
      * lift -- see //,
      * lift_std -- see gb,
      * listvars -- see listUserSymbols,
      * mat -- see matrix,
      * max -- see max,
      * mc -- see not documented yet,
      * min -- see min,
      * modulo -- see modulo,
      * monitor -- see using Macaulay2 with emacs,
      * monitoring -- see not documented yet,
      * monoms -- see not documented yet,
      * monprimes -- see not documented yet,
      * mr -- see not documented yet,
      * mult -- see *,
      * ncols -- use numgens source m
      * nres -- see resolution,
      * nrows -- use numgens target m
      * numinfo -- see not documented yet,
      * nvars -- use numgens R
      * outer -- see **,
      * path -- see path,
      * pc -- see not documented yet,
      * pfaff -- see pfaffians,
      * pmap -- see not documented yet,
      * poly -- see not documented yet,
      * power -- see ^,
      * pr -- see not documented yet,
      * pres <C:complex> -- Use C.dd or print C.dd
      * present_ring -- see not documented yet,
      * pring -- see not documented yet,
      * prmat -- see print, or toString,
      * putchange -- see not documented yet,
      * putmat -- see not documented yet,
      * putstd -- see not documented yet,
      * qring <I:ideal> <result A:ring> -- In Macaulay2, if I is an ideal, then
        A = (ring I)/I is equivalent, except that in Macaulay2, a Gröbner basis
        of I is computed for you, if it is needed
      * quit -- see quit,
      * quotient -- see not documented yet,
      * random -- see not documented yet,
      * reduce -- see not documented yet,
      * res -- see not documented yet,
      * reset -- see restart,
      * ring -- see not documented yet,
      * ring-from-rows -- see not documented yet,
      * ring_from_cols -- see not documented yet,
      * ring_from_rows -- see not documented yet,
      * ring_sum -- see not documented yet,
      * rmap -- see not documented yet,
      * row_degree -- see not documented yet,
      * row_degs -- see not documented yet,
      * sat -- see saturate (Saturation),
      * set -- see not documented yet,
      * set_value -- see not documented yet,
      * setcoldegs -- see not documented yet,
      * setdegs -- see not documented yet,
      * setring -- see use,
      * shout -- see not documented yet,
      * size -- see not documented yet,
      * smult -- see *,
      * space -- see not documented yet,
      * spairs -- see not documented yet,
      * spare -- see not documented yet,
      * sparse -- see not documented yet,
      * std -- see not documented yet,
      * std_minimal -- see not documented yet,
      * stdpart -- see not documented yet,
      * submat -- see submatrix,
      * subtract -- see -,
      * syz -- see syz,kernel,
      * tensor <matrix M> <matrix N> <result matrix M.N> -- cokernel M **
        cokernel N
      * trace -- see trace,
      * transpose -- see transpose,
      * truncate -- see truncate(ZZ,Module) (Truncations),
      * type -- see not documented yet,
      * version -- see version,
      * wedge -- see minors,exteriorPower,
  * Macaulay scripts from 'scriptsde':
      * <adj_of_cat -- see not documented yet,
      * <adjoin_fractions -- see not documented yet,
      * <adjoint -- see not documented yet,
      * <analytic_spread -- see not documented yet,
      * <annihilated -- see not documented yet,
      * <annihilator -- see annihilator (Saturation),
      * <annihilator1 -- see annihilator (Saturation),
      * <annihilator2 -- see annihilator (Saturation),
      * <binomial -- see binomial,
      * <ceiling -- see not documented yet,
      * <changelog -- see not documented yet,
      * <codim -- see not documented yet,
      * <cohomology -- see not documented yet,
      * <cohomology1 -- see not documented yet,
      * <column_vector -- see not documented yet,
      * <complement -- see not documented yet,
      * <copyring -- see not documented yet,
      * <cotan -- see not documented yet,
      * <cotan_bihom -- see not documented yet,
      * <curve_on_cubic -- see not documented yet,
      * <diagonal_submodule -- see not documented yet,
      * <diff -- see not documented yet,
      * <double_dual -- see not documented yet,
      * <double_dual1 -- see not documented yet,
      * <dual_variety -- see not documented yet,
      * <empty_array -- see not documented yet,
      * <equality -- see not documented yet,
      * <ext -- see not documented yet,
      * <ext(-,r) -- see not documented yet,
      * <extend_ring -- see not documented yet,
      * <from_bigraded -- see not documented yet,
      * <from_div_powers -- see not documented yet,
      * <generic_mat -- see genericMatrix,
      * <getvars -- see not documented yet,
      * <hom -- see not documented yet,
      * <hom_and_map -- see not documented yet,
      * <hom_is_0 -- see not documented yet,
      * <homology -- see not documented yet,
      * <i_in_j -- see not documented yet,
      * <ideal -- see not documented yet,
      * <idempotent -- see not documented yet,
      * <idencoldegs -- see not documented yet,
      * <idenrowdegs -- see not documented yet,
      * <interchange -- see not documented yet,
      * <interchange_permutation -- see not documented yet,
      * <inverse -- see not documented yet,
      * <is_zero -- see not documented yet,
      * <k3carpet -- see not documented yet,
      * <kernel -- see not documented yet,
      * <kernel_and_map -- see not documented yet,
      * <kosz_hom1 -- see not documented yet,
      * <kosz_hom2 -- see not documented yet,
      * <l_i_in_j -- see not documented yet,
      * <l_intersect -- see not documented yet,
      * <l_res -- see not documented yet,
      * <lex_seg_ideal -- see not documented yet,
      * <macaulayrep -- see not documented yet,
      * <map_from_col -- see not documented yet,
      * <minpres -- see not documented yet,
      * <module_iso -- see not documented yet,
      * <monomial_curve -- see not documented yet,
      * <mult_ideals -- see not documented yet,
      * <nbyn_commuting -- see not documented yet,
      * <normal_sheaf -- see not documented yet,
      * <nres -- see not documented yet,
      * <nzd -- see not documented yet,
      * <orbit_equations -- see not documented yet,
      * <permutation -- see not documented yet,
      * <perp -- see not documented yet,
      * <points -- see not documented yet,
      * <powers -- see not documented yet,
      * <project_from_product -- see not documented yet,
      * <projective_plane -- see not documented yet,
      * <prune -- see prune,
      * <prune_and_map -- see not documented yet,
      * <push_forward -- see pushForward,
      * <push_forward1 -- see coimage, (eventually)
      * <quotient1 -- see quotient,
      * <radical -- see radical (MinimalPrimes),
      * <random_element -- see not documented yet,
      * <random_int -- see not documented yet,
      * <random_map -- see not documented yet,
      * <random_mat -- see not documented yet,
      * <rank_prob -- see not documented yet,
      * <rat_nor_curve -- see not documented yet,
      * <rat_nor_osc_locus -- see not documented yet,
      * <rational_surface -- see not documented yet,
      * <rational_surface1 -- see not documented yet,
      * <reduce_syzygy_1 -- see not documented yet,
      * <regular_sequence -- see not documented yet,
      * <regular_sequence1 -- see not documented yet,
      * <regularity -- see regularity,
      * <remove_low_dim -- see not documented yet,
      * <remove_low_dim_id -- see not documented yet,
      * <remove_lowest_dim -- see not documented yet,
      * <representatives -- see not documented yet,
      * <representatives_old -- see not documented yet,
      * <res -- see resolution,
      * <res_and_dim -- see resolution,pdim,
      * <ring -- see not documented yet,
      * <sagbi -- see not documented yet,
      * <sagbi_step -- see not documented yet,
      * <sat -- see saturate (Saturation),
      * <sat1 -- see saturate (Saturation),
      * <scroll -- see not documented yet,
      * <select -- see not documented yet,
      * <shout_list -- see not documented yet,
      * <sort_by_degree -- see not documented yet,
      * <stack -- see matrix,map,
      * <submat_by_degs -- see not documented yet,
      * <subring -- see kernel,
      * <sym -- see not documented yet,
      * <sym_cokernel -- see not documented yet,
      * <template_for_scripts -- see not documented yet,
      * <to_div_powers -- see not documented yet,
      * <tor -- see Tor,
      * <unmixed_radical -- see radical (MinimalPrimes),
      * <unmixed_radical1 -- see radical (MinimalPrimes),
      * <unmixed_radical2 -- see radical (MinimalPrimes),
      * <wedge_cokernel -- see not documented yet,
      * <x_to_last -- see newCoordinateSystem,
      * <zeromat -- see not documented yet,
  * Macaulay scripts from 'scriptsmj':
      * <2BYN -- see not documented yet,
      * <add_matrix_to_array -- see not documented yet,
      * <check_complex -- see not documented yet,
      * <check_exact -- see not documented yet,
      * <comp_to_array -- see not documented yet,
      * <eagon_northcott -- see not documented yet,
      * <extract_matrix -- see not documented yet,
      * <homology_of_array -- see not documented yet,
      * <jordan0 -- see not documented yet,
      * <koszul_complex -- see not documented yet,
      * <lift -- see not documented yet,
      * <lift_arrays -- see not documented yet,
      * <mc -- see not documented yet,
      * <nilpotent0 -- see not documented yet,
      * <pres -- see not documented yet,
      * <smult_complex -- see not documented yet,
      * <splice_resns -- see not documented yet,
  * Macaulay scripts from 'scriptsms':
      * <block_map -- see not documented yet,
      * <blowup -- see not documented yet,
      * <blowup0 -- see not documented yet,
      * <generic_skew_mat -- see genericSkewMatrix,
      * <generic_sym_mat -- see genericSymmetricMatrix,
      * <hilb_fcn -- see not documented yet,
      * <inhomog_std -- see not documented yet,
      * <l_dual0 -- see not documented yet,
      * <l_from_dual -- see fromDual (InverseSystems),
      * <l_homog0 -- see not documented yet,
      * <l_min0 -- see not documented yet,
      * <l_minimal -- see not documented yet,
      * <l_minimal0 -- see not documented yet,
      * <l_tangentcone -- see not documented yet,
      * <l_to_dual -- see toDual (InverseSystems),
      * <line_bundle_image -- see not documented yet,
      * <normal_cone -- see not documented yet,
      * <proj_bundle -- see not documented yet,
      * <rmap -- see not documented yet,
      * <symmetric_algebra -- see not documented yet,

add <matrix> <matrix> <matrix>
------------------------------

Add matrices m and n, using result = m + n.  In general, arithmetic in
Macaulay2 is done using natural mathematical expressions.  See +.

betti <res>
-----------

Display the graded betti numbers of a chaincomplex or resolution C using betti
C.  See betti.

calc <computation> [hi degree]
------------------------------

chcalc <computation> [new hi deg]
---------------------------------

Compute the Gröbner basis of m up to a given degree, using gb(m,
DegreeLimit=>3).  Similarly, if a computation in Macaulay2 has been halted by
pressing <CTRL>-C, the computation can be restarted from where it left off, by
giving the original command, e.g., gb m.

cat <first var(0..numvars-1)> <result matrix>
---------------------------------------------

Macaulay1 then also prompts for two lists of integers, say rows and cols.  The
resulting catalecticant matrix can be obtained in Macaulay2 in the following
way.
+-------------------------------------------------------+
|i1 : R = QQ[a..h]                                      |
|                                                       |
|o1 = R                                                 |
|                                                       |
|o1 : PolynomialRing                                    |
+-------------------------------------------------------+
|i2 : rows = {0,1,2}                                    |
|                                                       |
|o2 = {0, 1, 2}                                         |
|                                                       |
|o2 : List                                              |
+-------------------------------------------------------+
|i3 : cols = {0,3}                                      |
|                                                       |
|o3 = {0, 3}                                            |
|                                                       |
|o3 : List                                              |
+-------------------------------------------------------+
|i4 : result = map(R^3, 2, (i,j) -> R_(rows_i + cols_j))|
|                                                       |
|o4 = | a d |                                           |
|     | b e |                                           |
|     | c f |                                           |
|                                                       |
|             3      2                                  |
|o4 : Matrix R  <-- R                                   |
+-------------------------------------------------------+

characteristic <ring> [result integer]
--------------------------------------

To obtain the characteristic of a ring R, use char R.  See char.

codim <standard basis> [integer result]
---------------------------------------

When computing the codimension of an ideal or module M, a Gröbner basis is
computed automatically, if needed.  Use codim M.One use of this command in
Macaulay1 was to compute the codimension of a partially computed Gröbner basis.

coef <matrix> <result monoms> <result coefs> [variable list]
------------------------------------------------------------

To obtain the matrices of monomials and their coefficients, use
coefficients.  The following example obtains the coefficients of
the variable a (which is variable number 0)
+-----------------------------------------------+
|i5 : R = ZZ/101[a..d];                         |
+-----------------------------------------------+
|i6 : m = matrix{{a^2+a^2*c+a*b+3*d}}           |
|                                               |
|o6 = | a2c+a2+ab+3d |                          |
|                                               |
|             1      1                          |
|o6 : Matrix R  <-- R                           |
+-----------------------------------------------+
|i7 : result = coefficients(m, Variables => {a})|
|                                               |
|o7 = (| a2 a 1 |, {2} | c+1 |)                 |
|                  {1} | b   |                  |
|                  {0} | 3d  |                  |
|                                               |
|o7 : Sequence                                  |
+-----------------------------------------------+
|i8 : result_0                                  |
|                                               |
|o8 = | a2 a 1 |                                |
|                                               |
|             1      3                          |
|o8 : Matrix R  <-- R                           |
+-----------------------------------------------+
|i9 : result_1                                  |
|                                               |
|o9 = {2} | c+1 |                               |
|     {1} | b   |                               |
|     {0} | 3d  |                               |
|                                               |
|             3      1                          |
|o9 : Matrix R  <-- R                           |
+-----------------------------------------------+

col_degree <matrix> <column> [result integer]
---------------------------------------------

To obtain the degree of the i-th column of a matrix m, use (degrees source
m)_i.  See degrees.  Note that in Macaulay2, one can use
multi-degrees, so the result is a list of integers.  Also all indices in
Macaulay2 start at 0.
+------------------------------------------+
|i10 : R = QQ[a,b,Degrees=>{{1,0},{1,-1}}];|
+------------------------------------------+
|i11 : m = matrix{{a*b, b^2}}              |
|                                          |
|o11 = | ab b2 |                           |
|                                          |
|              1      2                    |
|o11 : Matrix R  <-- R                     |
+------------------------------------------+
|i12 : (degrees source m)_0                |
|                                          |
|o12 = {2, -1}                             |
|                                          |
|o12 : List                                |
+------------------------------------------+

col_degs <matrix> [column degrees]
----------------------------------

Compute the list of degrees of the columns of a matrix m using degrees source
m.  The result is a list of degrees. Each degree is itself a list of integers,
since multi-degrees are allowed.

commands
--------

Using Macaulay2 in emacs, type the first few letters of a command, then hit
<TAB>. The list of all commands starting with those letters will be displayed,
or if there is only one, emacs will complete the typing for you.

compress <matrix> <result matrix>
---------------------------------

Remove columns of a matrix m which are entirely zero using compress m. See
compress.

concat <matrix> <matrix2> ... <matrix n>
----------------------------------------

Concatenate matrices m1, m2, ..., mn using m1 | m2 | ... | mn.  See |.
The main difference is that in Macaulay2 this command does not overwrite
the first matrix.

continue
--------

In Macaulay2, one interrupts a computation using <CTRL>-C, as in Macaulay1.
Restart the computation using the original command.  For Gröbner basis and
resolution commands, the computation starts off where it left off.

contract <ideal> <ideal> <result matrix>
----------------------------------------

To contract the matrix n by the matrix m use contract(m,n).  See
contract.  In Macaulay2, the arguments are not constrained to be
matrices with one row.

copy <existing matrix> <copy of matrix>
---------------------------------------

Since matrices in Macaulay2 are immutable objects, this command is no longer
necessary.  One can still make a copy of a matrix.  For example
+------------------------------------------------+
|i13 : R = ZZ/101[a..d]                          |
|                                                |
|o13 = R                                         |
|                                                |
|o13 : PolynomialRing                            |
+------------------------------------------------+
|i14 : m = matrix{{a,b},{c,d}}                   |
|                                                |
|o14 = | a b |                                   |
|      | c d |                                   |
|                                                |
|              2      2                          |
|o14 : Matrix R  <-- R                           |
+------------------------------------------------+
|i15 : copym = map(target m, source m, entries m)|
|                                                |
|o15 = | a b |                                   |
|      | c d |                                   |
|                                                |
|              2      2                          |
|o15 : Matrix R  <-- R                           |
+------------------------------------------------+

degree <standard basis> [integer codim] [integer degree]
--------------------------------------------------------

When computing the degree of an ideal or module M, a Gröbner basis is computed
automatically, if needed.  Use degree M.  Note that in Macaulay2, degree
returns only the degree.  Use codim M to obtain the codimension.One use of this
command in Macaulay1 was to compute the degree of a partially computed Gröbner
basis.

determinants <matrix> <p> <result>
----------------------------------

Use minors(p,m) to compute the ideal of p by p minors of the matrix m.  See
minors.

diag <matrix> <result>
----------------------

To make a diagonal matrix whose diagonal entries are taken from a matrix m, it
is necessary to build the matrix directly, as in the following example.
+---------------------------------------------------------------+
|i16 : R = ZZ[a..d];                                            |
+---------------------------------------------------------------+
|i17 : m = matrix{{a^2,b^3,c^4,d^5}}                            |
|                                                               |
|o17 = | a2 b3 c4 d5 |                                          |
|                                                               |
|              1      4                                         |
|o17 : Matrix R  <-- R                                          |
+---------------------------------------------------------------+
|i18 : map(R^(numgens source m), source m,                      |
|                       (i,j) -> if i === j then m_(0,i) else 0)|
|                                                               |
|o18 = | a2 0  0  0  |                                          |
|      | 0  b3 0  0  |                                          |
|      | 0  0  c4 0  |                                          |
|      | 0  0  0  d5 |                                          |
|                                                               |
|              4      4                                         |
|o18 : Matrix R  <-- R                                          |
+---------------------------------------------------------------+

diff <ideal> <ideal> <result matrix>
------------------------------------

To differentiate the matrix n by the matrix m use diff(m,n).  See diff.
In Macaulay2, the arguments are not constrained to be matrices with one
row.

dshift <matrix> <degree to shift by>
------------------------------------

To shift the degrees of a matrix m by an integer d, use m ** (ring m)^{-d}.
See **.  Note that this returns a matrix with the degrees
shifted, and does not modify the original matrix m.  For example
+-----------------------------------+
|i19 : R = ZZ[a..d];                |
+-----------------------------------+
|i20 : m = matrix{{a,b^2},{c^2,d^3}}|
|                                   |
|o20 = | a  b2 |                    |
|      | c2 d3 |                    |
|                                   |
|              2      2             |
|o20 : Matrix R  <-- R              |
+-----------------------------------+
|i21 : betti m                      |
|                                   |
|             0 1                   |
|o21 = total: 2 2                   |
|          0: 2 .                   |
|          1: . 1                   |
|          2: . 1                   |
|                                   |
|o21 : BettiTally                   |
+-----------------------------------+
|i22 : n = m ** R^{-1}              |
|                                   |
|o22 = {1} | a  b2 |                |
|      {1} | c2 d3 |                |
|                                   |
|              2      2             |
|o22 : Matrix R  <-- R              |
+-----------------------------------+
|i23 : betti n                      |
|                                   |
|             0 1                   |
|o23 = total: 2 2                   |
|          1: 2 .                   |
|          2: . 1                   |
|          3: . 1                   |
|                                   |
|o23 : BettiTally                   |
+-----------------------------------+

dsum <matrix> ... <matrix> <result>
-----------------------------------

To form the direct sum of matrices m1, m2, ..., mn, use m1 ++ m2 ++ ... ++ mn.
See ++.

elim <standard basis> <result matrix> [n]
-----------------------------------------

To select the columns of the matrix m which lie in the subring defined by the
first n slots of the monomial order being zero, use selectInSubring(n,m).
Usually, one uses the value of 1 for n.

ev <ideal> <matrix> <changed matrix>
------------------------------------

In Macaulay2, one uses ring maps, or substitute, to
substitute variables.  If m is a matrix in a ring R having n variables, and f
is a 1 by n matrix over some ring, then use substitute(m,f) to perform the
substitution.  For example,
+---------------------------------------+
|i24 : R = QQ[a..d]                     |
|                                       |
|o24 = R                                |
|                                       |
|o24 : PolynomialRing                   |
+---------------------------------------+
|i25 : S = QQ[s,t]                      |
|                                       |
|o25 = S                                |
|                                       |
|o25 : PolynomialRing                   |
+---------------------------------------+
|i26 : m = matrix{{a^2-d, b*c}}         |
|                                       |
|o26 = | a2-d bc |                      |
|                                       |
|              1      2                 |
|o26 : Matrix R  <-- R                  |
+---------------------------------------+
|i27 : f = matrix{{s^4,s^3*t,s*t^3,t^4}}|
|                                       |
|o27 = | s4 s3t st3 t4 |                |
|                                       |
|              1      4                 |
|o27 : Matrix S  <-- S                  |
+---------------------------------------+
|i28 : substitute(m,f)                  |
|                                       |
|o28 = | s8-t4 s4t4 |                   |
|                                       |
|              1      2                 |
|o28 : Matrix S  <-- S                  |
+---------------------------------------+
In Macaulay2, one may also create and apply ring maps
+-----------------------------------------+
|i29 : F = map(R,R,{b,c,d,a})             |
|                                         |
|o29 = map (R, R, {b, c, d, a})           |
|                                         |
|o29 : RingMap R <-- R                    |
+-----------------------------------------+
|i30 : m + F m + F F m + F F F m          |
|                                         |
|o30 = | a2+b2+c2+d2-a-b-c-d ab+bc+ad+cd ||
|                                         |
|              1      2                   |
|o30 : Matrix R  <-- R                    |
+-----------------------------------------+
Or one may substitute for only some variables
+---------------------------------+
|i31 : substitute(m, {a=>1, b=>3})|
|                                 |
|o31 = | -d+1 3c |                |
|                                 |
|              1      2           |
|o31 : Matrix R  <-- R            |
+---------------------------------+

exit
----

Use exit, to quit Macaulay2.

fetch <matrix> <result matrix> [ones, default=zeros]
----------------------------------------------------

In order to bring a matrix m to a ring S which has ring variables of the same
name, use substitute(m,S).
+---------------------+
|i32 : R = ZZ[s,t]    |
|                     |
|o32 = R              |
|                     |
|o32 : PolynomialRing |
+---------------------+
|i33 : m = s^2+t^2    |
|                     |
|       2    2        |
|o33 = s  + t         |
|                     |
|o33 : R              |
+---------------------+
|i34 : S = R[a..d]    |
|                     |
|o34 = S              |
|                     |
|o34 : PolynomialRing |
+---------------------+
|i35 : substitute(m,S)|
|                     |
|       2    2        |
|o35 = s  + t         |
|                     |
|o35 : S              |
+---------------------+

flatten <matrix> <result ideal of entries>
------------------------------------------

In order to form a one row matrix with the entries of a matrix m, use flatten
m.  See flatten.

forcestd <matrix> <result standard basis> [change of basis]
-----------------------------------------------------------

In order to inform the system that the columns of the matrix m form a Gröbner
basis, use forceGB m.  See forceGB.

homog <matrix> <homog variable> <new matrix>
--------------------------------------------

To homogenize a matrix m with respect to a variable x, use homogenize(m,x). One
may also homogenize with respect to a given weight vector.  See
homogenize.

ideal <resulting matrix>
------------------------

To enter a one row matrix, use we may use the following method.
+-------------------------------------+
|i36 : R = ZZ[a..d]                   |
|                                     |
|o36 = R                              |
|                                     |
|o36 : PolynomialRing                 |
+-------------------------------------+
|i37 : f = matrix{{a^2-b*c,3*b*c^4-1}}|
|                                     |
|o37 = | a2-bc 3bc4-1 |               |
|                                     |
|              1      2               |
|o37 : Matrix R  <-- R                |
+-------------------------------------+
Remember that ideals, modules, and matrices are all different in Macaulay2.
One can easily change between them, as in:
+---------------------------------+
|i38 : J = ideal f                |
|                                 |
|              2            4     |
|o38 = ideal (a  - b*c, 3b*c  - 1)|
|                                 |
|o38 : Ideal of R                 |
+---------------------------------+
|i39 : generators J               |
|                                 |
|o39 = | a2-bc 3bc4-1 |           |
|                                 |
|              1      2           |
|o39 : Matrix R  <-- R            |
+---------------------------------+
|i40 : image f                    |
|                                 |
|o40 = image | a2-bc 3bc4-1 |     |
|                                 |
|                              1  |
|o40 : R-module, submodule of R   |
+---------------------------------+
|i41 : cokernel f                 |
|                                 |
|o41 = cokernel | a2-bc 3bc4-1 |  |
|                                 |
|                             1   |
|o41 : R-module, quotient of R    |
+---------------------------------+

iden <size> <result>
--------------------

To make the identity map on a module F, use id_F, as in
+----------------------+
|i42 : id_(R^4)        |
|                      |
|o42 = | 1 0 0 0 |     |
|      | 0 1 0 0 |     |
|      | 0 0 1 0 |     |
|      | 0 0 0 1 |     |
|                      |
|              4      4|
|o42 : Matrix R  <-- R |
+----------------------+
See id.

if <integer> <label1> [<label2>]
--------------------------------

For conditional execution, use the if-then or if-then-else statement

int <name> <new value>
----------------------

To assign a value to a variable in Macaulay2, use =.  For example,
+----------------------------------+
|i43 : myanswer = 2*(numgens R) - 1|
|                                  |
|o43 = 7                           |
+----------------------------------+
Warning: In Macaulay1, names of variables in rings, and user defined variables
are completely separate.  In Macaulay2, if you assign something to a ring
variable, it will assume its new value.
+------------------------+
|i44 : R = ZZ/31991[a..d]|
|                        |
|o44 = R                 |
|                        |
|o44 : PolynomialRing    |
+------------------------+
|i45 : a                 |
|                        |
|o45 = a                 |
|                        |
|o45 : R                 |
+------------------------+
|i46 : a = 43            |
|                        |
|o46 = 43                |
+------------------------+
|i47 : a                 |
|                        |
|o47 = 43                |
+------------------------+
|i48 : use R             |
|                        |
|o48 = R                 |
|                        |
|o48 : PolynomialRing    |
+------------------------+
|i49 : a                 |
|                        |
|o49 = a                 |
|                        |
|o49 : R                 |
+------------------------+

intersect <mat 1> ... <mat n> <result computation>
--------------------------------------------------

To intersect ideals, or submodules I1, I2, ..., In, use
intersect(I1,I2,...,In).  The main difference is that these values cannot be
matrices, they must be ideals or submodules.  A second difference is that the
computation, if interrupted, must be restarted at the beginning.  See
intersect.  For example,
+-----------------------------------------------------------------------------+
|i50 : I = ideal(a^2-b,c-1,d^2-a*b)                                           |
|                                                                             |
|              2                      2                                       |
|o50 = ideal (a  - b, c - 1, - a*b + d )                                      |
|                                                                             |
|o50 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i51 : J = ideal(a*b-1, c*d-2)                                                |
|                                                                             |
|o51 = ideal (a*b - 1, c*d - 2)                                               |
|                                                                             |
|o51 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i52 : intersect(I,J)                                                         |
|                                                                             |
|              2                                          3                   |
|o52 = ideal (c d - c*d - 2c + 2, a*b*c - a*b - c + 1, c*d  - a*b*d + 2a*b -  |
|      -----------------------------------------------------------------------|
|              2       2                2        2       2        2           |
|      c*d - 2d  + d, a c*d - b*c*d - 2a  + 2b, a b*d - b c*d - 2a b + a*c*d +|
|      -----------------------------------------------------------------------|
|        2         2 2        2          2   3       2    2                   |
|      2b  - a*d, a b  - a*b*d  - a*b + d , a b - a*b  - a  + b)              |
|                                                                             |
|o52 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+

is_zero <poly> <result integer: 1 if zero, else 0>
--------------------------------------------------

To decide whether a polynomial, matrix, ideal, etc., f is zero, use f == 0.
The resulting value is a Boolean: either true, or false.  See ==.

jacob <ideal> <resulting jacobian> [variable list]
--------------------------------------------------

To find the Jacobian matrix of an ideal or one row matrixf, use jacobian f.  If
you only wish to differentiate with some of the variables, use diff,
instead.  See jacobian.

jump <label>
------------

Macaulay2 has no go to statements.  Instead, you should use the control
structures.

how Macaulay2 finds its files
*****************************

When you run Macaulay2, it has to find and load a sequence of startup files
containing code written in the Macaulay2 language. Here is the way it does
that.

Its first task is to discover the path to the binary file M2 that is currently
running.  On some systems, that information is available from the /proc file
system.  Otherwise, it examines the command name you used to run the program,
which is provided to it as the argument in position number 0 on the command
line.  If it's not an absolute path, it searches along the path of directories
mentioned in the environment variable PATH until it finds a file with the same
name.  If the result is a symbolic link, the link is followed.  The final
result is assumed to be in a directory named "bin/", and the startup files are
located relative to that.  The path to the top level directory is stored in the
variable prefixDirectory, which you can examine to see
whether it all worked out. For detailed information about the relative location
of Macaulay2 files, see Layout.

currentLayout -- relative locations of Macaulay2 files
******************************************************

Description
===========

Macaulay2 comes with a variety of types of files, and some of them are
associated with a particular Macaulay2 package.  The hash table currentLayout
is a translation table from names, corresponding to the various types of files,
to directory paths.  The directory paths are to be interpreted relative to the
path stored in prefixDirectory.  Each of the
directories contained in the list prefixPath, has its own
layout, which will be detected at runtime. Some of the strings contain PKG as a
substring, which should be replaced by the name of package whose files will be
stored in that directory.

The hash table Layout, contains the two possible values
for currentLayout,; corresponding to the two possible
values for the installPackage(...,SeparateExec=>...),
option used with installPackage. The hash table Layout#2
is used if architecture dependent files are to be stored in a directory tree
separate from the one used for architecture independent files.  The hash table
Layout#1 is used otherwise.

Basic Macaulay2 files are regarded as being associated with a special package
called Core, and the corresponding documentation files are part of the package
Macaulay2Doc.

+-----------------------------------------------------------------------------+
|i1 : Layout                                                                  |
|                                                                             |
|o1 = HashTable{1 => HashTable{"                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|               2 => HashTable{"                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                              "                                              |
|                                                                             |
|o1 : HashTable                                                               |
|-----------------------------------------------------------------------------|
|bin" => bin/                                                    }            |
|common" =>                                                                   |
|data" => share/                                                              |
|doc" => share/doc/Macaulay2/                                                 |
|docdir" => share/doc/Macaulay2/                                              |
|emacs" => share/emacs/site-lisp/macaulay2/                                   |
|exec" =>                                                                     |
|factory gftables" => /usr/share/singular/factory/                            |
|info" => share/info/                                                         |
|lib" => lib/                                                                 |
|libraries" => lib/Macaulay2/lib/                                             |
|man" => share/man/                                                           |
|package" => share/Macaulay2/PKG/                                             |
|packagecache" => lib/Macaulay2/PKG/cache/                                    |
|packagedoc" => share/doc/Macaulay2/PKG/                                      |
|packageexampleoutput" => share/doc/Macaulay2/PKG/example-output/             |
|packagehtml" => share/doc/Macaulay2/PKG/html/                                |
|packageimages" => share/doc/Macaulay2/PKG/images/                            |
|packagelib" => lib/Macaulay2/PKG/                                            |
|packages" => share/Macaulay2/                                                |
|packagetests" => share/doc/Macaulay2/PKG/tests/                              |
|program licenses" => libexec/Macaulay2/program-licenses/                     |
|programs" => libexec/Macaulay2/bin/                                          |
|bin" => x86_64-Linux-Ubuntu-24.04/bin/                                       |
|common" => common/                                                           |
|data" => common/share/                                                       |
|doc" => common/share/doc/Macaulay2/                                          |
|docdir" => common/share/doc/Macaulay2/                                       |
|emacs" => common/share/emacs/site-lisp/macaulay2/                            |
|exec" => x86_64-Linux-Ubuntu-24.04/                                          |
|factory gftables" => /usr/share/singular/factory/                            |
|info" => common/share/info/                                                  |
|lib" => x86_64-Linux-Ubuntu-24.04/lib/                                       |
|libraries" => x86_64-Linux-Ubuntu-24.04/lib/Macaulay2/lib/                   |
|man" => common/share/man/                                                    |
|package" => common/share/Macaulay2/PKG/                                      |
|packagecache" => x86_64-Linux-Ubuntu-24.04/lib/Macaulay2/PKG/cache/          |
|packagedoc" => common/share/doc/Macaulay2/PKG/                               |
|packageexampleoutput" => common/share/doc/Macaulay2/PKG/example-output/      |
|packagehtml" => common/share/doc/Macaulay2/PKG/html/                         |
|packageimages" => common/share/doc/Macaulay2/PKG/images/                     |
|packagelib" => x86_64-Linux-Ubuntu-24.04/lib/Macaulay2/PKG/                  |
|packages" => common/share/Macaulay2/                                         |
|packagetests" => common/share/doc/Macaulay2/PKG/tests/                       |
|program licenses" => x86_64-Linux-Ubuntu-24.04/libexec/Macaulay2/program-    |
|programs" => x86_64-Linux-Ubuntu-24.04/libexec/Macaulay2/bin/                |
|-----------------------------------------------------------------------------|
|          }                                                                  |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|         }                                                                   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|licenses/                                                                    |
+-----------------------------------------------------------------------------+
Here are the meanings of the keys used in currentLayout.
  * "bin" : executable files (M2)
  * "common" : architecture independent files
  * "data" : architecture independent data files
  * "doc" : documentation
  * "docdir" : documentation for Macaulay2 packages
  * "emacs" : emacs source files (*.el, *.elc)
  * "exec" : architecture dependent files
  * "factory gftables" : directory for files containing addition tables in
    small finite fields used by the library 'factory'
  * "info" : documentation in info form
  * "lib" : architecture dependent data and executable files
  * "libraries" : dynamically loadable libraries from third party packages
    linked with Macaulay2
  * "man" : man pages
  * "package" : additional source files for the Macaulay2 package PKG
  * "packagecache" : cached data files for the Macaulay2 package PKG
  * "packagedoc" : documentation for the Macaulay2 package PKG
  * "packageexampleoutput" : example output files for the Macaulay2 package PKG
  * "packagehtml" : html documentation for the Macaulay2 package PKG (*.html)
  * "packageimages" : images for the Macaulay2 package PKG (*.jpg)
  * "packagelib" : architecture dependent files for the Macaulay2 package PKG
  * "packages" : source files for Macaulay2 packages; this directory appears on
    the path
  * "packagetests" : test files for the Macaulay2 package PKG
  * "program licenses" : licenses for programs to be run by Macaulay2
  * "programs" : programs to be run by Macaulay2

See also
========

  * installPackage(...,SeparateExec=>...) -- load and
    install a package and its documentation

For the programmer
==================

The object currentLayout, is a hash table.

prefixDirectory -- the prefix directory
***************************************

Description
===========

When Macaulay2 is successfully installed, its files are installed in a
directory tree whose layout, relative to the root, is determined by the hash
table Layout.  When M2 starts up, it detects whether it
is running in such a layout, and sets prefixDirectory,
to the root of that directory tree.  The way it does that is that it locates
the running M2 executable and determines whether it is located in a directory
whose name is bin that has a sibling directory called share that leads to a
directory called share/Macaulay2/Core/.

The prefix directory can be set by the user at an early stage when M2 starts up
with the --prefix command line option.  This will affect the value of
path, and thus the locations of the files loaded initially.  Use the
--notify command line option to display the locations of files as they are
loaded.

See also
========

  * prefixPath -- absolute locations of Macaulay2 files
  * Invoking the program

For the programmer
==================

The object prefixDirectory, is a string.

Type -- the class of all types
******************************

Description
===========

Everything in the system is classified, and the class that a thing belongs to
is a type.  A type is implemented as a hash table containing method functions
for its instances.

The list of types known to the system is displayed below.

Types of type:
==============

  * HeaderType -- a class of lists with abbreviated
    constructors
  * Monoid -- the class of all monoids
  * Ring -- the class of all rings
  * RingFamily
  * SelfInitializingType -- the class of all self
    initializing types
  * WrapperType -- a class of lists with abbreviated
    constructors

Functions and methods returning a type:
=======================================

  * "class(Thing)" -- see class, -- class of an object
  * "parent(Thing)" -- see parent, -- parent type of an object

Methods that use a type:
========================

  * "? Type" -- see ? Symbol, -- view brief documentation of a
    symbol
  * "about(Type)" -- see about, -- search the documentation
  * ancestor(Type,Type) -- whether one type
    is an ancestor of another
  * "instance(Thing,Type)" -- see instance, -- whether
    something has a certain type
  * instances(Type)
  * "isQuotientOf(Type,QuotientRing)" -- see isQuotientOf(Type,Ring),
    -- whether one ring is a quotient of a ring
    of a given type
  * isQuotientOf(Type,Ring) -- whether
    one ring is a quotient of a ring of a given type
  * "methods(Type)" -- see methods, -- list methods
  * "ofClass(Type)" -- see ofClass, -- English phrases for types
  * random(Type) -- get a random object of a type
  * select(BasicList,Type) -- select
    elements of a given type in a list

Protected objects of class Type:
================================

  * AffineVariety (Varieties) -- the class of all affine
    varieties
  * AngleBarList -- the class of lists delimited by <| ...
    |>
  * Array -- the class of all arrays -- [...]
  * AssociativeExpression -- the class of
    associative expressions
  * AtomicInt -- the class of atomic integers
  * BasicList -- the class of all basic lists
  * BettiTally -- the class of all Betti tallies
  * Boolean -- the class of Boolean values
  * CacheFunction -- the class of cache functions
  * CacheTable -- hash tables for caching
  * CC_* (missing documentation)
  * ChainComplex -- the class of all chain complexes
  * ChainComplexMap -- the class of all maps between
    chain complexes
  * CoherentSheaf (Varieties) -- the class of all coherent
    sheaves
  * CompiledFunction -- the class of all compiled
    functions
  * CompiledFunctionBody -- the class of all
    compiled function bodies
  * CompiledFunctionClosure -- the class of all
    compiled function closures
  * ComplexField -- the class of all complex fields
  * Cone (Polyhedra) -- the class of all rational convex polyhedral
    cones
  * Constant
  * Database -- the class of all database files
  * Descent
  * Dictionary -- the class of all dictionaries
  * DocumentTag -- the class of all document tags
  * EngineRing -- the class of rings handled by the engine
  * Expression -- the class of all expressions
  * Fan (Polyhedra) -- the class of all fans
  * File -- the class of all files
  * FilePosition -- the class of all file positions
  * FractionField -- the class of all fraction fields
  * Function -- the class of all functions
  * FunctionBody -- the class of function bodies
  * FunctionClosure -- the class of all function
    closures
  * GaloisField -- the class of all Galois fields
  * GeneralOrderedMonoid -- the class of all
    ordered free commutative monoids
  * GlobalDictionary -- the class of all global
    dictionaries
  * GradedModule -- the class of all graded modules
  * GradedModuleMap -- the class of all maps between
    graded modules
  * GroebnerBasis -- the class of all Gröbner bases
  * GroebnerBasisOptions
  * HashTable -- the class of all hash tables
  * HeaderType -- a class of lists with abbreviated
    constructors
  * Ideal -- the class of all ideals
  * ImmutableType -- the class of immutable types
  * IndeterminateNumber -- the class of all
    indeterminate numbers
  * IndexedVariable -- the class of all indexed
    variables
  * IndexedVariableTable
  * InexactField -- the class of inexact fields
  * InexactFieldFamily -- the class of all families
    of inexact fields
  * InexactNumber
  * InexactNumber'
  * InfiniteNumber -- the class of all infinite numbers
  * Keyword -- the class of all keywords
  * List -- the class of all lists -- {...}
  * LocalDictionary -- the class of all local
    dictionaries
  * Manipulator -- the class of all file manipulators
  * Matrix -- the class of all matrices
  * MethodFunction -- a type of method function
  * MethodFunctionBinary -- a type of method
    function
  * MethodFunctionSingle -- a type of method
    function
  * MethodFunctionWithOptions -- a type of
    method function
  * Module -- the class of all modules
  * Monoid -- the class of all monoids
  * MonoidElement -- the class of all monoid elements
  * MonomialIdeal -- the class of all monomial ideals
    handled by the engine
  * MultigradedBettiTally -- the class of all
    multigraded Betti tallies
  * MutableHashTable -- the class of all mutable hash
    tables
  * MutableList -- the class of all mutable lists
  * MutableMatrix -- the class of all mutable matrices
  * Net -- the class of all nets and strings
  * NetFile -- the class of all net files
  * Nothing -- the empty class
  * Number -- the class of all numbers
  * OneExpression -- the class all one expressions
  * Option -- the class of all key-value pairs K => V
  * OptionTable -- the class of hash tables for optional
    arguments
  * OrderedMonoid -- the class of all ordered monoids
  * Package -- the class of all packages
  * Partition -- a type of list representing a partition of a
    natural number
  * PolyhedralComplex (Polyhedra) -- the class of all
    polyhedral complexes
  * PolyhedralObject (Polyhedra) -- the class of all
    polyhedral objects in Polyhedra
  * Polyhedron (Polyhedra) -- the class of all convex
    polyhedra
  * PolynomialRing -- the class of all ordered monoid
    rings
  * Program -- external program object
  * ProgramRun -- result of running an external program
  * ProjectiveHilbertPolynomial -- the
    class of all Hilbert polynomials
  * ProjectiveVariety (Varieties) -- the class of all
    projective varieties
  * Pseudocode -- the class of pseudocodes
  * "PseudocodeClosure" -- see Pseudocode, -- the class of
    pseudocodes
  * QuotientRing -- the class of all quotient rings
  * RealField -- the class of all real fields
  * Resolution -- the class of all resolution computations
  * Ring -- the class of all rings
  * RingElement -- the class of all ring elements handled
    by the engine
  * RingFamily
  * RingMap -- the class of all ring maps
  * RR_* (missing documentation)
  * RRi_* (missing documentation)
  * ScriptedFunctor -- the class of all scripted
    functors
  * SelfInitializingType -- the class of all self
    initializing types
  * Sequence -- the class of all sequences -- (...)
  * Set -- the class of all sets
  * SheafMap (missing documentation)
  * SheafOfRings (Varieties) -- the class of sheaves of
    rings
  * String -- the class of all strings
  * SumOfTwists (Varieties) -- the class of all sums of
    twists
  * Symbol -- the class of all symbols
  * "SymbolBody" -- see symbolBody, -- symbol bodies
  * Tally -- the class of all tally results
  * Task -- the class of all tasks
  * Thing -- the class of all things
  * Time -- the class of all timing results
  * Variety (Varieties) -- the class of all algebraic varieties
  * Vector -- the class of all elements of modules that are
    handled by the engine
  * VirtualTally
  * VisibleList -- the class of all visible lists
  * WrapperType -- a class of lists with abbreviated
    constructors
  * ZeroExpression -- the class of all zero expressions

For the programmer
==================

The object Type, is a type, with ancestor classes
MutableHashTable < HashTable <
Thing.

Function -- the class of all functions
**************************************

See also
========

  * using functions
  * using functions with optional inputs
  * making functions
  * local variables in a function
  * making functions with a variable number of arguments
  * making functions with multiple return values
  * making new functions with optional arguments

Types of function:
==================

  * CompiledFunction -- the class of all compiled
    functions
  * CompiledFunctionClosure -- the class of all
    compiled function closures
  * FunctionClosure -- the class of all function
    closures

Functions and methods returning a function:
===========================================

  * Function @@ Function -- composition of
    functions
  * Function _ Thing -- attach the first argument to
    a function of two or more arguments
  * "Boolean >> Function" -- see OptionTable >> Function,
    -- attaching options to a function
  * "List >> Function" -- see OptionTable >> Function,
    -- attaching options to a function
  * OptionTable >> Function -- attaching
    options to a function
  * "profile(Function)" -- see profile, -- profile a function

Methods that use a function:
============================

  * "? Function" -- see ? Symbol, -- view brief documentation
    of a symbol
  * "about(Function)" -- see about, -- search the documentation
  * "accumulate(Function,Thing)" -- see accumulate, -- apply
    a binary operator repeatedly
  * "accumulate(Function,Thing,Thing)" -- see accumulate, --
    apply a binary operator repeatedly
  * "accumulate(Function,Thing,VisibleList)" -- see accumulate,
    -- apply a binary operator repeatedly
  * "accumulate(Function,VisibleList)" -- see accumulate, --
    apply a binary operator repeatedly
  * "accumulate(VisibleList,Function)" -- see accumulate, --
    apply a binary operator repeatedly
  * "accumulate(VisibleList,Thing,Function)" -- see accumulate,
    -- apply a binary operator repeatedly
  * "addHook(MutableHashTable,Thing,Function)" -- see addHook,
    -- add a hook function to an object for later processing
  * "addHook(Sequence,Function)" -- see addHook, -- add a hook
    function to an object for later processing
  * "addHook(Symbol,Function)" -- see addHook, -- add a hook
    function to an object for later processing
  * all(BasicList,BasicList,Function)
    -- whether all corresponding
    elements of a pair of lists satisfy a condition
  * all(BasicList,Function) -- whether
    all elements of a list satisfy a specified condition
  * "all(ZZ,Function)" -- see all(BasicList,Function),
    -- whether all elements of a list satisfy a
    specified condition
  * all(HashTable,Function) -- whether
    all key/value pairs in a hash table satisfy a specified condition
  * any(BasicList,BasicList,Function)
    -- whether any corresponding
    elements of a pair of lists satisfy a condition
  * any(BasicList,Function) -- whether
    any elements of a list satisfy a specified condition
  * "any(ZZ,Function)" -- see any(BasicList,Function),
    -- whether any elements of a list satisfy a
    specified condition
  * any(HashTable,Function) -- whether
    all key/value pairs in a hash table satisfy a specified condition
  * apply(BasicList,BasicList,Function)
    -- apply a function to pairs
    of elements, one from each list
  * "apply(BasicList,String,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * "apply(String,BasicList,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * "apply(String,String,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * apply(BasicList,Function) -- apply
    a function to each element of a list
  * "apply(String,Function)" -- see apply(BasicList,Function),
    -- apply a function to each element of a
    list
  * apply(Thing,Function) -- apply a
    function to an object with an iterator
  * apply(ZZ,Function) -- apply a function to
    {0,..., n-1}
  * "applyKeys(HashTable,Function)" -- see applyKeys, -- apply
    a function to each key in a hash table
  * "applyKeys(HashTable,Function,Function)" -- see applyKeys,
    -- apply a function to each key in a hash table
  * "applyPairs(HashTable,Function)" -- see applyPairs, --
    apply a function to each pair in a hash table
  * "applyValues(HashTable,Function)" -- see applyValues, --
    apply a function to each value in a hash table
  * "code(Function)" -- see code, -- display source code
  * "createTask(Function)" -- see createTask, -- create a
    task
  * "createTask(Function,Thing)" -- see createTask, -- create
    a task
  * "fold(Function,Thing)" -- see fold, -- apply a binary operator
    repeatedly
  * "fold(Function,Thing,Thing)" -- see fold, -- apply a binary
    operator repeatedly
  * "fold(Function,VisibleList)" -- see fold, -- apply a binary
    operator repeatedly
  * "fold(VisibleList,Function)" -- see fold, -- apply a binary
    operator repeatedly
  * "fold(VisibleList,Thing,Function)" -- see fold, -- apply a
    binary operator repeatedly
  * Function \ Set (missing documentation)
  * Function Thing -- function application
  * hashTable(Function,List) (missing documentation)
  * /// Function \ Ideal /// -- see Ideal / Function,
    -- apply a function to generators of an ideal
  * Ideal / Function -- apply a function to generators
    of an ideal
  * "installAssignmentMethod(Symbol,HashTable,Function)" -- see
    installAssignmentMethod, -- install methods
    assignment to the value of an operator
  * "installAssignmentMethod(Symbol,HashTable,HashTable,Function)" -- see
    installAssignmentMethod, -- install methods
    assignment to the value of an operator
  * "integrate(Function,InfiniteNumber,InfiniteNumber)" -- see integrate,
    -- numerical integration
  * "integrate(Function,InfiniteNumber,Number)" -- see integrate,
    -- numerical integration
  * "integrate(Function,Number,InfiniteNumber)" -- see integrate,
    -- numerical integration
  * "integrate(Function,Number,Number)" -- see integrate, --
    numerical integration
  * "locate(Function)" -- see locate, -- locate source code
  * "new Manipulator from Function" -- see Manipulator, --
    the class of all file manipulators
  * map(ChainComplex,ChainComplex,Function)
    -- make a map of chain
    complexes
  * "map(GradedModule,GradedModule,Function)" -- see
    map(ChainComplex,ChainComplex,Function),
    -- make a map of chain
    complexes
  * map(Module,Module,Function), --
    create a matrix by specifying a function that gives each entry
  * map(Module,ZZ,Function) -- create a
    matrix from a free module by specifying a function that gives each entry
  * "memoize(Function)" -- see memoize, -- record results of
    function evaluation for future use
  * "memoize(Function,List)" -- see memoize, -- record results
    of function evaluation for future use
  * "merge(HashTable,HashTable,Function)" -- see merge, -- merge
    two hash tables
  * "mergePairs(BasicList,BasicList,Function)" -- see mergePairs,
    -- merge sorted lists of pairs
  * methodOptions(Function) -- recover the
    options used when a method function was created
  * "options(Function)" -- see options(Command), --
    get optional arguments and default values of functions and methods
  * "package(Function)" -- see package, -- get containing
    package
  * "parallelApply(BasicList,Function)" -- see parallelApply,
    -- apply a function to each element in parallel
  * "partition(Function,VirtualTally)" -- see partition, --
    partition a set or list by values of a function
  * "partition(Function,VirtualTally,VisibleList)" -- see partition,
    -- partition a set or list by values of a function
  * "partition(Function,VisibleList)" -- see partition, --
    partition a set or list by values of a function
  * "partition(Function,VisibleList,VisibleList)" -- see partition,
    -- partition a set or list by values of a function
  * "position(VisibleList,Function)" -- see position, -- the
    first element of a list satisfying a condition
  * "position(VisibleList,VisibleList,Function)" -- see position,
    -- the first element of a list satisfying a condition
  * "position(ZZ,Function)" -- see position, -- the first
    element of a list satisfying a condition
  * "positions(MutableList,Function)" -- see positions, --
    which elements of a list satisfy a condition
  * "positions(VisibleList,Function)" -- see positions, --
    which elements of a list satisfy a condition
  * product(VisibleList,Function),
    -- product of values of a function
  * product(VisibleList,VisibleList,Function)
    -- product of results of
    applying a function pairwise
  * product(ZZ,Function) -- product of
    consecutive values of a function
  * "profile(String,Function)" -- see profile, -- profile a
    function
  * rsort(List,Function) (missing documentation)
  * "scan(BasicList,BasicList,Function)" -- see scan, -- apply a
    function to each element in a list or sequence
  * "scan(BasicList,Function)" -- see scan, -- apply a function to
    each element in a list or sequence
  * "scan(Thing,Function)" -- see scan, -- apply a function to each
    element in a list or sequence
  * "scan(ZZ,Function)" -- see scan, -- apply a function to each
    element in a list or sequence
  * "scanKeys(Database,Function)" -- see scanKeys, -- apply a
    function to each key in a hash table or database
  * "scanKeys(HashTable,Function)" -- see scanKeys, -- apply a
    function to each key in a hash table or database
  * "scanLines(Function,List)" -- see scanLines, -- apply a
    function to each line of a file
  * "scanLines(Function,String)" -- see scanLines, -- apply a
    function to each line of a file
  * "scanPairs(HashTable,Function)" -- see scanPairs, -- apply
    a function to the pairs in a hash table
  * "scanValues(HashTable,Function)" -- see scanValues, --
    apply a function to each value in a hash table or database
  * "schedule(Function)" -- see schedule, -- schedule a task
    for execution
  * "schedule(Function,Thing)" -- see schedule, -- schedule a
    task for execution
  * select(BasicList,Function), --
    select elements from a list
  * select(HashTable,Function), --
    select part of a hash table
  * "selectValues(HashTable,Function)" -- see select(HashTable,Function),
    -- select part of a hash table
  * select(Thing,Function) -- select
    elements from an object with an iterator
  * select(ZZ,BasicList,Function),
    -- select a limited number of elements from a list
  * select(ZZ,Function) -- select integers
  * select(ZZ,HashTable,Function),
    -- select a limited number of pairs from a hash table
  * "selectValues(ZZ,HashTable,Function)" -- see
    select(ZZ,HashTable,Function), --
    select a limited number of pairs from a hash table
  * "select(Set,Function)" -- see select(ZZ,Set,Function),
    -- select a part of a set
  * select(ZZ,Set,Function) -- select a
    part of a set
  * "selectKeys(HashTable,Function)" -- see selectKeys, --
    select a part of a hash table by keys
  * "selectKeys(ZZ,HashTable,Function)" -- see selectKeys, --
    select a part of a hash table by keys
  * "selectPairs(HashTable,Function)" -- see selectPairs, --
    select a part of a hash table by pairs
  * "selectPairs(ZZ,HashTable,Function)" -- see selectPairs,
    -- select a part of a hash table by pairs
  * Set / Function (missing documentation)
  * "setupLift(Function,Ring,Ring)" -- see setupLift, -- set
    up lift from one ring to another
  * sort(List,Function) (missing documentation)
  * "sublists(VisibleList,Function)" -- see sublists, --
    process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Function)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Function,Function)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Function,Nothing)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Nothing)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Nothing,Function)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Nothing,Nothing)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * sum(VisibleList,Function) -- sum
    results of applying a function
  * sum(VisibleList,VisibleList,Function)
    -- sum results of applying a
    function pairwise
  * sum(ZZ,Function) -- sum consecutive values
    of a function
  * /// Function \\ Thing /// -- see Thing // Function,
    -- apply a function
  * Thing // Function -- apply a function
  * "ultimate(Function,Thing)" -- see ultimate, -- ultimate
    value for an iteration
  * /// Function \ String /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// Function \ VirtualTally /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// Function \ VisibleList /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "List / Function" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "String / Function" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "VirtualTally / Function" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * VisibleList / Function -- apply a function
    to elements of a list

For the programmer
==================

The object Function, is a type, with ancestor
class Thing.

# BasicList -- length or cardinality
************************************

Synopsis
========

  * Operator: #,
  * Usage:
        #x
  * Inputs:
      * x, a basic list, HashTable, Set, or String
  * Outputs:
      * an integer, the length of x

Description
===========

If x is a list, #x is the number of elements in x.

+-------------------------+
|i1 : L = {1, 2, 3, 2, 1};|
+-------------------------+
|i2 : #L                  |
|                         |
|o2 = 5                   |
+-------------------------+

If x is a set, #x is the cardinality of x.

+-----------------------+
|i3 : S = new Set from L|
|                       |
|o3 = set {1, 2, 3}     |
|                       |
|o3 : Set               |
+-----------------------+
|i4 : #S                |
|                       |
|o4 = 3                 |
+-----------------------+

If x is a hash table, #x is the number of key-value pairs stored in x.

+--------------------------------------------+
|i5 : T = new HashTable from {a => 1, b => 2}|
|                                            |
|o5 = HashTable{a => 1}                      |
|               b => 2                       |
|                                            |
|o5 : HashTable                              |
+--------------------------------------------+
|i6 : #T                                     |
|                                            |
|o6 = 2                                      |
+--------------------------------------------+

If x is a string, #x is the number of characters in x.

+----------------------------------------------------+
|i7 : s = "a perfectly adequate example of a string";|
+----------------------------------------------------+
|i8 : #s                                             |
|                                                    |
|o8 = 40                                             |
+----------------------------------------------------+

See also
========

  * # -- length or access to elements
  * #? -- check existence of value in a list, hash table, database,
    or string
  * BasicList # ZZ -- get value from list, hash table,
    database, or string
  * keys -- keys used in a hash table, dictionary, or database
  * pairs -- list the pairs in a hash table, dictionary, or basic
    list
  * values -- values in a hash table
  * hash tables
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use this method:
========================

  * # BasicList -- length or cardinality
  * "# HashTable"
  * "# Set"
  * "# String"

- List -- negation of a vector
******************************

Synopsis
========

  * Operator: -,
  * Usage:
        -v
  * Inputs:
      * v, a list interpreted as a vector
  * Outputs:
      * the negation of v

Description
===========

+-----------------+
|i1 : - {1,5,6}   |
|                 |
|o1 = {-1, -5, -6}|
|                 |
|o1 : List        |
+-----------------+

Ways to use this method:
========================

  * - List -- negation of a vector

- Vector -- negation of a Vector
********************************

Synopsis
========

  * Operator: -,

Description
===========

-v -- the negation of v

+-------------------------+
|i1 : v = vector {2,3,5,7}|
|                         |
|o1 = | 2 |               |
|     | 3 |               |
|     | 5 |               |
|     | 7 |               |
|                         |
|       4                 |
|o1 : ZZ                  |
+-------------------------+
|i2 : - v                 |
|                         |
|o2 = | -2 |              |
|     | -3 |              |
|     | -5 |              |
|     | -7 |              |
|                         |
|       4                 |
|o2 : ZZ                  |
+-------------------------+

Ways to use this method:
========================

  * - Vector -- negation of a Vector

- VirtualTally -- negation of a VirtualTally
********************************************

Synopsis
========

  * Operator: -,

Description
===========

-x -- the negation of x

+---------------------------------+
|i1 : x = tally {a,b,b,c,c,d,d,d} |
|                                 |
|o1 = Tally{a => 1}               |
|           b => 2                |
|           c => 2                |
|           d => 3                |
|                                 |
|o1 : Tally                       |
+---------------------------------+
|i2 : x' = new VirtualTally from x|
|                                 |
|o2 = VirtualTally{a => 1}        |
|                  b => 2         |
|                  c => 2         |
|                  d => 3         |
|                                 |
|o2 : VirtualTally                |
+---------------------------------+
|i3 : - x'                        |
|                                 |
|o3 = VirtualTally{a => -1}       |
|                  b => -2        |
|                  c => -2        |
|                  d => -3        |
|                                 |
|o3 : VirtualTally                |
+---------------------------------+

Ways to use this method:
========================

  * - VirtualTally -- negation of a VirtualTally

-- -- comment
*************

Synopsis
========

  * Consequences:
      * Macaulay2 ignores commented text
Use a double hyphen -- to introduce a comment in the text of a program.  The
comment runs from to the end of the line.

Emacs does a good job displaying the comments in a different color for
visibility.
+-------------------------------+
|i1 : x = 1 -- this is a comment|
|                               |
|o1 = 1                         |
+-------------------------------+

^! -- a unary postfix operator, used for the upper shriek functor
*****************************************************************

For the programmer
==================

The object ^!, is a keyword.

This operator may be used as a postfix unary operator in an expression like
x^!. The user may install a method, for handling such expressions
with code such as

         X ^!   := (x) -> ...

where X is the class of x.

^* -- a unary postfix operator, used for indicating pullback maps
*****************************************************************

For the programmer
==================

The object ^*, is a keyword.

This operator may be used as a postfix unary operator in an expression like
x^*. The user may install a method, for handling such expressions
with code such as

         X ^*   := (x) -> ...

where X is the class of x.

^< -- a binary operator, used for truncation
********************************************

For the programmer
==================

The object ^<, is a keyword.

This operator may be used as a binary operator in an expression like x^<y. The
user may install binary methods, for handling such
expressions with code such as

         X ^< Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

^<= -- a binary operator, used for truncation
*********************************************

For the programmer
==================

The object ^<=, is a keyword.

This operator may be used as a binary operator in an expression like x^<=y. The
user may install binary methods, for handling such
expressions with code such as

         X ^<= Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

^> -- a binary operator, used for truncation
********************************************

For the programmer
==================

The object ^>, is a keyword.

This operator may be used as a binary operator in an expression like x^>y. The
user may install binary methods, for handling such
expressions with code such as

         X ^> Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

^>= -- a binary operator, used for truncation
*********************************************

For the programmer
==================

The object ^>=, is a keyword.

This operator may be used as a binary operator in an expression like x^>=y. The
user may install binary methods, for handling such
expressions with code such as

         X ^>= Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

^~ -- a unary postfix operator, used for sheafification
*******************************************************

For the programmer
==================

The object ^~, is a keyword.

This operator may be used as a postfix unary operator in an expression like
x^~. The user may install a method, for handling such expressions
with code such as

         X ^~   := (x) -> ...

where X is the class of x.

_! -- a unary postfix operator, used for the lower shriek functor
*****************************************************************

For the programmer
==================

The object _!, is a keyword.

This operator may be used as a postfix unary operator in an expression like
x_!. The user may install a method, for handling such expressions
with code such as

         X _!   := (x) -> ...

where X is the class of x.

_* -- a unary postfix operator, used for indicating pushforward maps
********************************************************************

Ways to use symbol _*:
======================

  * Ideal _* -- get the list of generators of an ideal
  * Module _* (missing documentation)
  * Monoid _* (missing documentation)
  * Ring _* (missing documentation)
  * RingFamily _* -- a unary postfix operator, used
    for indicating pushforward maps

For the programmer
==================

The object _*, is a keyword.

This operator may be used as a postfix unary operator in an expression like
x_*. The user may install a method, for handling such expressions
with code such as

         X _*   := (x) -> ...

where X is the class of x.

_< -- a binary operator, used for truncation
********************************************

For the programmer
==================

The object _<, is a keyword.

This operator may be used as a binary operator in an expression like x_<y. The
user may install binary methods, for handling such
expressions with code such as

         X _< Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

_<= -- a binary operator, used for truncation
*********************************************

For the programmer
==================

The object _<=, is a keyword.

This operator may be used as a binary operator in an expression like x_<=y. The
user may install binary methods, for handling such
expressions with code such as

         X _<= Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

_> -- a binary operator, used for truncation
********************************************

For the programmer
==================

The object _>, is a keyword.

This operator may be used as a binary operator in an expression like x_>y. The
user may install binary methods, for handling such
expressions with code such as

         X _> Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

_>= -- a binary operator, used for truncation
*********************************************

For the programmer
==================

The object _>=, is a keyword.

This operator may be used as a binary operator in an expression like x_>=y. The
user may install binary methods, for handling such
expressions with code such as

         X _>= Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

_~ -- a unary postfix operator
******************************

For the programmer
==================

The object _~, is a keyword.

This operator may be used as a postfix unary operator in an expression like
x_~. The user may install a method, for handling such expressions
with code such as

         X _~   := (x) -> ...

where X is the class of x.

|_ -- a binary operator, used for restriction to a subset
*********************************************************

For the programmer
==================

The object |_, is a keyword.

This operator may be used as a binary operator in an expression like x|_y. The
user may install binary methods, for handling such
expressions with code such as

         X |_ Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

abs -- absolute value function
******************************

Synopsis
========

  * Usage:
        abs x
        abs I
  * Inputs:
      * x, a number
      * I, a real interval,
  * Outputs:
      * the absolute value of x
      * a real interval, an interval containing the absolute values
        of all the point of I

Description
===========

abs x computes the absolute value of x.
+-------------------------+
|i1 : abs(-pi)            |
|                         |
|o1 = 3.141592653589793   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+
|i2 : abs(1+ii)           |
|                         |
|o2 = 1.414213562373095   |
|                         |
|o2 : RR (of precision 53)|
+-------------------------+

Ways to use abs:
================

  * "abs(CC)"
  * "abs(QQ)"
  * "abs(RR)"
  * "abs(RRi)"
  * "abs(ZZ)"
  * abs(Constant) (missing documentation)

For the programmer
==================

The object abs, is a method function.

accumulate -- apply a binary operator repeatedly
************************************************

Synopsis
========

  * Usage:
        accumulate(f, x, L)
        accumulate(f, L)
        accumulate(L, x, f)
        accumulate(L, f)
  * Inputs:
      * f, a function,
      * x, a thing,
      * L, a visible list, or an instance of a class with
        the iterator, method installed
  * Outputs:
      * M, a list,

Description
===========

Suppose L=\{x0, x1, ..., xn\}. Then for any binary operator f, accumulate(f, L)
returns the list \{f(x0, x1), f(f(x0, x1), x2), ...\} . In other words, the
binary operator is applied to the first two elements of L, then to that result
along with the next unused element of L, and so forth.

+---------------------------------------------------------------------+
|i1 : accumulate(plus, {0,1,2,3,4,5})                                 |
|                                                                     |
|o1 = {1, 3, 6, 10, 15}                                               |
|                                                                     |
|o1 : List                                                            |
+---------------------------------------------------------------------+
|i2 : accumulate(concatenate, {a,b,c,d,e})                            |
|                                                                     |
|o2 = {ab, abc, abcd, abcde}                                          |
|                                                                     |
|o2 : List                                                            |
+---------------------------------------------------------------------+
|i3 : accumulate((i,j) -> i|j|i, {"a","b","c","d","e"})               |
|                                                                     |
|o3 = {aba, abacaba, abacabadabacaba, abacabadabacabaeabacabadabacaba}|
|                                                                     |
|o3 : List                                                            |
+---------------------------------------------------------------------+

If accumulate(f, x, L) is called, the element x is used as the first argument
of the binary function f. In other words, accumulate(f, \{x0, x1, \ldots, xn\})
is equivalent to accumulate(f, x0, \{x1, \ldots, xn\}).

+--------------------------------------------+
|i4 : accumulate(plus, 0, {1,2,3,4,5})       |
|                                            |
|o4 = {1, 3, 6, 10, 15}                      |
|                                            |
|o4 : List                                   |
+--------------------------------------------+
|i5 : accumulate((x, y) -> x^y, 2, {3,2,1,2})|
|                                            |
|o5 = {8, 64, 64, 4096}                      |
|                                            |
|o5 : List                                   |
+--------------------------------------------+

The function accumulate(\{x_0, x_1, \ldots, x_n\}, f) returns the list \{...,
f(x_{n-2}, f(x_{n-1}, x_n)), f(x_{n-1}, x_n) \} . That is, f is applied to the
last two elements of the list, and the result placed at the end of the output.
Then the accumulation proceeds backwards through the list. The optional
argument x in accumulate(L, x, f) is used as the second argument in the first
evaluation of f. So accumulate(\{x_0, x_1, \ldots, x_{n-1}\}, x_n, f) is
equivalent to accumulate(\{x_0, x_1, \ldots, x_n\}, f).

+--------------------------------------------+
|i6 : accumulate({a,b,c,d,e}, concatenate)   |
|                                            |
|o6 = {abcde, bcde, cde, de}                 |
|                                            |
|o6 : List                                   |
+--------------------------------------------+
|i7 : accumulate({a,b,c,d}, e, concatenate)  |
|                                            |
|o7 = {abcde, bcde, cde, de}                 |
|                                            |
|o7 : List                                   |
+--------------------------------------------+
|i8 : accumulate({2,3,2,1}, 2, (x, y) -> x^y)|
|                                            |
|o8 = {512, 9, 2, 1}                         |
|                                            |
|o8 : List                                   |
+--------------------------------------------+

If L is an instance of class the the iterator, method
installed, e.g., a string, then it may also be used with accumulate, but only
the versions with f as the first argument.  Its return value in this case is an
Iterator, object.

+-----------------------------------------+
|i9 : iter = accumulate(identity, "abcde")|
|                                         |
|o9 = iter                                |
|                                         |
|o9 : Iterator                            |
+-----------------------------------------+
|i10 : next iter                          |
|                                         |
|o10 = (a, b)                             |
|                                         |
|o10 : Sequence                           |
+-----------------------------------------+
|i11 : next iter                          |
|                                         |
|o11 = ((a, b), c)                        |
|                                         |
|o11 : Sequence                           |
+-----------------------------------------+
|i12 : next iter                          |
|                                         |
|o12 = (((a, b), c), d)                   |
|                                         |
|o12 : Sequence                           |
+-----------------------------------------+

The difference between fold and accumulate, is that fold
returns the final result of all the nested evaluations of f, while accumulate
lists all the intermediate values as well.

+--------------------------------------+
|i13 : fold({2,3,2,1}, 2, (x,y) -> x^y)|
|                                      |
|o13 = 512                             |
+--------------------------------------+

See also
========

  * apply -- apply a function to each element
  * fold -- apply a binary operator repeatedly
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use accumulate:
=======================

  * "accumulate(Function,Thing)"
  * "accumulate(Function,Thing,Thing)"
  * "accumulate(Function,Thing,VisibleList)"
  * "accumulate(Function,VisibleList)"
  * "accumulate(VisibleList,Function)"
  * "accumulate(VisibleList,Thing,Function)"

For the programmer
==================

The object accumulate, is a method function.

acos -- arccosine
*****************

Synopsis
========

  * Usage:
        acos x
        acos I
  * Inputs:
      * x
      * I, a real interval,
  * Outputs:
      * a number, the arccosine (in radians) of x
      * a real interval, an interval containing the arccosines of
        the points of I

Description
===========

+-------------------------+
|i1 : acos 0.5            |
|                         |
|o1 = 1.047197551196598   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See Trigonometric function (see
https://en.wikipedia.org/wiki/Trigonometric_function ).

Ways to use acos:
=================

  * "acos(CC)"
  * "acos(RR)"
  * "acos(RRi)"

For the programmer
==================

The object acos, is a method function.

acosh -- inverse hyperbolic cosine
**********************************

Synopsis
========

  * Usage:
        acosh x
  * Inputs:
      * x
  * Outputs:
      * a number, the inverse hyperbolic cosine of x

Description
===========

+-------------------------+
|i1 : acosh .2            |
|                         |
|o1 = 1.369438406004566*ii|
|                         |
|o1 : CC (of precision 53)|
+-------------------------+
|i2 : cosh oo             |
|                         |
|o2 = .1999999999999999   |
|                         |
|o2 : CC (of precision 53)|
+-------------------------+

See Hyperbolic function (see https://en.wikipedia.org/wiki/Hyperbolic_function
).

Ways to use acosh:
==================

  * "acosh(Number)"

For the programmer
==================

The object acosh, is a method function.

acot -- compute the inverse cotangent
*************************************

Synopsis
========

  * Usage:
        acot x
  * Inputs:
      * x, a real number,
  * Outputs:
      * a real number, the arccotangent (in radians) of x

Description
===========

+-------------------------+
|i1 : acot 2              |
|                         |
|o1 = .4636476090008061   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

Ways to use acot:
=================

  * "acot(Number)"

For the programmer
==================

The object acot, is a method function.

acoth -- compute the hyperbolic arctangent of a number
******************************************************

Synopsis
========

  * Usage:
        acoth x
  * Inputs:
      * x, a number,
  * Outputs:
      * a number, the hyperbolic arccotangent of x

Description
===========

+-------------------------------------------+
|i1 : acoth .4                              |
|                                           |
|o1 = .4236489301936018+1.570796326794897*ii|
|                                           |
|o1 : CC (of precision 53)                  |
+-------------------------------------------+
|i2 : acoth 4.                              |
|                                           |
|o2 = .2554128118829954                     |
|                                           |
|o2 : RR (of precision 53)                  |
+-------------------------------------------+

Ways to use acoth:
==================

  * "acoth(Number)"

For the programmer
==================

The object acoth, is a method function.

AdditionalPaths -- list of non-standard paths to search for a program
*********************************************************************

Functions with optional argument named AdditionalPaths:
=======================================================

  * "findProgram(...,AdditionalPaths=>...)" -- see findProgram,
    -- load external program

For the programmer
==================

The object AdditionalPaths, is a symbol.

Adjacent -- the class of all adjacent expression pairs
******************************************************

Description
===========

Adjacent is a type of Expression, representing a pair of
adjacent expressions, separated only by white space.

For the programmer
==================

The object Adjacent, is a header type, with
ancestor classes Expression, < BasicList <
Thing.

AfterEval -- top level method applied after evaluation
******************************************************

Synopsis
========

  * Usage:
        X#AfterEval = f
  * Inputs:
      * f, a function to be applied after evaluating a top-level evaluation
        result r of type X.
  * Consequences:
      * The value returned result replaces the original for storing in the
        output variables and for printing

For the programmer
==================

The object AfterEval, is a symbol.

AfterNoPrint -- top level method applied after not printing
***********************************************************

Synopsis
========

  * Usage:
        X#{topLevelMode,AfterNoPrint} = f
  * Inputs:
      * f, a function to be applied after not printing a top-level evaluation
        result r of type X.
  * Consequences:
      * The function f will be applied at top level to the result of an
        evaluation when printing of the result has been suppressed by a
        semicolon.

For the programmer
==================

The object AfterNoPrint, is a symbol.

AfterPrint -- top level method applied after printing
*****************************************************

Synopsis
========

  * Usage:
        X#{topLevelMode,AfterPrint} = f
  * Inputs:
      * f, a function to be applied after printing a top-level evaluation
        result r of type X.
  * Outputs:
      * The value returned by f is discarded.

Description
===========

This method is used to print the type of the result of a computation.
+--------+
|i1 : 3/4|
|        |
|     3  |
|o1 = -  |
|     4  |
|        |
|o1 : QQ |
+--------+
We could suppress that output for a single type as follows.
+-------------------------------------------+
|i2 : QQ#{topLevelMode,AfterPrint} = r -> r;|
+-------------------------------------------+
|i3 : 3/4                                   |
|                                           |
|     3                                     |
|o3 = -                                     |
|     4                                     |
+-------------------------------------------+

For the programmer
==================

The object AfterPrint, is a symbol.

agm -- arithmetic-geometric mean
********************************

Synopsis
========

  * Usage:
        agm(x,y)
  * Inputs:
      * x, a number
      * y, a number
  * Outputs:
      * the arithmetic-geometric mean of x and y

Description
===========

+-------------------------------------------------------------------+
|i1 : agm(1,2p200)                                                  |
|                                                                   |
|o1 = 1.456791031046906869186432383265081974973863943221305590794173|
|                                                                   |
|o1 : RR (of precision 200)                                         |
+-------------------------------------------------------------------+

See Arithmetic-geometric mean (see
https://en.wikipedia.org/wiki/Arithmetic-geometric_mean ).

Ways to use agm:
================

  * "agm(CC,CC)"
  * "agm(CC,RR)"
  * "agm(RR,CC)"
  * "agm(RR,RR)"

For the programmer
==================

The object agm, is a method function.

all -- whether all elements satisfy a specified condition
*********************************************************

See also
========

  * scan -- apply a function to each element in a list or sequence
  * apply -- apply a function to each element
  * select -- select from a list, hash table, or string
  * any -- whether any elements satisfy a specified condition
  * isMember -- test membership in a list or set

Ways to use all:
================

  * all(BasicList,BasicList,Function)
    -- whether all corresponding
    elements of a pair of lists satisfy a condition
  * "all(BasicList)" -- see all(BasicList,Function),
    -- whether all elements of a list satisfy a
    specified condition
  * all(BasicList,Function) -- whether
    all elements of a list satisfy a specified condition
  * "all(ZZ,Function)" -- see all(BasicList,Function),
    -- whether all elements of a list satisfy a
    specified condition
  * all(HashTable,Function) -- whether
    all key/value pairs in a hash table satisfy a specified condition

For the programmer
==================

The object all, is a method function.

all(BasicList,BasicList,Function) -- whether all corresponding elements of a pair of lists satisfy a condition
**************************************************************************************************************

Synopsis
========

  * Function: all,
  * Usage:
        all(v,w,f)
  * Inputs:
      * v, a basic list,
      * w, a basic list,
      * f, a function, a function of two variables that
        returns true or false
  * Outputs:
      * a Boolean value, true, if f returns true
        when applied to every pair (x,y) of corresponding elements of v and w,
        and false, otherwise

Description
===========

+----------------------------------------------------+
|i1 : all((1,2,3,4),(2,3,4,5), (i,j) -> i<=j)        |
|                                                    |
|o1 = true                                           |
+----------------------------------------------------+
|i2 : all((1,2,5,4),(2,3,4,5), (i,j) -> i<=j)        |
|                                                    |
|o2 = false                                          |
+----------------------------------------------------+
|i3 : all((1,2,5,4),(2,3,4,5), x -> (print x; false))|
|(1, 2)                                              |
|                                                    |
|o3 = false                                          |
+----------------------------------------------------+
|i4 : all((1,2,5,4),(2,3,4,5), x -> (print x; true)) |
|(1, 2)                                              |
|(2, 3)                                              |
|(5, 4)                                              |
|(4, 5)                                              |
|                                                    |
|o4 = true                                           |
+----------------------------------------------------+

See also
========

  * scan -- apply a function to each element in a list or sequence
  * apply -- apply a function to each element
  * select -- select from a list, hash table, or string
  * any -- whether any elements satisfy a specified condition
  * isMember -- test membership in a list or set

Ways to use this method:
========================

  * all(BasicList,BasicList,Function)
    -- whether all corresponding
    elements of a pair of lists satisfy a condition

all(BasicList,Function) -- whether all elements of a list satisfy a specified condition
***************************************************************************************

Synopsis
========

  * Function: all,
  * Usage:
        all(L,f)
  * Inputs:
      * L, or an integer.  If an integer is given, then the sequence
        0..L-1 is used.
      * f, which returns true or false. If omitted, the identity,
        function is used
  * Outputs:
      * a Boolean value, true, if f returns true
        when applied to every element of L and false, otherwise

Description
===========

+-------------------------+
|i1 : all({1,2,3,4}, even)|
|                         |
|o1 = false               |
+-------------------------+
|i2 : all({2,4,6,8}, even)|
|                         |
|o2 = true                |
+-------------------------+
|i3 : all{true,true,true} |
|                         |
|o3 = true                |
+-------------------------+
|i4 : all{true,true,false}|
|                         |
|o4 = false               |
+-------------------------+
|i5 : all{}               |
|                         |
|o5 = true                |
+-------------------------+
|i6 : all(7, x -> x < 10) |
|                         |
|o6 = true                |
+-------------------------+

See also
========

  * scan -- apply a function to each element in a list or sequence
  * apply -- apply a function to each element
  * select -- select from a list, hash table, or string
  * any -- whether any elements satisfy a specified condition
  * isMember -- test membership in a list or set

Ways to use this method:
========================

  * "all(BasicList)"
  * all(BasicList,Function) -- whether
    all elements of a list satisfy a specified condition
  * "all(ZZ,Function)"

all(HashTable,Function) -- whether all key/value pairs in a hash table satisfy a specified condition
****************************************************************************************************

Synopsis
========

  * Function: all,
  * Usage:
        all(H,f)
  * Inputs:
      * H, a hash table,
      * f, a function, , which returns true or false
  * Outputs:
      * a Boolean value, true, if freturns true
        when applied to all key/value pairs of H and false,
        otherwise

Description
===========

+------------------------------------------------------+
|i1 : all(hashTable{1=>3, 2=>2, 3=>1}, (a,b) -> a == b)|
|                                                      |
|o1 = false                                            |
+------------------------------------------------------+
|i2 : all(hashTable{1=>1, 2=>2, 3=>3}, (a,b) -> a == b)|
|                                                      |
|o2 = true                                             |
+------------------------------------------------------+

See also
========

  * scan -- apply a function to each element in a list or sequence
  * apply -- apply a function to each element
  * select -- select from a list, hash table, or string
  * any -- whether any elements satisfy a specified condition
  * isMember -- test membership in a list or set

Ways to use this method:
========================

  * all(HashTable,Function) -- whether
    all key/value pairs in a hash table satisfy a specified condition

ambient -- ambient free module of a subquotient, or ambient ring
****************************************************************

Description
===========

Each module M in Macaulay2 is a quotient, submodule or subquotient of a free
module, called the ambient free module of M.

The ambient ring of a quotient ring R/I is the polynomial ring of that it is a
quotient.  The ambient ring of a Galois field is the quotient ring that it was
constructed from.

See also
========

  * GF -- make a finite field
  * cover -- get the covering free module
  * super -- get the ambient module

Ways to use ambient:
====================

  * ambient(AffineVariety) (missing documentation)
  * ambient(CoherentSheaf) (missing documentation)
  * ambient(GaloisField) -- corresponding
    quotient ring
  * ambient(Matrix) -- get the map between the
    ambient free modules
  * "ambient(GradedModule)" -- see ambient(Module),
    -- ambient free module
  * ambient(Module) -- ambient free module
  * ambient(ProjectiveVariety) (missing documentation)
  * "ambient(PolynomialRing)" -- see ambient(Ring), --
    ambient polynomial ring
  * "ambient(QuotientRing)" -- see ambient(Ring), --
    ambient polynomial ring
  * ambient(Ring) -- ambient polynomial ring
  * ambient(SheafMap) (missing documentation)

For the programmer
==================

The object ambient, is a method function.

ambient(GaloisField) -- corresponding quotient ring
***************************************************

Synopsis
========

  * Function: ambient,
  * Usage:
        ambient F
  * Inputs:
      * F
  * Outputs:
      * a ring, a quotient of a polynomial ring over the prime
        field

Description
===========

description
+---------------------------+
|i1 : F = GF(25,Variable=>a)|
|                           |
|o1 = F                     |
|                           |
|o1 : GaloisField           |
+---------------------------+
|i2 : ambient F             |
|                           |
|        ZZ                 |
|        --[a]              |
|         5                 |
|o2 = ----------            |
|      2                    |
|     a  - a + 2            |
|                           |
|o2 : QuotientRing          |
+---------------------------+

Ways to use this method:
========================

  * ambient(GaloisField) -- corresponding
    quotient ring

ambient(Matrix) -- get the map between the ambient free modules
***************************************************************

Synopsis
========

  * Function: ambient,
  * Usage:
        ambient f
  * Inputs:
      * f, M --> N, where M is a free module or quotient of a free module F.
  * Outputs:
      * a matrix, ambient M --> ambient N

Description
===========

+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..d];                                                           |
+-----------------------------------------------------------------------------+
|i2 : f = map(image vars R, coker matrix{{a,b},{c,d}}, transpose              |
|                                                                             |
|o2 = {1} | a 2d |                                                            |
|     {1} | b 2c |                                                            |
|     {1} | c 0  |                                                            |
|     {1} | d 0  |                                                            |
|                                                                             |
|o2 : Matrix                                                                  |
|-----------------------------------------------------------------------------|
|matrix{{a,b,c,d},{d,c,b,a}})                                                 |
+-----------------------------------------------------------------------------+
|i3 : target f                                                                |
|                                                                             |
|o3 = image | a b c d |                                                       |
|                                                                             |
|                             1                                               |
|o3 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+
|i4 : source f                                                                |
|                                                                             |
|o4 = cokernel | a b |                                                        |
|              | c d |                                                        |
|                                                                             |
|                            2                                                |
|o4 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i5 : ambient f                                                               |
|                                                                             |
|o5 = | a2+b2+c2+d2 2bc+2ad |                                                 |
|                                                                             |
|             1      2                                                        |
|o5 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * cover(Module) -- get the covering free module
  * cover(Matrix) -- get the map between the covering
    free modules
  * matrix(Matrix) -- the matrix between generators

Ways to use this method:
========================

  * ambient(Matrix) -- get the map between the
    ambient free modules

ambient(Module) -- ambient free module
**************************************

Synopsis
========

  * Function: ambient,
  * Usage:
        ambient M
  * Inputs:
      * M
  * Outputs:
      * a module, a free module

Description
===========

If a module is a submodule or quotient of a free module F, or is a subquotient
of F (that is, a submodule of a quotient of F), then this routine yields the
free module F.
+---------------------------------------------------------------------+
|i1 : R = QQ[x_1 .. x_5]                                              |
|                                                                     |
|o1 = R                                                               |
|                                                                     |
|o1 : PolynomialRing                                                  |
+---------------------------------------------------------------------+
|i2 : N = image matrix{{x_1,x_2},{x_2,x_3}}                           |
|                                                                     |
|o2 = image | x_1 x_2 |                                               |
|           | x_2 x_3 |                                               |
|                                                                     |
|                             2                                       |
|o2 : R-module, submodule of R                                        |
+---------------------------------------------------------------------+
|i3 : ambient N                                                       |
|                                                                     |
|      2                                                              |
|o3 = R                                                               |
|                                                                     |
|o3 : R-module, free                                                  |
+---------------------------------------------------------------------+
|i4 : ambient cokernel vars R                                         |
|                                                                     |
|      1                                                              |
|o4 = R                                                               |
|                                                                     |
|o4 : R-module, free                                                  |
+---------------------------------------------------------------------+
|i5 : ambient kernel vars R                                           |
|                                                                     |
|      5                                                              |
|o5 = R                                                               |
|                                                                     |
|o5 : R-module, free, degrees {5:1}                                   |
+---------------------------------------------------------------------+
|i6 : M = image vars R ++ cokernel vars R                             |
|                                                                     |
|o6 = subquotient (| x_1 x_2 x_3 x_4 x_5 0 |, | 0   0   0   0   0   |)|
|                  | 0   0   0   0   0   1 |  | x_1 x_2 x_3 x_4 x_5 | |
|                                                                     |
|                               2                                     |
|o6 : R-module, subquotient of R                                      |
+---------------------------------------------------------------------+
|i7 : ambient M                                                       |
|                                                                     |
|      2                                                              |
|o7 = R                                                               |
|                                                                     |
|o7 : R-module, free                                                  |
+---------------------------------------------------------------------+
This module is always the common target free module of the generator and
relation matrices of M
+-------------------------------------+
|i8 : ambient M == target generators M|
|                                     |
|o8 = true                            |
+-------------------------------------+
|i9 : ambient M == target relations M |
|                                     |
|o9 = true                            |
+-------------------------------------+

See also
========

  * subquotient modules -- the way Macaulay2
    represents modules
  * cover(Module) -- get the covering free module
  * super(Module) -- get the ambient module
  * generators(Module) -- the generator matrix
    of a module
  * relations(Module) -- the defining relations

Ways to use this method:
========================

  * "ambient(GradedModule)"
  * ambient(Module) -- ambient free module

ambient(Ring) -- ambient polynomial ring
****************************************

Synopsis
========

  * Function: ambient,
  * Usage:
        ambient R
  * Inputs:
      * R, a polynomial ring or a quotient of a polynomial ring
  * Outputs:
      * a ring, the polynomial ring of which this ring is a
        quotient

Description
===========

+---------------------+
|i1 : A = ZZ[a..d];   |
+---------------------+
|i2 : B = A/(3*a^2-1);|
+---------------------+
|i3 : C = B/(a*b-3);  |
+---------------------+
|i4 : describe C      |
|                     |
|        B            |
|o4 = -------         |
|     a*b - 3         |
+---------------------+
|i5 : ambient C       |
|                     |
|o5 = B               |
|                     |
|o5 : QuotientRing    |
+---------------------+
If R is not a quotient of a polynomial ring, an error is given.

Caveat
======

If the ring is a GaloisField, then the meaning is
different.  See ambient(GaloisField).

Ways to use this method:
========================

  * "ambient(PolynomialRing)"
  * "ambient(QuotientRing)"
  * ambient(Ring) -- ambient polynomial ring

ancestors -- the ancestors of something
***************************************

Synopsis
========

  * Usage:
        ancestors x
  * Inputs:
      * x
  * Outputs:
      * the list of ancestors of x

Description
===========

+-----------------------------------------------------------------------------+
|i1 : ancestors String                                                        |
|                                                                             |
|o1 = {String, Net, Thing}                                                    |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+
|i2 : ancestors class 3                                                       |
|                                                                             |
|o2 = {ZZ, Number, Thing}                                                     |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : ancestors class 3.                                                      |
|                                                                             |
|o3 = {RR, InexactNumber, Number, Thing}                                      |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : ancestors ring 3.                                                       |
|                                                                             |
|o4 = {RR  , RR , InexactNumber , Nothing, Thing}                             |
|        53    *               *                                              |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : ancestors class ring 3.                                                 |
|                                                                             |
|o5 = {RealField, InexactField, EngineRing, Ring, Type, MutableHashTable,     |
|     ------------------------------------------------------------------------|
|     HashTable, Thing}                                                       |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : ancestors 3                                                             |
|                                                                             |
|o6 = {3, Nothing, Thing}                                                     |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * ancestor -- whether one type is an
    ancestor of another
  * showStructure -- display parent structure

For the programmer
==================

The object ancestors, is a function closure.

AngleBarList -- the class of lists delimited by <| ... |>
*********************************************************

Description
===========

An angle bar list can be created by enclosing elements of any type between
angle bars.

+------------------+
|i1 : x = <|a,b,c|>|
|                  |
|o1 = <|a, b, c|>  |
|                  |
|o1 : AngleBarList |
+------------------+
|i2 : # x          |
|                  |
|o2 = 3            |
+------------------+
|i3 : x#1          |
|                  |
|o3 = b            |
|                  |
|o3 : Symbol       |
+------------------+

To convert angle bar lists to and from other types of BasicList,
one may use new.

+----------------------------------+
|i4 : new AngleBarList from {a,b,c}|
|                                  |
|o4 = <|a, b, c|>                  |
|                                  |
|o4 : AngleBarList                 |
+----------------------------------+
|i5 : new Sequence from <|a,b,c|>  |
|                                  |
|o5 = (a, b, c)                    |
|                                  |
|o5 : Sequence                     |
+----------------------------------+

For an overview of lists and sequences, see lists and sequences.

Methods that use an angle bar list:
===================================

  * Ring AngleBarList (missing documentation)

For the programmer
==================

The object AngleBarList, is a type, with
ancestor classes VisibleList, < BasicList
< Thing.

antipode -- antipode for skew commuting polynomial rings
********************************************************

Synopsis
========

  * Usage:
        antipode f
  * Inputs:
      * f, a ring element, An element in any ring
  * Outputs:
      * a ring element, An element in the same ring, the
        antipode of f

Description
===========

If the ring does not have skew commuting variables, antipode is the identify
function.

If the ring does have skew commuting variables, then the antipode returns a new
polynomial with the same monomials, and the coefficients have been modified to
provide an isomorphism with the ring, and its opposite ring, i.e. this switches
left and right modules of the ring.

This is implemented in the following simple manner: each monomial which has
exactly $d$ skew commuting variables occurring (thus, with exponent 1 each), is
multiplied by $(-1)^{(d-1)(d-2)/2}$.

+---------------------------------------------------+
|i1 : R = ZZ/32003[a..f, SkewCommutative => true]   |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing, 6 skew commutative variable(s)|
+---------------------------------------------------+
|i2 : F = 1 + a + b + a*b + b*c*d + a*b*c*d*e       |
|                                                   |
|o2 = a*b*c*d*e + b*c*d + a*b + a + b + 1           |
|                                                   |
|o2 : R                                             |
+---------------------------------------------------+
|i3 : antipode F                                    |
|                                                   |
|o3 = a*b*c*d*e - b*c*d - a*b + a + b + 1           |
|                                                   |
|o3 : R                                             |
+---------------------------------------------------+

If the ring has some skew commuting variables, and some commutative ones, then
only the skew ones are considered.

+---------------------------------------------------+
|i4 : S = ZZ/32003[a..f, SkewCommutative => {0,1,2}]|
|                                                   |
|o4 = S                                             |
|                                                   |
|o4 : PolynomialRing, 3 skew commutative variable(s)|
+---------------------------------------------------+
|i5 : F = 1 + a + b + a*b + b*c*d + a*b*c*d*e       |
|                                                   |
|o5 = a*b*c*d*e + b*c*d + a*b + a + b + 1           |
|                                                   |
|o5 : S                                             |
+---------------------------------------------------+
|i6 : antipode F                                    |
|                                                   |
|o6 = - a*b*c*d*e - b*c*d - a*b + a + b + 1         |
|                                                   |
|o6 : S                                             |
+---------------------------------------------------+

The transpose of a matrix applies this function to each entry.  This is
basically because the transpose of a left module gives a right module, and we
need to make that a left module again.  The key reason for this is so that the
transpose of a complex remains a complex.

+-----------------------------------------------------------------------------+
|i7 : use R                                                                   |
|                                                                             |
|o7 = R                                                                       |
|                                                                             |
|o7 : PolynomialRing, 6 skew commutative variable(s)                          |
+-----------------------------------------------------------------------------+
|i8 : M = matrix{{a*b-1, a*c-d, e-a*b*c}}                                     |
|                                                                             |
|o8 = | ab-1 ac-d -abc+e |                                                    |
|                                                                             |
|             1      3                                                        |
|o8 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i9 : N = syz M                                                               |
|                                                                             |
|o9 = {2} | -ad 0  cd   be ae -abd+ac-d -abc-bd -bcd 2abd-ac+d abc-abe-e      |
|     {2} | a   cd bd-c 0  0  1         b       bc   -ab-1     0              |
|     {3} | 0   0  0    b  a  0         0       0    0         -1             |
|     ------------------------------------------------------------------------|
|     bde+ce abce |                                                           |
|     be     0    |                                                           |
|     c      e    |                                                           |
|                                                                             |
|             3      12                                                       |
|o9 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i10 : M*N                                                                    |
|                                                                             |
|o10 = 0                                                                      |
|                                                                             |
|              1      12                                                      |
|o10 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i11 : (transpose N) * (transpose M)                                          |
|                                                                             |
|o11 = 0                                                                      |
|                                                                             |
|              12      1                                                      |
|o11 : Matrix R   <-- R                                                       |
+-----------------------------------------------------------------------------+

If we had not used the antipode, then this would be false!

+-------------------------------------------------------------------+
|i12 : Mt = matrix transpose entries M -- this does not use antipode|
|                                                                   |
|o12 = | ab-1   |                                                   |
|      | ac-d   |                                                   |
|      | -abc+e |                                                   |
|                                                                   |
|              3      1                                             |
|o12 : Matrix R  <-- R                                              |
+-------------------------------------------------------------------+
|i13 : Nt = matrix transpose entries N -- this does not use antipode|
|                                                                   |
|o13 = | -ad       a     0  |                                       |
|      | 0         cd    0  |                                       |
|      | cd        bd-c  0  |                                       |
|      | be        0     b  |                                       |
|      | ae        0     a  |                                       |
|      | -abd+ac-d 1     0  |                                       |
|      | -abc-bd   b     0  |                                       |
|      | -bcd      bc    0  |                                       |
|      | 2abd-ac+d -ab-1 0  |                                       |
|      | abc-abe-e 0     -1 |                                       |
|      | bde+ce    be    c  |                                       |
|      | abce      0     e  |                                       |
|                                                                   |
|              12      3                                            |
|o13 : Matrix R   <-- R                                             |
+-------------------------------------------------------------------+
|i14 : Nt*Mt -- is not zero!                                        |
|                                                                   |
|o14 = | 2ad    |                                                   |
|      | 0      |                                                   |
|      | -2cd   |                                                   |
|      | -2be   |                                                   |
|      | -2ae   |                                                   |
|      | 0      |                                                   |
|      | 2bd    |                                                   |
|      | 0      |                                                   |
|      | 0      |                                                   |
|      | 0      |                                                   |
|      | -2ce   |                                                   |
|      | -2abce |                                                   |
|                                                                   |
|              12      1                                            |
|o14 : Matrix R   <-- R                                             |
+-------------------------------------------------------------------+

Caveat
======

If the ring is a Weyl algebra, the antipode is the identity, which is probably
not what is wanted.  If the ring is a quotient of a skew commuting polynomial
ring $R/I$, then the antipode of an element should really be in the quotient
ring $R/(antipode(I))$, but this function returns an element in the same ring.

See also
========

  * transpose -- transpose a table or a matrix

Ways to use antipode:
=====================

  * "antipode(RingElement)"

For the programmer
==================

The object antipode, is a method function.

any -- whether any elements satisfy a specified condition
*********************************************************

See also
========

  * scan -- apply a function to each element in a list or sequence
  * apply -- apply a function to each element
  * select -- select from a list, hash table, or string
  * all -- whether all elements satisfy a specified condition
  * isMember -- test membership in a list or set

Ways to use any:
================

  * any(BasicList,BasicList,Function)
    -- whether any corresponding
    elements of a pair of lists satisfy a condition
  * any(BasicList,Function) -- whether
    any elements of a list satisfy a specified condition
  * "any(ZZ,Function)" -- see any(BasicList,Function),
    -- whether any elements of a list satisfy a
    specified condition
  * any(HashTable,Function) -- whether
    all key/value pairs in a hash table satisfy a specified condition

For the programmer
==================

The object any, is a compiled function.

any(BasicList,BasicList,Function) -- whether any corresponding elements of a pair of lists satisfy a condition
**************************************************************************************************************

Synopsis
========

  * Function: any,
  * Usage:
        any(v,w,f)
  * Inputs:
      * v, a basic list,
      * w, a basic list,
      * f, a function, a function of two variables that
        returns true or false
  * Outputs:
      * a Boolean value, true, if f returns true
        when applied to some pair (x,y) of corresponding elements of v and w,
        and false, otherwise

Description
===========

+----------------------------------------------------+
|i1 : any((1,2,3,4),(2,3,4,5), (i,j) -> i>j)         |
|                                                    |
|o1 = false                                          |
+----------------------------------------------------+
|i2 : any((1,2,5,4),(2,3,4,5), (i,j) -> i>j)         |
|                                                    |
|o2 = true                                           |
+----------------------------------------------------+
|i3 : any((1,2,5,4),(2,3,4,5), x -> (print x; false))|
|(1, 2)                                              |
|(2, 3)                                              |
|(5, 4)                                              |
|(4, 5)                                              |
|                                                    |
|o3 = false                                          |
+----------------------------------------------------+
|i4 : any((1,2,5,4),(2,3,4,5), x -> (print x; true)) |
|(1, 2)                                              |
|                                                    |
|o4 = true                                           |
+----------------------------------------------------+

See also
========

  * scan -- apply a function to each element in a list or sequence
  * apply -- apply a function to each element
  * select -- select from a list, hash table, or string
  * any -- whether any elements satisfy a specified condition
  * isMember -- test membership in a list or set

Ways to use this method:
========================

  * any(BasicList,BasicList,Function)
    -- whether any corresponding
    elements of a pair of lists satisfy a condition

any(BasicList,Function) -- whether any elements of a list satisfy a specified condition
***************************************************************************************

Synopsis
========

  * Function: any,
  * Usage:
        any(L,f)
  * Inputs:
      * L, or an integer.  If an integer is given, then the sequence
        0..L-1 is used.
      * f, a function, which returns true or false
  * Outputs:
      * a Boolean value, true, if f returns true
        when applied to any element of L and false, otherwise

Description
===========

+-------------------------+
|i1 : any({1,2,3,4}, even)|
|                         |
|o1 = true                |
+-------------------------+
|i2 : any({1,3,5,7}, even)|
|                         |
|o2 = false               |
+-------------------------+
|i3 : any(20,n -> n == 15)|
|                         |
|o3 = true                |
+-------------------------+

We can test whether a permutation has a fixed point as follows.

+--------------------------------------+
|i4 : fp = x -> any(#x, i -> x#i == i);|
+--------------------------------------+
|i5 : fp {2,3,4,0,1}                   |
|                                      |
|o5 = false                            |
+--------------------------------------+
|i6 : fp {2,4,0,3,1}                   |
|                                      |
|o6 = true                             |
+--------------------------------------+

See also
========

  * scan -- apply a function to each element in a list or sequence
  * apply -- apply a function to each element
  * select -- select from a list, hash table, or string
  * any -- whether any elements satisfy a specified condition
  * isMember -- test membership in a list or set

Ways to use this method:
========================

  * any(BasicList,Function) -- whether
    any elements of a list satisfy a specified condition
  * "any(ZZ,Function)"

any(HashTable,Function) -- whether all key/value pairs in a hash table satisfy a specified condition
****************************************************************************************************

Synopsis
========

  * Function: any,
  * Usage:
        any(H,f)
  * Inputs:
      * L, a hash table,
      * f, a function, which returns true or false
  * Outputs:
      * a Boolean value, true, if freturns true
        when applied to all key/value pairs of H and false,
        otherwise

Description
===========

+------------------------------------------------------------------+
|i1 : any(hashTable{1=>5, 2=>4, 3=>3, 4=>2, 5=>1}, (a,b) -> a == b)|
|                                                                  |
|o1 = true                                                         |
+------------------------------------------------------------------+
|i2 : any(hashTable{1=>4, 2=>3, 3=>2, 4=>1}, (a,b) -> a == b)      |
|                                                                  |
|o2 = false                                                        |
+------------------------------------------------------------------+

See also
========

  * scan -- apply a function to each element in a list or sequence
  * apply -- apply a function to each element
  * select -- select from a list, hash table, or string
  * all -- whether all elements satisfy a specified condition
  * isMember -- test membership in a list or set

Ways to use this method:
========================

  * any(HashTable,Function) -- whether
    all key/value pairs in a hash table satisfy a specified condition

append -- add an element to the end of a list
*********************************************

Synopsis
========

  * Usage:
        append(L, x)
  * Inputs:
      * L, a basic list,
      * x, a thing,
  * Outputs:
      * a basic list, the list obtained by adding the element
        x to the end of list L

Description
===========

+-------------------------------+
|i1 : append({1, 7, 8, 3}, 3)   |
|                               |
|o1 = {1, 7, 8, 3, 3}           |
|                               |
|o1 : List                      |
+-------------------------------+
|i2 : L = {"old", "old", "old"};|
+-------------------------------+
|i3 : append(L, "new")          |
|                               |
|o3 = {old, old, old, new}      |
|                               |
|o3 : List                      |
+-------------------------------+

The new list will be of the same class, as L.

+-------------------+
|i4 : K = (a, b, c);|
+-------------------+
|i5 : append(K, z)  |
|                   |
|o5 = (a, b, c, z)  |
|                   |
|o5 : Sequence      |
+-------------------+

Only a single element can be appended with this function. To append the
elements of a list, use join. To add the new element to the
beginning of the list, or at a particular index, use prepend, or
insert, respectively.

+-----------------------+
|i6 : join(K, (x, y, z))|
|                       |
|o6 = (a, b, c, x, y, z)|
|                       |
|o6 : Sequence          |
+-----------------------+
|i7 : prepend(z, K)     |
|                       |
|o7 = (z, a, b, c)      |
|                       |
|o7 : Sequence          |
+-----------------------+
|i8 : insert(1, z, K)   |
|                       |
|o8 = (a, z, b, c)      |
|                       |
|o8 : Sequence          |
+-----------------------+

Append always returns a new list, rather than modifying the input list, even if
L is a MutableList.

+--------------------------------------+
|i9 : L = new MutableList from {2,3,5};|
+--------------------------------------+
|i10 : peek append(L, 7)               |
|                                      |
|o10 = MutableList{2, 3, 5, 7}         |
+--------------------------------------+
|i11 : peek L                          |
|                                      |
|o11 = MutableList{2, 3, 5}            |
+--------------------------------------+

Notice that the order of the arguments is switched in prepend versus append: we
write prepend(x, L) and append(L, x). A good way to remember this is that the
new element is visually placed before or after the list, depending on where we
want it to appear in the output.

See also
========

  * insert -- copy a list, inserting an element
  * join -- join lists, sequences, and iterable objects
  * prepend -- add an element to the beginning of a list
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use append:
===================

  * "append(BasicList,Thing)"

For the programmer
==================

The object append, is a compiled function.

applicationDirectory -- the path to the user's application directory
********************************************************************

Synopsis
========

  * Usage:
        applicationDirectory()
  * Outputs:
      * a string, the path to the user's application directory

Description
===========

The function installPackage, by default, installs
packages under the application directory.  At program startup, unless the -q
option is provided on the command line, an entry will be added to the
path, so packages can be loaded from there by loadPackage,
and needsPackage.  Moreover, the
initialization file, if found there, will be run.

The function applicationDirectorySuffix,
determines the value of applicationDirectory, and can be modified by the user.

+-----------------------------+
|i1 : applicationDirectory()  |
|                             |
|o1 = /home/m2user/.Macaulay2/|
+-----------------------------+

Code
====

../../../../../Macaulay2/m2/startup.m2.in:219:28-229:11: --source code:
     applicationDirectory = () -> (
          if getenv "HOME" =!= ""
          then (
               getenv "HOME" | "/" |
               -- we allow the user to change applicationDirectorySuffix to a
               if instance(applicationDirectorySuffix, Function)
               then applicationDirectorySuffix()
               else applicationDirectorySuffix
               )
          else error "environment variable HOME not set"
          );
-------------------------------------------------------------------------------
string or a function

See also
========

  * applicationDirectorySuffix -- suffix
    that determines the user's application directory

For the programmer
==================

The object applicationDirectory, is a
function closure.

applicationDirectorySuffix -- suffix that determines the user's application directory
*************************************************************************************

Synopsis
========

  * Usage:
        applicationDirectorySuffix = s
  * Inputs:
      * s, a string, a relative path, which will be appended to
        the user's home directory to determine the user's application directory
  * Consequences:
      * the value of the function applicationDirectory will use the new value
        of applicationDirectorySuffix

Description
===========

The value of applicationDirectorySuffix may also be a function of no arguments,
in which case its value is used as the path. The initial value of
applicationDirectorySuffix is a string whose value depends on the operating
system and its conventions.

+----------------------------------------------+
|i1 : applicationDirectorySuffix               |
|                                              |
|o1 = .Macaulay2/                              |
+----------------------------------------------+
|i2 : applicationDirectory()                   |
|                                              |
|o2 = /home/m2user/.Macaulay2/                 |
+----------------------------------------------+
|i3 : applicationDirectorySuffix = "local/Mac2"|
|                                              |
|o3 = local/Mac2                               |
+----------------------------------------------+
|i4 : applicationDirectory()                   |
|                                              |
|o4 = /home/m2user/local/Mac2                  |
+----------------------------------------------+

See also
========

  * applicationDirectory -- the path to the user's
    application directory

For the programmer
==================

The object applicationDirectorySuffix, is a
string.

apply -- apply a function to each element
*****************************************

Synopsis
========

  * Usage:
        apply(L,f) or apply(L1,L2,f)

See also
========

  * applyKeys -- apply a function to each key in a hash table
  * applyPairs -- apply a function to each pair in a hash
    table
  * applyValues -- apply a function to each value in a hash
    table
  * applyTable -- apply a function to each element of a
    table
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use apply:
==================

  * apply(BasicList,BasicList,Function)
    -- apply a function to pairs
    of elements, one from each list
  * "apply(BasicList,String,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * "apply(String,BasicList,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * "apply(String,String,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * apply(BasicList,Function) -- apply
    a function to each element of a list
  * "apply(String,Function)" -- see apply(BasicList,Function),
    -- apply a function to each element of a
    list
  * apply(Thing,Function) -- apply a
    function to an object with an iterator
  * apply(ZZ,Function) -- apply a function to
    {0,..., n-1}

For the programmer
==================

The object apply, is a compiled function.

apply(BasicList,BasicList,Function) -- apply a function to pairs of elements, one from each list
************************************************************************************************

Synopsis
========

  * Function: apply,
  * Usage:
        apply(L1,L2,f)
  * Inputs:
      * L1, a basic list, or a string,
      * L2, a basic list, or a string, of the
        same length as L1
      * f, a function, with two arguments
  * Outputs:
      * a basic list, with the ith element obtained by
        evaluating f(L1_i,L2_i)

Description
===========

The result will have the same class as the class of L1 and L2.
+------------------------------------------------+
|i1 : apply({1,2,3}, {100,200,300}, (i,j) -> i+j)|
|                                                |
|o1 = {101, 202, 303}                            |
|                                                |
|o1 : List                                       |
+------------------------------------------------+
|i2 : apply([1,2,3], [100,200,300], (i,j) -> i+j)|
|                                                |
|o2 = [101, 202, 303]                            |
|                                                |
|o2 : Array                                      |
+------------------------------------------------+
|i3 : apply((1,2,3), (100,200,300), (i,j) -> i+j)|
|                                                |
|o3 = (101, 202, 303)                            |
|                                                |
|o3 : Sequence                                   |
+------------------------------------------------+
The exception is that for strings, the result will be a sequence.
+-------------------------------------+
|i4 : apply("foo", "bar", concatenate)|
|                                     |
|o4 = (fb, oa, or)                    |
|                                     |
|o4 : Sequence                        |
+-------------------------------------+

Ways to use this method:
========================

  * apply(BasicList,BasicList,Function)
    -- apply a function to pairs
    of elements, one from each list
  * "apply(BasicList,String,Function)"
  * "apply(String,BasicList,Function)"
  * "apply(String,String,Function)"

apply(BasicList,Function) -- apply a function to each element of a list
***********************************************************************

Synopsis
========

  * Function: apply,
  * Usage:
        apply(L,f)
  * Inputs:
      * L, a basic list, or a string,
      * f, a function, with one argument
  * Outputs:
      * a basic list, obtained by applying f to each element
        of L

Description
===========

The result will have the same class as L.
+-------------------------------+
|i1 : apply({1,3,5,7}, i -> i^2)|
|                               |
|o1 = {1, 9, 25, 49}            |
|                               |
|o1 : List                      |
+-------------------------------+
|i2 : apply([1,3,5,7], i -> i^2)|
|                               |
|o2 = [1, 9, 25, 49]            |
|                               |
|o2 : Array                     |
+-------------------------------+
|i3 : apply((1,3,5,7), i -> i^2)|
|                               |
|o3 = (1, 9, 25, 49)            |
|                               |
|o3 : Sequence                  |
+-------------------------------+
The exception is that for strings, the result will be a sequence.
+---------------------------+
|i4 : apply("foo", identity)|
|                           |
|o4 = (f, o, o)             |
|                           |
|o4 : Sequence              |
+---------------------------+

See also
========

  * VisibleList / Function -- apply a function
    to elements of a list
  * Function \ VisibleList -- apply a function
    to elements of a list

Ways to use this method:
========================

  * apply(BasicList,Function) -- apply
    a function to each element of a list
  * "apply(String,Function)"

apply(Thing,Function) -- apply a function to an object with an iterator
***********************************************************************

Synopsis
========

  * Function: apply,
  * Usage:
        apply(x, f)
  * Inputs:
      * x, a thing, an instance of a class with the
        iterator, method installed;
      * f, a function,
  * Outputs:
      * an iterator,

Description
===========

Suppose x is an instance of a class with the iterator, method
installed and suppose iter is the output of iterator x.  Then a new
Iterator, object is returned whose next, method returns f
next iter  until next iter returns StopIteration, in
which case this new iterator does the same.

+-----------------------------------------------+
|i1 : applyiter = apply(iterator "foo", toUpper)|
|                                               |
|o1 = applyiter                                 |
|                                               |
|o1 : Iterator                                  |
+-----------------------------------------------+
|i2 : next applyiter                            |
|                                               |
|o2 = F                                         |
+-----------------------------------------------+
|i3 : next applyiter                            |
|                                               |
|o3 = O                                         |
+-----------------------------------------------+
|i4 : next applyiter                            |
|                                               |
|o4 = O                                         |
+-----------------------------------------------+
|i5 : next applyiter                            |
|                                               |
|o5 = StopIteration                             |
|                                               |
|o5 : Symbol                                    |
+-----------------------------------------------+

See also
========

  * iterator -- get an iterator
  * Iterator -- class for iterators
  * next -- get the next object from an iterator
  * StopIteration -- stop iteration
  * select(Thing,Function) -- select
    elements from an object with an iterator

Ways to use this method:
========================

  * apply(Thing,Function) -- apply a
    function to an object with an iterator

apply(ZZ,Function) -- apply a function to {0,..., n-1}
******************************************************

Synopsis
========

  * Function: apply,
  * Usage:
        apply(n,f)
  * Inputs:
      * n, an integer,
      * f, a function, with one argument
  * Outputs:
      * a list, obtained by applying f to the list of integers
        {0,..., n-1}

Description
===========

The command  apply(n,f) is equivalent to apply(toList(0 .. n-1),f).
+-----------------------------------------+
|i1 : apply(10, i -> i^2)                 |
|                                         |
|o1 = {0, 1, 4, 9, 16, 25, 36, 49, 64, 81}|
|                                         |
|o1 : List                                |
+-----------------------------------------+

Ways to use this method:
========================

  * apply(ZZ,Function) -- apply a function to
    {0,..., n-1}

applyTable -- apply a function to each element of a table
*********************************************************

Synopsis
========

  * Usage:
        applyTable(T, f)
  * Inputs:
      * T, a list, a table (list of lists of the same length)
      * f, a function,
  * Outputs:
      * A, a list, a table of the same shape as $T$, where the
        function $f$ has been applied elementwise

Description
===========

+---------------------------------------------------+
|i1 : t = table({1,3,5,7}, {0,1,2,4}, (i,j) -> i^j);|
+---------------------------------------------------+
|i2 : netList t                                     |
|                                                   |
|     +-+-+--+----+                                 |
|o2 = |1|1|1 |1   |                                 |
|     +-+-+--+----+                                 |
|     |1|3|9 |81  |                                 |
|     +-+-+--+----+                                 |
|     |1|5|25|625 |                                 |
|     +-+-+--+----+                                 |
|     |1|7|49|2401|                                 |
|     +-+-+--+----+                                 |
+---------------------------------------------------+
|i3 : netList applyTable(t, i -> 2*i)               |
|                                                   |
|     +-+--+--+----+                                |
|o3 = |2|2 |2 |2   |                                |
|     +-+--+--+----+                                |
|     |2|6 |18|162 |                                |
|     +-+--+--+----+                                |
|     |2|10|50|1250|                                |
|     +-+--+--+----+                                |
|     |2|14|98|4802|                                |
|     +-+--+--+----+                                |
+---------------------------------------------------+
|i4 : netList applyTable(t, isPrime)                |
|                                                   |
|     +-----+-----+-----+-----+                     |
|o4 = |false|false|false|false|                     |
|     +-----+-----+-----+-----+                     |
|     |false|true |false|false|                     |
|     +-----+-----+-----+-----+                     |
|     |false|true |false|false|                     |
|     +-----+-----+-----+-----+                     |
|     |false|true |false|false|                     |
|     +-----+-----+-----+-----+                     |
+---------------------------------------------------+

See also
========

  * isTable -- whether something is a list of lists of equal
    length
  * subtable -- extract a subtable from a table
  * table -- make a table from a binary function
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

For the programmer
==================

The object applyTable, is a function closure.

argument -- specify the function in a scripted functor for an argument
**********************************************************************

Description
===========

argument -- a key used in scripted functors under which is stored the function
that accepts the arguments.

See also
========

  * ScriptedFunctor -- the class of all scripted
    functors

For the programmer
==================

The object argument, is a symbol.

Ascending -- specify ascending order
************************************

Description
===========

Ascending -- a symbol used as a value for optional arguments DegreeOrder,
and MonomialOrder.

For the programmer
==================

The object Ascending, is a symbol.

asin -- arcsine
***************

Synopsis
========

  * Usage:
        asin x
        asin I
  * Inputs:
      * x
      * I, a real interval,
  * Outputs:
      * a number, the arcsine (in radians) of x
      * a real interval, an interval containing the arcsines of the
        points of I

Description
===========

+-------------------------+
|i1 : asin 1              |
|                         |
|o1 = 1.570796326794897   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See Trigonometric function (see
https://en.wikipedia.org/wiki/Trigonometric_function ).

Ways to use asin:
=================

  * "asin(CC)"
  * "asin(RR)"
  * "asin(RRi)"
  * asin(RingElement) (missing documentation)

For the programmer
==================

The object asin, is a method function.

asinh -- inverse hyperbolic sine
********************************

Synopsis
========

  * Usage:
        asinh x
  * Inputs:
      * x
  * Outputs:
      * a number, the inverse hyperbolic sine of x

Description
===========

+-------------------------+
|i1 : asinh .2            |
|                         |
|o1 = .1986901103492414   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See Hyperbolic function (see https://en.wikipedia.org/wiki/Hyperbolic_function
).

Ways to use asinh:
==================

  * "asinh(Number)"

For the programmer
==================

The object asinh, is a method function.

assert -- check whether something is true, raise an error if not
****************************************************************

Synopsis
========

  * Usage:
        assert x
  * Inputs:
      * x, a thing,

Description
===========

assert x raises an error if x isn't true.

+----------------------------------------------+
|i1 : stopIfError = false;                     |
+----------------------------------------------+
|i2 : assert( (2+2) === 4)                     |
+----------------------------------------------+
|i3 : assert(rank matrix {{1, 2}, {2, 4}} == 2)|
|stdio:3:6:(3): error: assertion failed        |
+----------------------------------------------+

If x is an Expression, that evaluates to false, then a
partially evaluated form is printed with the error message to assist in
debugging.

+-----------------------------------------------------+
|i4 : assert Equation(rank matrix {{1, 2}, {2, 4}}, 2)|
|stdio:4:6:(3): error: assertion failed:              |
|1 == 2 is false                                      |
+-----------------------------------------------------+

See also
========

  * generateAssertions -- generate assert statements
    from experimental input
  * stopIfError -- whether to stop the program when an
    error occurs

Ways to use assert:
===================

  * "assert(Expression)"
  * "assert(Thing)"

For the programmer
==================

The object assert, is a method function.

AssociativeExpression -- the class of associative expressions
*************************************************************

Types of associative expression:
================================

  * DirectSum (missing documentation)
  * Equation -- the class of all equation expressions
  * Product -- the class of all product expressions
  * Sum -- the class of all sum expressions
  * TensorProduct (missing documentation)

For the programmer
==================

The object AssociativeExpression, is a type,
with ancestor classes Expression, < BasicList
< Thing.

atan -- compute the arctangent of a number
*******************************************

Synopsis
========

  * Usage:
        atan x
        atan I
  * Inputs:
      * x, a real number,
      * I, a real interval,
  * Outputs:
      * a real number, the arctangent (in radians) of x
      * a real interval, an interval containing the arctangents of
        the points of I

Description
===========

+-------------------------+
|i1 : atan 1              |
|                         |
|o1 = .7853981633974483   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+
|i2 : abs atan 1 == pi/4  |
|                         |
|o2 = true                |
+-------------------------+

See also
========

  * atan2 -- compute an angle of a certain triangle

Ways to use atan:
=================

  * "atan(CC)"
  * "atan(RR)"
  * "atan(RRi)"
  * atan(RingElement) (missing documentation)

For the programmer
==================

The object atan, is a method function.

atan2 -- compute an angle of a certain triangle
***********************************************

Synopsis
========

  * Usage:
        atan2(y,x)
        atan2(y,I)
        atan2(J,x)
        atan2(J,I)
  * Inputs:
      * y, a real number,
      * x, a real number,
      * J, a real interval,
      * I, a real interval,
  * Outputs:
      * a real number, the angle (in radians) formed with the x-axis
        by the ray from the origin to the point (x,y)
      * a real number, an interval containing the angles (in
        radians) formed with the x-axis by the rays from the origin to the
        points of (I,y),(x,J),(I,J)

Description
===========

+-------------------------+
|i1 : atan2(1,0)          |
|                         |
|o1 = 1.570796326794897   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+
|i2 : atan2(0,1)          |
|                         |
|o2 = 0                   |
|                         |
|o2 : RR (of precision 53)|
+-------------------------+
|i3 : atan2(-1,-1)        |
|                         |
|o3 = -2.356194490192345  |
|                         |
|o3 : RR (of precision 53)|
+-------------------------+

See also
========

  * atan -- compute the arctangent of a number

Ways to use atan2:
==================

  * "atan2(RR,RR)"
  * "atan2(RR,RRi)"
  * "atan2(RRi,RR)"
  * "atan2(RRi,RRi)"

For the programmer
==================

The object atan2, is a method function.

atanh -- compute the hyperbolic arctangent of a number
******************************************************

Synopsis
========

  * Usage:
        atanh x
  * Inputs:
      * x, a number,
  * Outputs:
      * a number, the hyperbolic arctangent of x

Description
===========

+-------------------------------------------+
|i1 : atanh .4                              |
|                                           |
|o1 = .4236489301936018                     |
|                                           |
|o1 : RR (of precision 53)                  |
+-------------------------------------------+
|i2 : atanh 4.                              |
|                                           |
|o2 = .2554128118829954+1.570796326794897*ii|
|                                           |
|o2 : CC (of precision 53)                  |
+-------------------------------------------+

Ways to use atanh:
==================

  * "atanh(Number)"

For the programmer
==================

The object atanh, is a method function.

atEndOfFile(File) -- test for end of file
*****************************************

Synopsis
========

  * Function: atEndOfFile,
  * Usage:
        atEndOfFile f
  * Inputs:
      * f
  * Outputs:
      * a Boolean value, whether the input file f is at the end

Description
===========

+---------------------------------+
|i1 : f = openInOut "!cat"        |
|                                 |
|o1 = !cat                        |
|                                 |
|o1 : File                        |
+---------------------------------+
|i2 : f << "hi there" << closeOut;|
+---------------------------------+
|i3 : atEndOfFile f               |
|                                 |
|o3 = false                       |
+---------------------------------+
|i4 : peek read f                 |
|                                 |
|o4 = "hi there"                  |
+---------------------------------+
|i5 : atEndOfFile f               |
|                                 |
|o5 = false                       |
+---------------------------------+

Ways to use this method:
========================

  * atEndOfFile(File) -- test for end of file

AtomicInt -- the class of atomic integers
*****************************************

Description
===========

Atomic integers are a special type of integer for which various atomic
operations, which cannot be interrupted, are available.  This makes them useful
for parallel programming.

Caveat
======

On most systems, atomic integers use 32 bits, i.e., they must lie between
$-2^{31}$ and $2^{31} - 1$.

See also
========

  * parallel programming with threads and tasks

Methods that use an atomic integer:
===================================

  * AtomicInt &= ZZ -- atomic fetch and bitwise and
  * AtomicInt += ZZ -- atomic fetch and add
  * AtomicInt -= ZZ -- atomic fetch and subtract
  * AtomicInt ^^= ZZ -- atomic fetch and bitwise xor
  * AtomicInt |= ZZ -- atomic fetch and bitwise or
  * "compareExchange(AtomicInt,ZZ,ZZ)" -- see compareExchange,
    -- compares and possibly exchanges the value of an atomic
    integer
  * "exchange(AtomicInt,ZZ)" -- see exchange, -- exchange the
    value of an atomic integer
  * "new AtomicInt" -- see new AtomicInt from ZZ,
    -- initialize an atomic integer
  * new AtomicInt from ZZ -- initialize an atomic
    integer
  * new ZZ from AtomicInt -- load an atomic
    integer
  * "store(AtomicInt,ZZ)" -- see store, -- store the value of an
    atomic integer

For the programmer
==================

The object AtomicInt, is a type, with ancestor
class Thing.

AtomicInt &= ZZ -- atomic fetch and bitwise and
***********************************************

Synopsis
========

  * Operator: &=,
  * Usage:
        x &= y
  * Inputs:
      * x, an atomic integer,
      * y, an integer,
  * Outputs:
      * an integer,

Description
===========

Bitwise and is performed between x and y and the original value of x is
returned.  This operation occurs atomically and is thread safe.

+------------------------------+
|i1 : x = new AtomicInt from 12|
|                              |
|o1 = 12                       |
|                              |
|o1 : AtomicInt                |
+------------------------------+
|i2 : x &= 10                  |
|                              |
|o2 = 12                       |
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 8                        |
|                              |
|o3 : AtomicInt                |
+------------------------------+

Ways to use this method:
========================

  * AtomicInt &= ZZ -- atomic fetch and bitwise and

AtomicInt += ZZ -- atomic fetch and add
***************************************

Synopsis
========

  * Operator: +=,
  * Usage:
        x += y
  * Inputs:
      * x, an atomic integer,
      * y, an integer,
  * Outputs:
      * an integer,

Description
===========

This performs a fetch-and-add (see https://en.wikipedia.org/wiki/fetch-and-add
) operation.  The atomic integer x is increased by y and its original value is
returned. This operation occurs atomically and is thread safe.

+------------------------------+
|i1 : x = new AtomicInt from 12|
|                              |
|o1 = 12                       |
|                              |
|o1 : AtomicInt                |
+------------------------------+
|i2 : x += 10                  |
|                              |
|o2 = 12                       |
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 22                       |
|                              |
|o3 : AtomicInt                |
+------------------------------+

Ways to use this method:
========================

  * AtomicInt += ZZ -- atomic fetch and add

AtomicInt -= ZZ -- atomic fetch and subtract
********************************************

Synopsis
========

  * Operator: -=,
  * Usage:
        x -= y
  * Inputs:
      * x, an atomic integer,
      * y, an integer,
  * Outputs:
      * an integer,

Description
===========

The atomic integer x is decreased by y and its original value is returned.
This operation occurs atomically and is thread safe.

+------------------------------+
|i1 : x = new AtomicInt from 12|
|                              |
|o1 = 12                       |
|                              |
|o1 : AtomicInt                |
+------------------------------+
|i2 : x -= 10                  |
|                              |
|o2 = 12                       |
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 2                        |
|                              |
|o3 : AtomicInt                |
+------------------------------+

Ways to use this method:
========================

  * AtomicInt -= ZZ -- atomic fetch and subtract

AtomicInt ^^= ZZ -- atomic fetch and bitwise xor
************************************************

Synopsis
========

  * Operator: ^^=,
  * Usage:
        x ^^= y
  * Inputs:
      * x, an atomic integer,
      * y, an integer,
  * Outputs:
      * an integer,

Description
===========

Bitwise xor is performed between x and y and the original value of x is
returned.  This operation occurs atomically and is thread safe.

+------------------------------+
|i1 : x = new AtomicInt from 12|
|                              |
|o1 = 12                       |
|                              |
|o1 : AtomicInt                |
+------------------------------+
|i2 : x ^^= 10                 |
|                              |
|o2 = 12                       |
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 6                        |
|                              |
|o3 : AtomicInt                |
+------------------------------+

Ways to use this method:
========================

  * AtomicInt ^^= ZZ -- atomic fetch and bitwise xor

AtomicInt |= ZZ -- atomic fetch and bitwise or
**********************************************

Synopsis
========

  * Operator: |=,
  * Usage:
        x |= y
  * Inputs:
      * x, an atomic integer,
      * y, an integer,
  * Outputs:
      * an integer,

Description
===========

Bitwise or is performed between x and y and the original value of x is
returned.  This operation occurs atomically and is thread safe.

+------------------------------+
|i1 : x = new AtomicInt from 12|
|                              |
|o1 = 12                       |
|                              |
|o1 : AtomicInt                |
+------------------------------+
|i2 : x |= 10                  |
|                              |
|o2 = 12                       |
+------------------------------+
|i3 : x                        |
|                              |
|o3 = 14                       |
|                              |
|o3 : AtomicInt                |
+------------------------------+

Ways to use this method:
========================

  * AtomicInt |= ZZ -- atomic fetch and bitwise or

backtrace -- whether a backtrace is displayed following an error message
************************************************************************

Synopsis
========

  * Usage:
        backtrace = false
  * Consequences:
      * a backtrace will not displayed following an error message

For the programmer
==================

The object backtrace, is a Boolean value.

Bag -- the class of all bags
****************************

Description
===========

A bag can be used for enclosing something in a container to prevent it from
being printed, in normal circumstances. Any mutable list can be used for this
purpose, but bags are designed for this purpose.  In comparison and sorting,
they are declared to be incomparable.

See also
========

  * unbag

Methods that use a bag:
=======================

  * "Bag ? Bag"
  * unbag(Bag)

For the programmer
==================

The object Bag, is a self initializing type,
with ancestor classes MutableList, <
BasicList < Thing.

Bareiss
*******

Description
===========

This symbol is used as one of the permissible values for the strategy option in
function dealing with determinants.

See also
========

  * exteriorPower(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * minors(...,Strategy=>...)
    -- choose between Bareiss,
    Cofactor and Dynamic algorithms
  * determinant(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms

For the programmer
==================

The object Bareiss, is a symbol.

baseFilename -- the base part of a filename or path
***************************************************

Synopsis
========

  * Usage:
        baseFilename fn
  * Inputs:
      * fn, a string, a filename or path
  * Outputs:
      * the last component of the path

Description
===========

+-----------------------------+
|i1 : baseFilename "/a/b/dir/"|
|                             |
|o1 = dir                     |
+-----------------------------+
|i2 : baseFilename "/a/b/file"|
|                             |
|o2 = file                    |
+-----------------------------+

See also
========

  * File -- the class of all files
  * minimizeFilename -- minimize a file name
  * relativizeFilename -- relativize a file name
  * toAbsolutePath -- the absolute path version of a
    file name
  * searchPath -- search a path for a
    file
  * path -- list of directories to look in

For the programmer
==================

The object baseFilename, is a function closure.

baseName -- the base name of a generator
****************************************

Description
===========

baseName x -- returns the variable or symbol upon which an indexed variable
table or a generator of a monoid or polynomial ring is based.
+-------------------------+
|i1 : R = QQ[x_1 .. x_4,y]|
|                         |
|o1 = R                   |
|                         |
|o1 : PolynomialRing      |
+-------------------------+
|i2 : y                   |
|                         |
|o2 = y                   |
|                         |
|o2 : R                   |
+-------------------------+
|i3 : baseName y          |
|                         |
|o3 = y                   |
|                         |
|o3 : Symbol              |
+-------------------------+
|i4 : x_1                 |
|                         |
|o4 = x                   |
|      1                  |
|                         |
|o4 : R                   |
+-------------------------+
|i5 : baseName x_1        |
|                         |
|o5 = x                   |
|      1                  |
|                         |
|o5 : IndexedVariable     |
+-------------------------+
|i6 : x                   |
|                         |
|o6 = x                   |
|                         |
|o6 : IndexedVariableTable|
+-------------------------+
|i7 : baseName x          |
|                         |
|o7 = x                   |
|                         |
|o7 : Symbol              |
+-------------------------+

Ways to use baseName:
=====================

  * "baseName(IndexedVariable)"
  * "baseName(IndexedVariableTable)"
  * "baseName(RingElement)"
  * "baseName(Subscript)"
  * "baseName(Symbol)"
  * "baseName(Thing)"
  * baseName(MonoidElement) (missing documentation)

For the programmer
==================

The object baseName, is a method function.

baseRing -- produce the ring from which a ring was formed
*********************************************************

Synopsis
========

  * Usage:
        baseRing R
  * Inputs:
      * R, a ring,
  * Outputs:
      * a ring, the ring from which
      * R
      *  was formed

Description
===========

The base ring of a ring R is the ring from which R was formed. For example, if
R is a quotient ring of the form S/I, or if R is a fraction ring of the form
frac S, or if R is a polynomial ring over S, then the base ring is S.

+----------------------------+
|i1 : baseRing QQ            |
|                            |
|o1 = ZZ                     |
|                            |
|o1 : Ring                   |
+----------------------------+
|i2 : R = QQ[x,y]            |
|                            |
|o2 = R                      |
|                            |
|o2 : PolynomialRing         |
+----------------------------+
|i3 : S = R / (x^2 + y^3 - 1)|
|                            |
|o3 = S                      |
|                            |
|o3 : QuotientRing           |
+----------------------------+
|i4 : T = frac S             |
|                            |
|o4 = T                      |
|                            |
|o4 : FractionField          |
+----------------------------+
|i5 : baseRing T             |
|                            |
|o5 = S                      |
|                            |
|o5 : QuotientRing           |
+----------------------------+
|i6 : baseRing S             |
|                            |
|o6 = R                      |
|                            |
|o6 : PolynomialRing         |
+----------------------------+
|i7 : baseRing R             |
|                            |
|o7 = QQ                     |
|                            |
|o7 : Ring                   |
+----------------------------+

The entire chain of base rings can be obtained under the key baseRings.

+-------------------+
|i8 : T.baseRings   |
|                   |
|o8 = {ZZ, QQ, R, S}|
|                   |
|o8 : List          |
+-------------------+

See also
========

  * baseRings -- store the list of base rings of a ring

Ways to use baseRing:
=====================

  * "baseRing(Ring)"

For the programmer
==================

The object baseRing, is a method function.

baseRings -- store the list of base rings of a ring
***************************************************

Description
===========

baseRings -- a symbol used as a key in a ring R under which is stored a list of
base rings for R.

A base ring A of R is one of the rings involved in the construction of R.

The base rings are presented in chronological order.

See also
========

  * baseRing -- produce the ring from which a ring was formed

For the programmer
==================

The object baseRings, is a symbol.

BasicList -- the class of all basic lists
*****************************************

Description
===========

For an overview of lists and sequences, see lists and sequences.

A basic list is a sequence of expressions indexed by a sequence of consecutive
integers of the form 0, 1, ..., N-1.  The number N is called the length of the
list.

There are various types of basic lists, depending on the application, and they
are displayed in different ways. The types first encountered are those of type
VisibleList, but new types are easy to introduce. In the
following example we introduce a new type of basic list called L.
+------------------------------+
|i1 : L = new Type of BasicList|
|                              |
|o1 = L                        |
|                              |
|o1 : Type                     |
+------------------------------+
|i2 : x = new L from {a,b,c,d} |
|                              |
|o2 = L{a, b, c, d}            |
|                              |
|o2 : L                        |
+------------------------------+
|i3 : join(x,x)                |
|                              |
|o3 = L{a, b, c, d, a, b, c, d}|
|                              |
|o3 : L                        |
+------------------------------+

Types of basic list:
====================

  * Command -- the class of all commands
  * Eliminate -- elimination order
  * Expression -- the class of all expressions
  * FilePosition -- the class of all file positions
  * IndexedVariable -- the class of all indexed
    variables
  * LowerBound (Varieties) -- the class of lower bound
    objects
  * Manipulator -- the class of all file manipulators
  * MutableList -- the class of all mutable lists
  * Option -- the class of all key-value pairs K => V
  * Partition -- a type of list representing a partition of a
    natural number
  * ProductOrder -- product ordering
  * RingElement -- the class of all ring elements handled
    by the engine
  * SumOfTwists (Varieties) -- the class of all sums of
    twists
  * Time -- the class of all timing results
  * URL -- a type representing a URL
  * Vector -- the class of all elements of modules that are
    handled by the engine
  * VisibleList -- the class of all visible lists

Functions and methods returning a basic list:
=============================================

  * "append(BasicList,Thing)" -- see append, -- add an element to
    the end of a list
  * apply(BasicList,BasicList,Function)
    -- apply a function to pairs
    of elements, one from each list
  * apply(BasicList,Function) -- apply
    a function to each element of a list
  * "deepSplice(BasicList)" -- see deepSplice, -- remove all
    levels of subsequences from a sequence or list
  * "drop(BasicList,List)" -- see drop, -- drop some elements from
    a list or sequence.
  * "drop(BasicList,ZZ)" -- see drop, -- drop some elements from a
    list or sequence.
  * "insert(ZZ,Thing,BasicList)" -- see insert, -- copy a list,
    inserting an element
  * "mergePairs(BasicList,BasicList,Function)" -- see mergePairs,
    -- merge sorted lists of pairs
  * "prepend(Thing,BasicList)" -- see prepend, -- add an element
    to the beginning of a list
  * replace(ZZ,Thing,BasicList), --
    copy a list, replacing an element
  * "reverse(BasicList)" -- see reverse, -- reverse a list,
    sequence, or string
  * select(BasicList,Function), --
    select elements from a list
  * select(BasicList,Type) -- select
    elements of a given type in a list
  * select(ZZ,BasicList,Function),
    -- select a limited number of elements from a list
  * "splice(BasicList)" -- see splice, -- remove subsequences
    from a sequence or list
  * "switch(ZZ,ZZ,BasicList)" -- see switch, -- copy a list,
    switching two elements
  * "take(BasicList,List)" -- see take, -- Take some elements from
    a list or sequence.
  * "take(BasicList,ZZ)" -- see take, -- Take some elements from a
    list or sequence.

Methods that use a basic list:
==============================

  * # BasicList -- length or cardinality
  * "BasicList #? ZZ" -- see #?, -- check existence of value in a
    list, hash table, database, or string
  * all(BasicList,BasicList,Function)
    -- whether all corresponding
    elements of a pair of lists satisfy a condition
  * "all(BasicList)" -- see all(BasicList,Function),
    -- whether all elements of a list satisfy a
    specified condition
  * all(BasicList,Function) -- whether
    all elements of a list satisfy a specified condition
  * any(BasicList,BasicList,Function)
    -- whether any corresponding
    elements of a pair of lists satisfy a condition
  * any(BasicList,Function) -- whether
    any elements of a list satisfy a specified condition
  * "apply(BasicList,String,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * "apply(String,BasicList,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * "ascii(BasicList)" -- see ascii, -- ASCII character conversion
  * BasicList # ZZ -- get value from list, hash table,
    database, or string
  * "concatenate(BasicList)" -- see concatenate, -- join
    strings
  * "delete(Thing,BasicList)" -- see delete, -- delete some
    elements of a list
  * "horizontalJoin(BasicList)" -- see horizontalJoin, --
    join nets or strings horizontally
  * "maxPosition(BasicList)" -- see maxPosition, -- position
    of the largest element
  * "mingle(BasicList)" -- see mingle, -- mingle elements of
    several lists
  * "minPosition(BasicList)" -- see minPosition, -- position
    of the smallest element
  * "pack(BasicList,ZZ)" -- see pack, -- pack elements of a list or
    string into several shorter lists or strings
  * "pack(ZZ,BasicList)" -- see pack, -- pack elements of a list or
    string into several shorter lists or strings
  * "pairs(BasicList)" -- see pairs, -- list the pairs in a hash
    table, dictionary, or basic list
  * "parallelApply(BasicList,Function)" -- see parallelApply,
    -- apply a function to each element in parallel
  * "scan(BasicList,BasicList,Function)" -- see scan, -- apply a
    function to each element in a list or sequence
  * "scan(BasicList,Function)" -- see scan, -- apply a function to
    each element in a list or sequence
  * "stack(BasicList)" -- see stack, -- join nets or string
    vertically
  * "toList(BasicList)" -- see toList, -- create a list
  * "toSequence(BasicList)" -- see toSequence, -- convert to
    sequence

For the programmer
==================

The object BasicList, is a type, with ancestor
class Thing.

BasicList # ZZ -- get value from list, hash table, database, or string
**********************************************************************

Synopsis
========

  * Operator: #,
  * Usage:
        x#i
  * Inputs:
      * x, a list, hash table, or string
      * i, an index or key

Description
===========

If x is a list, x#i returns the ith element of x. The entries of the list are
numbered starting with 0. If i is negative, then the entries are numbered
ending with -1. If i is out of range, an error is signaled.

+-------------------------+
|i1 : L = {a, b, c, b, a};|
+-------------------------+
|i2 : L#2                 |
|                         |
|o2 = c                   |
|                         |
|o2 : Symbol              |
+-------------------------+
|i3 : L#-2                |
|                         |
|o3 = b                   |
|                         |
|o3 : Symbol              |
+-------------------------+

If x is a hash table or database, x#i provides the value associated with the
key i.

+-----------------------------------------------------------+
|i4 : T = new HashTable from {a => 103, b => 89.4, c => 92};|
+-----------------------------------------------------------+
|i5 : T#a                                                   |
|                                                           |
|o5 = 103                                                   |
+-----------------------------------------------------------+
|i6 : T#b                                                   |
|                                                           |
|o6 = 89.40000000000001                                     |
|                                                           |
|o6 : RR (of precision 53)                                  |
+-----------------------------------------------------------+

If x is a string, x#i provides the ith character of x, if there is one.
Negative indices are counted backward from the end, as with lists. If i is out
of range, an error is thrown.

+----------------------------------------------------+
|i7 : s = "a perfectly adequate example of a string";|
+----------------------------------------------------+
|i8 : s#2                                            |
|                                                    |
|o8 = p                                              |
+----------------------------------------------------+
|i9 : s#-2                                           |
|                                                    |
|o9 = n                                              |
+----------------------------------------------------+

Assignment to x#i can change x if x is mutable.

+--------------------------------------+
|i10 : V = new MutableHashTable from T;|
+--------------------------------------+
|i11 : V#a = 5;                        |
+--------------------------------------+
|i12 : V#d = 22.3;                     |
+--------------------------------------+
|i13 : peek V                          |
|                                      |
|o13 = MutableHashTable{a => 5   }     |
|                       b => 89.4      |
|                       c => 92        |
|                       d => 22.3      |
+--------------------------------------+

See also
========

  * # -- length or access to elements
  * #? -- check existence of value in a list, hash table, database,
    or string
  * # BasicList -- length or cardinality
  * VisibleList _ ZZ -- get element from list
  * hash tables
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use this method:
========================

  * BasicList # ZZ -- get value from list, hash table,
    database, or string
  * "Database # String"
  * "HashTable # Thing"
  * "String # ZZ"

BeforePrint -- top level method applied before printing results
***************************************************************

Synopsis
========

  * Usage:
        X#{topLevelMode,BeforePrint} = f
  * Inputs:
      * f, a function to be applied before printing a top-level evaluation
        result r of type X.
  * Consequences:
      * The value returned by f is printed instead.

For the programmer
==================

The object BeforePrint, is a symbol.

benchmark -- accurate timing of execution
*****************************************

Synopsis
========

  * Usage:
        benchmark s
  * Inputs:
      * s, a string, a string containing Macaulay2 code
  * Outputs:
      * a real number, the number of seconds it takes to evaluate
        the code in s

Description
===========

Produces an accurate timing for the code contained in the string s.  The value
returned is the number of seconds.
+------------------------------+
|i1 : benchmark "sqrt 2p100000"|
|                              |
|o1 = .0002652828116841144     |
|                              |
|o1 : RR (of precision 53)     |
+------------------------------+
The snippet of code provided will be run enough times to register meaningfully
on the clock, and the garbage collector will be called beforehand.

For the programmer
==================

The object benchmark, is a function closure.

BesselJ -- Bessel function of the first kind
********************************************

Synopsis
========

  * Usage:
        BesselJ(n,x)
        BesselJ_n x
  * Inputs:
      * n, an integer, the order
      * x, an integer, a rational number, or a real number,
  * Outputs:
      * the Bessel function of the first kind of order n at x

Description
===========

+------------------------------------------------------------------+
|i1 : BesselJ_0 .5                                                 |
|                                                                  |
|o1 = .9384698072408129                                            |
|                                                                  |
|o1 : RR (of precision 53)                                         |
+------------------------------------------------------------------+
|i2 : BesselJ_2 3p200                                              |
|                                                                  |
|o2 = .486091260585891076907831094114984034801662265643298727377034|
|                                                                  |
|o2 : RR (of precision 200)                                        |
+------------------------------------------------------------------+

See Bessel function (see https://en.wikipedia.org/wiki/Bessel_function ).

See also
========

  * BesselY -- Bessel function of the second kind

Ways to use BesselJ:
====================

  * "BesselJ(Number,Number)"
  * "BesselJ(ZZ,Number)"

For the programmer
==================

The object BesselJ, is a method function.

BesselY -- Bessel function of the second kind
*********************************************

Synopsis
========

  * Usage:
        BesselY(n,x)
        BesselY_n x
  * Inputs:
      * n, an integer, the order
      * x, an integer, a rational number, or a real number,
  * Outputs:
      * the Bessel function of the second kind of order n at x

Description
===========

+--------------------------------------------------------------------+
|i1 : BesselY_0 .5                                                   |
|                                                                    |
|o1 = -.4445187335067066                                             |
|                                                                    |
|o1 : RR (of precision 53)                                           |
+--------------------------------------------------------------------+
|i2 : BesselY_2 3p200                                                |
|                                                                    |
|o2 = -.1604003934849237296757682995379809181040120401743782209819082|
|                                                                    |
|o2 : RR (of precision 200)                                          |
+--------------------------------------------------------------------+

See Bessel function (see https://en.wikipedia.org/wiki/Bessel_function ).

See also
========

  * BesselJ -- Bessel function of the first kind

Ways to use BesselY:
====================

  * "BesselY(Number,Number)"
  * "BesselY(ZZ,Number)"

For the programmer
==================

The object BesselY, is a method function.

Beta -- Beta function
*********************

Synopsis
========

  * Usage:
        Beta(x, y)
  * Inputs:
      * x, a real number,
      * y, a real number,
  * Outputs:
      * a real number, the beta function of x and y;

Description
===========

This is the beta function (see https://en.wikipedia.org/wiki/beta_function )
\(B(x,y) = \int_0^1 t^{x - 1}(1 - t)^{y - 1}\,dt\).

+-------------------------+
|i1 : Beta(3, 4)          |
|                         |
|o1 = .01666666666666667  |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See also
========

  * regularizedBeta -- regularized beta function
  * inverseRegularizedBeta -- inverse of the
    regularized beta function

Ways to use Beta:
=================

  * "Beta(CC,CC)"
  * "Beta(CC,RR)"
  * "Beta(RR,CC)"
  * "Beta(RR,RR)"
  * "Beta(RR,RRi)"
  * "Beta(RRi,RR)"
  * "Beta(RRi,RRi)"

For the programmer
==================

The object Beta, is a method function.

between -- insert something between elements of a list
******************************************************

Ways to use between:
====================

  * between(Thing,VisibleList), --
    insert something between elements of a list

For the programmer
==================

The object between, is a method function.

between(Thing,VisibleList) -- insert something between elements of a list
*************************************************************************

Synopsis
========

  * Function: between,
  * Usage:
        between(m,v)
  * Inputs:
      * a thing,
      * a visible list,
  * Outputs:
      * a list,

Description
===========

Inserts m between each pair of elements of the list or sequence v, returning a
list.
+-------------------------------------------------+
|i1 : between(55,{a,b,c,d})                       |
|                                                 |
|o1 = {a, 55, b, 55, c, 55, d}                    |
|                                                 |
|o1 : List                                        |
+-------------------------------------------------+
|i2 : concatenate between(",", (1..10) / toString)|
|                                                 |
|o2 = 1,2,3,4,5,6,7,8,9,10                        |
+-------------------------------------------------+

Ways to use this method:
========================

  * between(Thing,VisibleList), --
    insert something between elements of a list

BinaryOperation -- the class of all binary operation expressions
****************************************************************

Description
===========

BinaryOperation is a type of Expression, representing the
result of a binary operation.

For the programmer
==================

The object BinaryOperation, is a header type,
with ancestor classes Expression, <
BasicList < Thing.

binomial -- binomial coefficient
********************************

Synopsis
========

  * Usage:
        binomial(n,k)
  * Inputs:
      * n, an integer, or a ring element,
      * k, an integer, must be non-negative;
  * Outputs:
      * a number, the binomial coefficient, the coefficient of
        $x^k$ in $(1+x)^n$ or $n(n-1)...(n-k+1)/k!$.

Description
===========

+-------------------+
|i1 : binomial(13,6)|
|                   |
|o1 = 1716          |
+-------------------+
|i2 : binomial(-1,3)|
|                   |
|o2 = -1            |
+-------------------+

When either n or k are not ZZ, objects, the Gamma,
function is used, i.e., $\binom{n}{k} = \frac{\Gamma(n + 1)}{\Gamma(k +
1)\Gamma(n - k + 1)}$.

+-------------------------+
|i3 : binomial(7.5, pi)   |
|                         |
|o3 = 46.76478688243245   |
|                         |
|o3 : RR (of precision 53)|
+-------------------------+

A polynomial may also be used for n.

+-----------------------+
|i4 : R = QQ[x]         |
|                       |
|o4 = R                 |
|                       |
|o4 : PolynomialRing    |
+-----------------------+
|i5 : binomial(x + 3, 3)|
|                       |
|     1 3    2   11     |
|o5 = -x  + x  + --x + 1|
|     6           6     |
|                       |
|o5 : R                 |
+-----------------------+

Ways to use binomial:
=====================

  * "binomial(Number,Number)"
  * "binomial(RingElement,ZZ)"
  * "binomial(ZZ,ZZ)"

For the programmer
==================

The object binomial, is a method function.

blockMatrixForm -- global flag for block printing
*************************************************

Synopsis
========

  * Usage:
        blockMatrixForm = x
  * Consequences:
      * changes the display of matrices

Description
===========

blockMatrixForm is a global flag that specifies whether to display blocks in
matrices.

The default value is false.
+-----------------------------+
|i1 : M = ZZ^1 ++ ZZ^2 ++ ZZ^3|
|                             |
|       6                     |
|o1 = ZZ                      |
|                             |
|o1 : ZZ-module, free         |
+-----------------------------+
|i2 : f = random(M,M)         |
|                             |
|o2 = | 8 3 8 6 6 2 |         |
|     | 1 7 5 8 9 6 |         |
|     | 3 8 2 6 6 9 |         |
|     | 7 8 3 9 2 3 |         |
|     | 8 5 6 3 6 5 |         |
|     | 3 7 3 7 0 6 |         |
|                             |
|              6       6      |
|o2 : Matrix ZZ  <-- ZZ       |
+-----------------------------+
|i3 : blockMatrixForm = true; |
+-----------------------------+
|i4 : f                       |
|                             |
|o4 = | 8 | 3 8 | 6 6 2 |     |
|     +---+-----+-------+     |
|     | 1 | 7 5 | 8 9 6 |     |
|     | 3 | 8 2 | 6 6 9 |     |
|     +---+-----+-------+     |
|     | 7 | 8 3 | 9 2 3 |     |
|     | 8 | 5 6 | 3 6 5 |     |
|     | 3 | 7 3 | 7 0 6 |     |
|                             |
|              6       6      |
|o4 : Matrix ZZ  <-- ZZ       |
+-----------------------------+

For the programmer
==================

The object blockMatrixForm, is a Boolean value.

Boolean -- the class of Boolean values
**************************************

Description
===========

Predicate functions return these as values, and the logical connectives expect
to receive them as arguments.

Special operators dealing with truth values.
  * not -- negation
  * and -- conjunction
  * or -- disjunction
  * xor -- exclusive disjunction
  * if -- condition testing

Functions and methods returning a Boolean value:
================================================

  * "BasicList #? ZZ" -- see #?, -- check existence of value in a
    list, hash table, database, or string
  * "Database #? String" -- see #?, -- check existence of value in a
    list, hash table, database, or string
  * "HashTable #? Thing" -- see #?, -- check existence of value in a
    list, hash table, database, or string
  * "String #? ZZ" -- see #?, -- check existence of value in a list,
    hash table, database, or string
  * "Thing =!= Thing" -- see =!=, -- strict inequality
  * ? -- comparison operator
  * all -- whether all elements satisfy a specified condition
  * ancestor(Type,Type) -- whether one type
    is an ancestor of another
  * any(BasicList,BasicList,Function)
    -- whether any corresponding
    elements of a pair of lists satisfy a condition
  * any(BasicList,Function) -- whether
    any elements of a list satisfy a specified condition
  * "any(ZZ,Function)" -- see any(BasicList,Function),
    -- whether any elements of a list satisfy a
    specified condition
  * any(HashTable,Function) -- whether
    all key/value pairs in a hash table satisfy a specified condition
  * atEndOfFile(File) -- test for end of file
  * BettiTally == BettiTally (missing documentation)
  * Boolean == Boolean (missing documentation)
  * CC == CC (missing documentation)
  * CC == QQ (missing documentation)
  * CC == RR (missing documentation)
  * CC == ZZ (missing documentation)
  * CoherentSheaf == CoherentSheaf (missing documentation)
  * CoherentSheaf == ZZ (missing documentation)
  * commonFace (Polyhedra) -- checks if the intersection is a
    face of both Cones or Polyhedra, or of cones with fans
  * contains (Polyhedra) -- checks if the first argument
    contains the second argument
  * Dictionary #? String (missing documentation)
  * "fileExecutable(String)" -- see fileExecutable,
  * "fileReadable(String)" -- see fileReadable,
  * "fileWritable(String)" -- see fileWritable,
  * inducesWellDefinedMap -- whether a map is
    well defined
  * inInterior (Polyhedra) -- checks if a point lies in the
    relative interior of a Cone/Polyhedron
  * "instance(Thing,Type)" -- see instance, -- whether
    something has a certain type
  * isAffineRing -- whether something is an affine ring
  * "isANumber(Number)" -- see isANumber, -- whether a number
    is not not-a-number
  * isBorel -- whether an ideal is fixed by upper triangular
    changes of coordinates
  * "isBorel(MonomialIdeal)" -- see isBorel, -- whether an ideal
    is fixed by upper triangular changes of coordinates
  * isCanceled(Task) -- whether a task has been
    canceled
  * isCommutative -- whether a ring is commutative
  * isCommutative(ChainComplexMap) (missing documentation)
  * isCompact (Polyhedra) -- checks compactness of a
    Polyhedron
  * isComplete (Polyhedra) -- checks completeness of a Fan or
    PolyhedralComplex
  * isConstant -- whether a ring element is constant
  * isEmpty
  * isEmpty(RRi) -- empty test for an interval
  * isFace (Polyhedra) -- tests if the first argument is a face
    of the second
  * isField -- whether something is a field
  * "isField(Ring)" -- see isField, -- whether something is a
    field
  * isFreeModule -- whether something is a free module
  * isFullDimensional (Polyhedra) -- Determine whether
    a polyhedral object is full-dimensional
  * isHomogeneous -- whether something is homogeneous
    (graded)
  * "isHomogeneous(Module)" -- see isHomogeneous, --
    whether something is homogeneous (graded)
  * isIdeal -- whether something is an ideal
  * isInjective -- whether a map is injective
  * isInputFile(File) -- whether a file is open
    for input
  * isIsomorphism -- whether a map is an isomorphism
  * isIsomorphism(SheafMap) (missing documentation)
  * "isLatticePolytope(Polyhedron)" -- see isLatticePolytope (Polyhedra),
    -- checks if a polyhedron is a lattice
    polytope
  * isLinearType (ReesAlgebra) -- Determine whether module
    has linear type
  * isListener(File) -- whether a file is open for
    listening
  * "isMember(Thing,Set)" -- see isMember, -- test membership
    in a list or set
  * "isMember(Thing,VisibleList)" -- see isMember, -- test
    membership in a list or set
  * isModule -- whether something is a module
  * isMonomialIdeal -- whether something is a monomial
    ideal
  * "isMutable(Thing)" -- see isMutable, -- whether something
    may be modified
  * isNormal(Ring) (IntegralClosure) -- determine if
    a reduced ring is normal
  * "isOpen(Database)" -- see isOpen, -- whether a file or
    database is open
  * "isOpen(File)" -- see isOpen, -- whether a file or database
    is open
  * isOutputFile(File) -- whether a file is open
    for output
  * isPointed (Polyhedra) -- checks if a Cone or Fan is
    pointed
  * isPolynomialRing -- whether something is a
    polynomial ring
  * isPolytopal (Polyhedra) -- checks if a Fan is polytopal
  * isPrime -- whether a integer or polynomial is prime
  * "isPrime(ZZ)" -- see isPrime, -- whether a integer or
    polynomial is prime
  * isPrime(Ideal) (MinimalPrimes) -- whether an
    ideal is prime
  * isProjective (missing documentation)
  * "isPseudoprime" -- see isPseudoprime(ZZ), --
    whether an integer is probably prime
  * isPseudoprime(ZZ) -- whether an integer is
    probably prime
  * isPure (Polyhedra) -- checks if a Fan or PolyhedralComplex is
    of pure dimension
  * isQuotientModule -- whether something is evidently
    a quotient of a free module
  * isQuotientOf -- whether one thing is a quotient of
    another
  * isQuotientRing -- whether something is a quotient
    ring
  * isReady(File) -- whether a file has data
    available for reading
  * isReady(Task) -- whether a task is finished
  * isReduction (ReesAlgebra) -- Determine whether an ideal
    is a reduction
  * isReflexive (Polyhedra) --  checks if a Polytope is
    reflexive
  * isRing -- whether something is a ring
  * isSimplicial (Polyhedra) --  checks if a polyhedral
    object is simplicial
  * isSkewCommutative -- whether a ring has skew
    commuting variables
  * isSmooth
  * isSquareFree -- whether something is square free
    monomial ideal
  * isSubmodule -- whether a module is evidently a
    submodule of a free module
  * isSubset -- whether one object is a subset of another
  * isSubset(Set,Set) -- whether one object is
    a subset of another
  * "isSubset(Set,VisibleList)" -- see isSubset(Set,Set),
    -- whether one object is a subset of another
  * "isSubset(VisibleList,Set)" -- see isSubset(Set,Set),
    -- whether one object is a subset of another
  * "isSubset(VisibleList,VisibleList)" -- see isSubset(Set,Set),
    -- whether one object is a subset of another
  * isSurjective -- whether a map is surjective
  * isUnit -- whether a ring element is a unit
  * isVeryAmple
  * isWellDefined -- whether a map is well defined
  * liftable -- whether lifting to another ring is possible
  * List #? ZZ (missing documentation)
  * match -- regular expression matching
  * Net #? ZZ (missing documentation)
  * Net == Net (missing documentation)
  * Nothing #? Thing (missing documentation)
  * Nothing == Nothing (missing documentation)
  * ProjectiveHilbertPolynomial == ProjectiveHilbertPolynomial (missing
    documentation)
  * ProjectiveHilbertPolynomial == ZZ (missing documentation)
  * QQ == CC (missing documentation)
  * QQ == QQ (missing documentation)
  * QQ == RR (missing documentation)
  * QQ == RRi (missing documentation)
  * QQ == ZZ (missing documentation)
  * radicalContainment (MinimalPrimes) -- whether an
    element is contained in the radical of an ideal
  * "radicalContainment(Ideal,Ideal)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * "radicalContainment(RingElement,Ideal)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * RR == CC (missing documentation)
  * RR == QQ (missing documentation)
  * RR == RR (missing documentation)
  * RR == RRi (missing documentation)
  * RR == ZZ (missing documentation)
  * RRi == QQ (missing documentation)
  * RRi == RR (missing documentation)
  * RRi == RRi (missing documentation)
  * RRi == ZZ (missing documentation)
  * Sequence #? ZZ (missing documentation)
  * Sequence == Sequence (missing documentation)
  * Set #? Thing -- test set membership
  * SheafMap == ZZ (missing documentation)
  * String == String (missing documentation)
  * Symbol == Symbol (missing documentation)
  * "testHunekeQuestion(RingElement)" -- see testHunekeQuestion (IntegralClosure),
    -- tests a conjecture on integral
    closures strengthening the Eisenbud-Mazur conjecture
  * Thing === Thing -- strict equality
  * "isWeylAlgebra" -- see Weyl algebras,
  * ZZ == CC (missing documentation)
  * ZZ == CoherentSheaf (missing documentation)
  * ZZ == ProjectiveHilbertPolynomial (missing documentation)
  * ZZ == QQ (missing documentation)
  * ZZ == RR (missing documentation)
  * ZZ == RRi (missing documentation)
  * ZZ == SheafMap (missing documentation)
  * ZZ == ZZ (missing documentation)

Methods that use a Boolean value:
=================================

  * "Boolean >> Function" -- see OptionTable >> Function,
    -- attaching options to a function
  * "Boolean xor Boolean" -- see xor, -- exclusive disjunction

Protected objects of class Boolean:
===================================

  * false
  * true

For the programmer
==================

The object Boolean, is a type, with ancestor class
Thing.

borel(Matrix) -- make a Borel fixed submodule
*********************************************

Synopsis
========

  * Function: borel,

Description
===========

borel m -- make a Borel fixed submodule

Yields the matrix with the same target as the matrix m, whose columns generate
the smallest Borel fixed submodule containing the lead monomials of the columns
of m.  If m is a monomial ideal, then the minimal Borel fixed monomial ideal
containing it is returned.

For example, if R = ZZ/101[a..f], then
+-------------------------------------+
|i1 : R = ZZ/101[a..e]                |
|                                     |
|o1 = R                               |
|                                     |
|o1 : PolynomialRing                  |
+-------------------------------------+
|i2 : borel matrix {{a*d*e, b^2}}     |
|                                     |
|o2 = | a2 ab b2 ac2 acd ad2 ace ade ||
|                                     |
|             1      8                |
|o2 : Matrix R  <-- R                 |
+-------------------------------------+

Ways to use this method:
========================

  * borel(Matrix) -- make a Borel fixed submodule
  * "borel(MonomialIdeal)"

break -- break from a loop
**************************

Synopsis
========

  * Usage:
        break x
  * Consequences:
      * this interrupts execution of a loop controlled by for,
        while, apply, or scan,
        returning x as the value of the loop currently being evaluated.
      * Alternatively, as a top level command in the debugger, it leaves the
        debugger, returning the user to top level.

Description
===========

Omitting x, and executing break, interrupts execution of a loop as above,
returning null, as the value of the function currently being
evaluated, except, in the case of a for, loop or a while,
loop with a list clause, the list accumulated so far is returned as the
value.

+-----------------------------------------------------+
|i1 : for i from 1 to 10 do if i == 7 then break 12345|
|                                                     |
|o1 = 12345                                           |
+-----------------------------------------------------+

Warning: trying to break from a loop controlled by table, will
probably not do what you expect, since table, is implemented by
two nested loops controlled by apply, and only the inner one will
stop, as in the following example.

+---------------------------------------------------------+
|i2 : table(3,3,(i,j) -> if i == 1 then break 3 else "hi")|
|                                                         |
|o2 = {{hi, hi, hi}, 3, {hi, hi, hi}}                     |
|                                                         |
|o2 : List                                                |
+---------------------------------------------------------+
|i3 : table(3,3,(i,j) -> if j == 1 then break 3 else "hi")|
|                                                         |
|o3 = {3, 3, 3}                                           |
|                                                         |
|o3 : List                                                |
+---------------------------------------------------------+

Here is an example as a debugger command.

+-----------------------------------------------------------------------------+
|i4 : load "Macaulay2Doc/demo1.m2"                                            |
+-----------------------------------------------------------------------------+
|i5 : g 2                                                                     |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|8:10-8:13: --source code:                                                    |
|     b := 1/x;                                                               |
|-----------------------------------------------------------------------------|
|error: division by zero                                                      |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
|ii6 : x                                                                      |
|                                                                             |
|oo6 = 0                                                                      |
+-----------------------------------------------------------------------------+
|ii7 : break                                                                  |
+-----------------------------------------------------------------------------+
|i8 : g 3                                                                     |
|                                                                             |
|     7                                                                       |
|o8 = -                                                                       |
|     2                                                                       |
|                                                                             |
|o8 : QQ                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * apply -- apply a function to each element
  * scan -- apply a function to each element in a list or sequence
  * while -- while loops
  * for -- for loops

For the programmer
==================

The object break, is a keyword.

cache -- a key under which to store cache tables
************************************************

Description
===========

+------------------------------------------------------------------------+
|i1 : F = ZZ^3                                                           |
|                                                                        |
|       3                                                                |
|o1 = ZZ                                                                 |
|                                                                        |
|o1 : ZZ-module, free                                                    |
+------------------------------------------------------------------------+
|i2 : peek F                                                             |
|                                                                        |
|o2 = Module of Vector{cache => CacheTable{...2...}                     }|
|                      numgens => 3                                      |
|                      RawFreeModule => free(rank 3 degrees = {1, 1, 1}) |
|                      ring => ZZ                                        |
+------------------------------------------------------------------------+
|i3 : F.cache#Foo = Bar                                                  |
|                                                                        |
|o3 = Bar                                                                |
|                                                                        |
|o3 : Symbol                                                             |
+------------------------------------------------------------------------+
|i4 : peek F                                                             |
|                                                                        |
|o4 = Module of Vector{cache => CacheTable{...3...}                     }|
|                      numgens => 3                                      |
|                      RawFreeModule => free(rank 3 degrees = {1, 1, 1}) |
|                      ring => ZZ                                        |
+------------------------------------------------------------------------+
|i5 : peek F.cache                                                       |
|                                                                        |
|o5 = CacheTable{cache => MutableHashTable{}}                            |
|                Foo => Bar                                              |
|                rank => 3                                               |
+------------------------------------------------------------------------+
|i6 : F === ZZ^3                                                         |
|                                                                        |
|o6 = true                                                               |
+------------------------------------------------------------------------+

See also
========

  * CacheTable -- hash tables for caching

For the programmer
==================

The object cache, is a symbol.

CacheFunction -- the class of cache functions
*********************************************

Description
===========

Functions of class CacheFunction, are created and used by
cacheValue, and by stashValue.

For the programmer
==================

The object CacheFunction, is a type, with
ancestor classes FunctionClosure, < Function
< Thing.

CacheTable -- hash tables for caching
*************************************

Description
===========

A type of mutable hash table designed for caching computed values that could
always be recomputed.  Cache tables are designed so their contents will not
participate in any comparisons by the strict comparison operator ===.  To that
end, any two cache tables with the same class and parent are considered equal
to each other and have hash code equal to 0.

For the programmer
==================

The object CacheTable, is a type, with ancestor
classes MutableHashTable, < HashTable
< Thing.

cacheValue -- cache values of functions in their arguments
**********************************************************

Synopsis
========

  * Usage:
        ((cacheValue KEY) f) x
  * Inputs:
      * KEY
      * f, a function,
      * x, an argument for f that has a cache table, stored
        in it under x.cache
  * Outputs:
      * f x is returned, but the value is saved in x.cache#KEY and not
        recomputed later. However, if the value found in x.cache#KEY is an
        a cache function, such as is returned by
        (stashValue KEY) f, then the value of x.cache#KEY x is returned
        instead, after first removing x.cache#KEY from x.cache.

Description
===========

+--------------------------------------------------------------------+
|i1 : x = new HashTable from { val => 1000, cache => new CacheTable }|
|                                                                    |
|o1 = HashTable{cache => CacheTable{}}                               |
|               val => 1000                                          |
|                                                                    |
|o1 : HashTable                                                      |
+--------------------------------------------------------------------+
|i2 : f = (t -> (print "hi there"; t.val^4))                         |
|                                                                    |
|o2 = f                                                              |
|                                                                    |
|o2 : FunctionClosure                                                |
+--------------------------------------------------------------------+
|i3 : h = (cacheValue VALUE) f                                       |
|                                                                    |
|o3 = -*a cache function*-                                           |
|                                                                    |
|o3 : CacheFunction                                                  |
+--------------------------------------------------------------------+
|i4 : h x                                                            |
|hi there                                                            |
|                                                                    |
|o4 = 1000000000000                                                  |
+--------------------------------------------------------------------+
|i5 : h x                                                            |
|                                                                    |
|o5 = 1000000000000                                                  |
+--------------------------------------------------------------------+
|i6 : peek'_2 x                                                      |
|                                                                    |
|o6 = HashTable{cache => CacheTable{VALUE => 1000000000000}}         |
|               val => 1000                                          |
+--------------------------------------------------------------------+

Code
====

../../../../../Macaulay2/m2/methods.m2:685:13-694:28: --source code:
cacheValue = key -> f -> new CacheFunction from (x -> (
          c := try x.cache else x.cache = new CacheTable;
          if c#?key then (
               val := c#key;
               if class val === CacheFunction then (
                    remove(c,key);
                    c#key = val x)
               else val
               )
          else c#key = f x))

See also
========

  * stashValue -- stash values of functions in their
    arguments

For the programmer
==================

The object cacheValue, is a function closure.

CatalanConstant -- Catalan's constant
*************************************

Synopsis
========

  * Usage:
        CatalanConstant
  * Outputs:
      * a real number, Catalan's constant, converted to a numeric
        value of the correct precision, when necessary.

Description
===========

+-------------------------------------+
|i1 : CatalanConstant                 |
|                                     |
|o1 = CatalanConstant                 |
|                                     |
|o1 : Constant                        |
+-------------------------------------+
|i2 : numeric_100 CatalanConstant     |
|                                     |
|o2 = .9159655941772190150546035149325|
|                                     |
|o2 : RR (of precision 100)           |
+-------------------------------------+

See Catalan's constant (see https://en.wikipedia.org/wiki/Catalan's_constant ).

For the programmer
==================

The object CatalanConstant, is an instance of the type
Constant.

CC -- the class of all complex numbers
**************************************

Description
===========

In Macaulay2, complex numbers are represented as floating point numbers, and so
are only approximate.  The symbol ii, represents the square root of
-1 in many numeric contexts.  A complex number is obtained by using the
symbolic constant ii, or the conversion functions toCC,
and numeric, in combination with real numbers (see RR).
It is stored internally as a pair of arbitrary precision floating point
real numbers, using the MPFR, library.
+--------------------------------------------+
|i1 : z = 3-4*ii                             |
|                                            |
|o1 = 3-4*ii                                 |
|                                            |
|o1 : CC (of precision 53)                   |
+--------------------------------------------+
|i2 : z^5                                    |
|                                            |
|o2 = -237.0000000000017+3115.999999999999*ii|
|                                            |
|o2 : CC (of precision 53)                   |
+--------------------------------------------+
|i3 : 1/z                                    |
|                                            |
|o3 = .12+.16*ii                             |
|                                            |
|o3 : CC (of precision 53)                   |
+--------------------------------------------+
|i4 : +ii                                    |
|                                            |
|o4 = ii                                     |
|                                            |
|o4 : CC (of precision 53)                   |
+--------------------------------------------+
|i5 : numeric_200 ii                         |
|                                            |
|o5 = ii                                     |
|                                            |
|o5 : CC (of precision 200)                  |
+--------------------------------------------+
Complex numbers are ordered lexicographically, mingled with real numbers.
+-------------------------------------------+
|i6 : sort {1+ii,2+ii,1-ii,2-ii,1/2,2.1,7/5}|
|                                           |
|      1              7                     |
|o6 = {-, 1-ii, 1+ii, -, 2-ii, 2+ii, 2.1}   |
|      2              5                     |
|                                           |
|o6 : List                                  |
+-------------------------------------------+
The precision is measured in bits, is visible in the ring displayed on the
second of each pair of output lines, and can be recovered using
precision.
+----------------+
|i7 : precision z|
|                |
|o7 = 53         |
+----------------+
For complex numbers, the functions class, and ring,
yield different results.  That allows numbers of various precisions to be used
without creating a new ring for each precision.
+-----------------------+
|i8 : class z           |
|                       |
|o8 = CC                |
|                       |
|o8 : InexactFieldFamily|
+-----------------------+
|i9 : ring z            |
|                       |
|o9 = CC                |
|       53              |
|                       |
|o9 : ComplexField      |
+-----------------------+
A computation involving numbers of different precisions has a result with the
minimal precision occurring. Numbers that appear alone on an output line are
displayed with all their meaningful digits. (Specifying 100 bits of precision
yields about 30 decimal digits of precision.)
+--------------------------+
|i10 : 3p100+2p90e3*ii     |
|                          |
|o10 = 3+2000*ii           |
|                          |
|o10 : CC (of precision 90)|
+--------------------------+
Numbers displayed inside more complicated objects are printed with the number
of digits specified by printingPrecision.
+------------------------------+
|i11 : printingPrecision       |
|                              |
|o11 = 6                       |
+------------------------------+
|i12 : x = {1/3.*ii,1/3p100*ii}|
|                              |
|o12 = {.333333*ii, .333333*ii}|
|                              |
|o12 : List                    |
+------------------------------+
Use toExternalString, to produce something that, when
encountered as input, will reproduce exactly what you had before.
+----------------------------------------------------+
|i13 : y = toExternalString x                        |
|                                                    |
|o13 = {toCC(.0p53,.33333333333333331p53),toCC(.0p100|
|      ,.33333333333333333333333333333346p100)}      |
+----------------------------------------------------+
|i14 : value y === x                                 |
|                                                    |
|o14 = true                                          |
+----------------------------------------------------+

Caveat
======

Currently, most transcendental functions are not implemented for complex
arguments.

See also
========

  * ii -- the square root of -1
  * toCC -- convert to high-precision complex number
  * toRR -- convert to high-precision real number
  * numeric -- convert to floating point
  * precision
  * format -- format a string or a real number
  * printingPrecision -- current precision for
    printing numbers
  * printingAccuracy -- current accuracy for printing
    numbers
  * printingLeadLimit -- maximum number of leading
    zeroes to use when printing real numbers
  * printingTrailLimit -- maximum number of
    additional trailing digits to use when printing real numbers
  * printingSeparator -- string used to separate
    mantissa from exponent when printing real numbers

Functions and methods returning a complex number:
=================================================

  * "CC * CC" -- see *, -- a binary operator, usually used for
    multiplication
  * "CC * QQ" -- see *, -- a binary operator, usually used for
    multiplication
  * "CC * RR" -- see *, -- a binary operator, usually used for
    multiplication
  * "CC * ZZ" -- see *, -- a binary operator, usually used for
    multiplication
  * "QQ * CC" -- see *, -- a binary operator, usually used for
    multiplication
  * "RR * CC" -- see *, -- a binary operator, usually used for
    multiplication
  * "ZZ * CC" -- see *, -- a binary operator, usually used for
    multiplication
  * "+ CC" -- see +, -- a unary or binary operator, usually used for
    addition
  * "CC + CC" -- see +, -- a unary or binary operator, usually used
    for addition
  * "CC + QQ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "CC + RR" -- see +, -- a unary or binary operator, usually used
    for addition
  * "CC + ZZ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "QQ + CC" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RR + CC" -- see +, -- a unary or binary operator, usually used
    for addition
  * "ZZ + CC" -- see +, -- a unary or binary operator, usually used
    for addition
  * "- CC" -- see -, -- a unary or binary operator, usually used for
    negation or subtraction
  * "CC - CC" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "CC - QQ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "CC - RR" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "CC - ZZ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "QQ - CC" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RR - CC" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "ZZ - CC" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "CC / CC" -- see /, -- a binary operator, usually used for
    division
  * "CC / QQ" -- see /, -- a binary operator, usually used for
    division
  * "CC / RR" -- see /, -- a binary operator, usually used for
    division
  * "CC / ZZ" -- see /, -- a binary operator, usually used for
    division
  * "QQ / CC" -- see /, -- a binary operator, usually used for
    division
  * "RR / CC" -- see /, -- a binary operator, usually used for
    division
  * "ZZ / CC" -- see /, -- a binary operator, usually used for
    division
  * "acos(CC)" -- see acos, -- arccosine
  * "agm(CC,CC)" -- see agm, -- arithmetic-geometric mean
  * "agm(CC,RR)" -- see agm, -- arithmetic-geometric mean
  * "agm(RR,CC)" -- see agm, -- arithmetic-geometric mean
  * "asin(CC)" -- see asin, -- arcsine
  * "atan(CC)" -- see atan, -- compute the arctangent of a number
  * "Beta(CC,CC)" -- see Beta, -- Beta function
  * "Beta(CC,RR)" -- see Beta, -- Beta function
  * "Beta(RR,CC)" -- see Beta, -- Beta function
  * "cos(CC)" -- see cos, -- compute the cosine
  * "cosh(CC)" -- see cosh, -- compute the hyperbolic cosine
  * "cot(CC)" -- see cot, -- cotangent
  * "coth(CC)" -- see coth, -- hyperbolic cotangent
  * "csc(CC)" -- see csc, -- cosecant
  * "csch(CC)" -- see csch, -- hyperbolic cosecant
  * "Digamma(CC)" -- see Digamma, -- Digamma function
  * "eint(CC)" -- see eint, -- exponential integral
  * "erf(CC)" -- see erf, -- error function
  * "erfc(CC)" -- see erfc, -- complementary error function
  * "exp(CC)" -- see exp, -- exponential function
  * "expm1(CC)" -- see expm1, -- exponential minus 1
  * "Gamma(CC)" -- see Gamma, -- Gamma function
  * "Gamma(CC,CC)" -- see Gamma, -- Gamma function
  * "Gamma(CC,RR)" -- see Gamma, -- Gamma function
  * "Gamma(RR,CC)" -- see Gamma, -- Gamma function
  * "log(CC)" -- see log, -- logarithm function
  * "log(RR,CC)" -- see log, -- logarithm function
  * "log(RR,RR)" -- see log, -- logarithm function
  * "log1p(CC)" -- see log1p, -- logarithm of 1+x
  * "regularizedBeta(CC,CC,CC)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(CC,CC,RR)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(CC,RR,CC)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(CC,RR,RR)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RR,CC,CC)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RR,CC,RR)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RR,RR,CC)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedGamma(CC,CC)" -- see regularizedGamma,
    -- upper regularized gamma function
  * "regularizedGamma(CC,RR)" -- see regularizedGamma,
    -- upper regularized gamma function
  * "regularizedGamma(RR,CC)" -- see regularizedGamma,
    -- upper regularized gamma function
  * "sec(CC)" -- see sec, -- secant
  * "sech(CC)" -- see sech, -- hyperbolic secant
  * "sin(CC)" -- see sin, -- compute the sine
  * "sinh(CC)" -- see sinh, -- compute the hyperbolic sine
  * "sqrt(CC)" -- see sqrt, -- square root function
  * "sqrt(RR)" -- see sqrt, -- square root function
  * "tan(CC)" -- see tan, -- compute the tangent
  * "tanh(CC)" -- see tanh, -- compute the hyperbolic tangent
  * "toCC(CC)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(QQ)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(RR)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(RR,RR)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,CC)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,QQ)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,QQ,QQ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,QQ,RR)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,QQ,ZZ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,RR)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,RR,QQ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,RR,RR)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,RR,ZZ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,ZZ)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,ZZ,QQ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,ZZ,RR)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,ZZ,ZZ)" -- see toCC, -- convert to high-precision
    complex number
  * "zeta(CC)" -- see zeta, -- Riemann zeta function

Methods that use a complex number:
==================================

  * "CC % CC" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "CC % QQ" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "CC % RR" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "CC % ZZ" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "CC // CC" -- see //, -- a binary operator, usually used for
    quotient
  * "CC // QQ" -- see //, -- a binary operator, usually used for
    quotient
  * "CC // RR" -- see //, -- a binary operator, usually used for
    quotient
  * "CC // ZZ" -- see //, -- a binary operator, usually used for
    quotient
  * "abs(CC)" -- see abs, -- absolute value function
  * CC + InfiniteNumber (missing documentation)
  * CC - InfiniteNumber (missing documentation)
  * CC == CC (missing documentation)
  * CC == QQ (missing documentation)
  * CC == RR (missing documentation)
  * CC == ZZ (missing documentation)
  * CC ? InfiniteNumber (missing documentation)
  * "conjugate(CC)" -- see conjugate, -- complex conjugate
  * "format(CC)" -- see format, -- format a string or a real
    number
  * InfiniteNumber * CC (missing documentation)
  * InfiniteNumber + CC (missing documentation)
  * InfiniteNumber - CC (missing documentation)
  * InfiniteNumber / CC (missing documentation)
  * InfiniteNumber // CC (missing documentation)
  * InfiniteNumber ? CC (missing documentation)
  * "isReal(CC)" -- see isReal, -- whether a number is real
  * "CC << ZZ" -- see left shift,
  * "lift(CC,type of QQ)" -- see lift, -- lift to another ring
  * "lift(CC,type of RR_*)" -- see lift, -- lift to another ring
  * "lift(CC,type of ZZ)" -- see lift, -- lift to another ring
  * liftable(CC,type of RR_*) (missing documentation)
  * "lngamma(CC)" -- see lngamma, -- logarithm of the Gamma
    function
  * "numeric(CC)" -- see numeric, -- convert to floating point
  * "numeric(ZZ,CC)" -- see numeric, -- convert to floating
    point
  * QQ == CC (missing documentation)
  * "CC >> ZZ" -- see right shift,
  * "ring(CC)" -- see ring, -- get the associated ring of an object
  * "round(CC)" -- see round, -- round a number
  * RR == CC (missing documentation)
  * "size2(CC)" -- see size2, -- number of binary digits to the
    left of the point
  * ZZ == CC (missing documentation)

For the programmer
==================

The object CC, is an inexact field family,
with ancestor classes InexactNumber, < Number
< Thing.

CC' -- the parent class of all rings of complex numbers
*******************************************************

Description
===========

Floating point complex numbers are treated in a special way.  Recall first to
create a polynomial, one must first create a polynomial ring to contain it.
And then, the polynomial ring is the class of the polynomial.

+-------------------+
|i1 : R = QQ[x,y,z] |
|                   |
|o1 = R             |
|                   |
|o1 : PolynomialRing|
+-------------------+
|i2 : x^2           |
|                   |
|      2            |
|o2 = x             |
|                   |
|o2 : R             |
+-------------------+
|i3 : class x^2     |
|                   |
|o3 = R             |
|                   |
|o3 : PolynomialRing|
+-------------------+

Floating point complex numbers, however, can be created directly, as follows,
without creating a ring.

+-----------------------------------------------------------------------------+
|i4 : r = 4.5 * ii                                                            |
|                                                                             |
|o4 = 4.5*ii                                                                  |
|                                                                             |
|o4 : CC (of precision 53)                                                    |
+-----------------------------------------------------------------------------+
|i5 : s = 4.3p300 * ii                                                        |
|                                                                             |
|o5 = 4.3000000000000000000000000000000000000000000000000000000000000000000000|
|     00000000000000000002*ii                                                 |
|                                                                             |
|o5 : CC (of precision 300)                                                   |
+-----------------------------------------------------------------------------+

The floating point numbers created above have different precisions, and thus
are regarded as being elements of different rings, whose elements all have the
same precision.

+-----------------+
|i6 : precision r |
|                 |
|o6 = 53          |
+-----------------+
|i7 : precision s |
|                 |
|o7 = 300         |
+-----------------+
|i8 : ring r      |
|                 |
|o8 = CC          |
|       53        |
|                 |
|o8 : ComplexField|
+-----------------+
|i9 : ring s      |
|                 |
|o9 = CC          |
|       300       |
|                 |
|o9 : ComplexField|
+-----------------+

In order to make it convenient to define methods that apply to all such rings,
those rings have a common parent, namely CC'.  Notice that CC' is printed in a
special way.

+---------------------------+
|i10 : CC'                  |
|                           |
|o10 = CC                   |
|        *                  |
|                           |
|o10 : Type                 |
+---------------------------+
|i11 : parent ring r        |
|                           |
|o11 = CC                   |
|        *                  |
|                           |
|o11 : Type                 |
+---------------------------+
|i12 : parent ring s        |
|                           |
|o12 = CC                   |
|        *                  |
|                           |
|o12 : Type                 |
+---------------------------+
|i13 : parent ring s === CC'|
|                           |
|o13 = true                 |
+---------------------------+

Methods that use an object of class CC_*:
=========================================

  * "lift(Matrix,type of CC_*,type of QQ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of CC_*,type of RR_*)" -- see lift, -- lift
    to another ring
  * "lift(Matrix,type of CC_*,type of ZZ)" -- see lift, -- lift to
    another ring
  * lift(Matrix,type of CC_*,type of CC_*) (missing documentation)

For the programmer
==================

The object CC', is a type, with ancestor classes
InexactNumber', < Nothing < Thing.

ceiling -- ceiling function
***************************

See also
========

  * floor -- floor function

Ways to use ceiling:
====================

  * ceiling(Number) -- ceiling function

For the programmer
==================

The object ceiling, is a method function.

ceiling(Number) -- ceiling function
***********************************

Synopsis
========

  * Function: ceiling,
  * Usage:
        ceiling x
  * Inputs:
      * x
  * Outputs:
      * the least integer greater than or equal to the number x. The imaginary
        part of a complex number is ignored.

Description
===========

+------------------+
|i1 : ceiling(-3.4)|
|                  |
|o1 = -3           |
+------------------+

See also
========

  * floor(Number) -- floor function
  * truncate(Number) -- round a number toward zero

Ways to use this method:
========================

  * ceiling(Number) -- ceiling function

centerString -- center a string or net
**************************************

Synopsis
========

  * Usage:
        centerString(wid,s)
  * Inputs:
      * wid, an integer,
      * s, a net,
  * Outputs:
      * a net with spaces added, as needed, to center s in a net of width wid

Description
===========

+------------------------------------+
|i1 : centerString(18,"asdf"||"qwer")|
|                                    |
|o1 =        asdf                    |
|            qwer                    |
+------------------------------------+

For the programmer
==================

The object centerString, is a function closure.

ChainComplex -- the class of all chain complexes
************************************************

Description
===========

For an overview of creating and using chain complexes in Macaulay2, see
chain complexes.

Common ways to create a chain complex
  * chainComplex -- make a chain complex
  * resolution(Module) -- compute a free
    resolution of a module
Information about a chain complex
  * length(ChainComplex) -- length of a chain
    complex or graded module
  * min(GradedModule)
  * max(GradedModule)
  * betti(GradedModule) -- display or modify a Betti diagram
  * ring(ChainComplex) -- get the associated ring of an object
Operations on chain complexes
  * dual(ChainComplex) -- dual
  * ChainComplex ++ ChainComplex -- direct
    sum
  * ChainComplex ** Module -- tensor
    product
  * ChainComplex ** ChainComplex, --
    tensor product
  * Hom(ChainComplex,Module) -- the Hom
    functor
  * ChainComplex Array -- degree shift

Functions and methods returning a chain complex:
================================================

  * "Ring ^ BettiTally" -- see BettiTally, -- the class of
    all Betti tallies
  * chainComplex -- make a chain complex
  * ChainComplex ** ChainComplex, --
    tensor product
  * "ChainComplex ** Module" -- see ChainComplex ** ChainComplex,
    -- tensor product
  * "Module ** ChainComplex" -- see ChainComplex ** ChainComplex,
    -- tensor product
  * ChainComplex ** GradedModule, --
    tensor product
  * ChainComplex ** Ring -- a binary operator,
    usually used for tensor product or Cartesian product
  * ChainComplex ++ ChainComplex -- direct
    sum
  * ChainComplex Array -- degree shift
  * "coimage(ChainComplexMap)" -- see coimage, -- coimage of a
    map
  * "cokernel(ChainComplexMap)" -- see cokernel, -- cokernel of
    a map of modules, graded modules, or chaincomplexes
  * complete(ChainComplex) -- complete the
    internal parts
  * cone(ChainComplexMap)
  * dual(ChainComplex) -- dual
  * "eagonNorthcott" -- see eagonNorthcott(Matrix),
    -- Eagon-Northcott complex of a matrix of
    linear forms
  * GradedModule ** ChainComplex, --
    tensor product
  * "Hom(ChainComplex,Module)" -- see Hom(Module,ChainComplex),
    -- the Hom functor
  * Hom(Module,ChainComplex) -- the Hom
    functor
  * "image(ChainComplexMap)" -- see image, -- image of a map
  * kernel(ChainComplexMap) -- kernel of a
    chain complex map
  * koszul(Matrix) -- the Koszul complex
  * "minimalPresentation(ChainComplex)" -- see
    minimalPresentation(Module), -- minimal
    presentation of a module
  * "prune(ChainComplex)" -- see minimalPresentation(Module),
    -- minimal presentation of a module
  * Module Array -- make a chain complex from a module
  * new ChainComplex -- make a new chain complex from
    scratch
  * new ChainComplex from Resolution (missing documentation)
  * resolution(Ideal) -- compute a projective
    resolution of (the quotient ring corresponding to) an ideal
  * resolution(Module) -- compute a free
    resolution of a module
  * "RingMap ChainComplex" -- see RingMap RingElement,
    -- apply a ring map

Methods that use a chain complex:
=================================

  * "betti(ChainComplex)" -- see betti, -- display or modify a
    Betti diagram
  * ChainComplex ** ChainComplexMap,
    -- tensor product
  * ChainComplex == ChainComplex (missing documentation)
  * ChainComplex == ZZ (missing documentation)
  * ChainComplex ^ ZZ -- access member, cohomological
    degree
  * ChainComplex _ ZZ -- component
  * ChainComplex _ ZZ = Thing -- install
    component of chain complex
  * ChainComplexMap ** ChainComplex,
    -- tensor product
  * components(ChainComplex)
  * "directSum(ChainComplex)" -- see directSum, -- direct sum
    of modules or maps
  * extend(ChainComplex,ChainComplex,Matrix)
    -- extend a module map to
    a chain map, if possible
  * "formation(ChainComplex)" -- see formation, -- recover the
    methods used to make a module
  * "gradedModule(ChainComplex)" -- see gradedModule, --
    make a graded module
  * HH ChainComplex -- homology of a chain complex
  * HH^ZZ ChainComplex -- cohomology of a chain
    complex
  * HH_ZZ ChainComplex -- homology of a chain
    complex
  * "inducedMap(ChainComplex,ChainComplex)" -- see
    inducedMap(Module,Module), -- compute the
    map induced by the identity
  * "isDirectSum(ChainComplex)" -- see isDirectSum, --
    whether something is a direct sum
  * "isHomogeneous(ChainComplex)" -- see isHomogeneous, --
    whether something is homogeneous (graded)
  * length(ChainComplex) -- length of a chain
    complex or graded module
  * map(ChainComplex,ChainComplex,ChainComplexMap) (missing documentation)
  * map(ChainComplex,ChainComplex,Function)
    -- make a map of chain
    complexes
  * "ChainComplex ^ Array" -- see Module ^ Array, --
    projection onto summand
  * "ChainComplex _ Array" -- see Module _ Array, --
    inclusion from summand
  * poincare(ChainComplex) -- assemble
    degrees of a chain complex into a polynomial
  * "poincareN(ChainComplex)" -- see poincareN, -- assemble
    degrees into polynomial
  * "regularity(ChainComplex)" -- see regularity, -- compute
    the Castelnuovo-Mumford regularity
  * "ring(ChainComplex)" -- see ring, -- get the associated ring of
    an object
  * "status(ChainComplex)" -- see status, -- status of a
    resolution computation
  * sum(ChainComplex) -- direct sum of the
    components of a chain complex
  * "tensorAssociativity(ChainComplex,ChainComplex,ChainComplex)" -- see
    tensorAssociativity, -- associativity isomorphisms for
    tensor products
  * ZZ == ChainComplex (missing documentation)

For the programmer
==================

The object ChainComplex, is a type, with
ancestor classes GradedModule, < MutableHashTable
< HashTable < Thing.

chainComplex -- make a chain complex
************************************

Description
===========

chainComplex -- a method for creating chain complexes.

Ways to use chainComplex:
=========================

  * chainComplex(GradedModule) -- make a
    chain complex from a graded module
  * chainComplex(List) -- make a chain complex
  * "chainComplex(Sequence)" -- see chainComplex(List),
    -- make a chain complex
  * chainComplex(Matrix) -- make a small chain
    complex
  * chainComplex(Ring) -- make an empty chain
    complex over a ring

For the programmer
==================

The object chainComplex, is a method function with a single argument.

ChainComplex ** ChainComplex -- tensor product
**********************************************

Synopsis
========

  * Operator: **,

Description
===========

C**D -- the tensor product of two chain complexes.

The result, E, is a chain complex.  Each module E_k in it is a direct sum of
modules of the form C_i**D_j with i+j=k, and the preferred keys for the
components of this direct sum are the pairs (i,j), sorted increasing values of
i.  For information about how to use preferred keys, see directSum.

Ways to use this method:
========================

  * ChainComplex ** ChainComplex, --
    tensor product
  * "ChainComplex ** Module"
  * "Module ** ChainComplex"

ChainComplex ** ChainComplexMap -- tensor product
*************************************************

Synopsis
========

  * Operator: **,

Description
===========

C ** f -- tensor product of a chain complex with a map of chain complexes.

See also
========

  * ChainComplexMap -- the class of all maps between
    chain complexes

Ways to use this method:
========================

  * ChainComplex ** ChainComplexMap,
    -- tensor product
  * "Module ** ChainComplexMap"

ChainComplex ** GradedModule -- tensor product
**********************************************

Synopsis
========

  * Operator: **,

Description
===========

C**D -- the tensor product of a chain complex with a graded module.

The result is a chain complex.

Ways to use this method:
========================

  * ChainComplex ** GradedModule, --
    tensor product

ChainComplex ** Ring -- a binary operator, usually used for tensor product or Cartesian product
***********************************************************************************************

Synopsis
========

  * Operator: **,
  * Usage:
        C ** R
  * Inputs:
      * C
      * R
  * Outputs:
      * the tensor product of C with R

Description
===========

+-----------------------------------------+
|i1 : R = QQ[a..d];                       |
+-----------------------------------------+
|i2 : C = res coker vars R                |
|                                         |
|      1      4      6      4      1      |
|o2 = R  <-- R  <-- R  <-- R  <-- R  <-- 0|
|                                         |
|     0      1      2      3      4      5|
|                                         |
|o2 : ChainComplex                        |
+-----------------------------------------+
|i3 : S = R[x]                            |
|                                         |
|o3 = S                                   |
|                                         |
|o3 : PolynomialRing                      |
+-----------------------------------------+
|i4 : C**S                                |
|                                         |
|      1      4      6      4      1      |
|o4 = S  <-- S  <-- S  <-- S  <-- S  <-- 0|
|                                         |
|     0      1      2      3      4      5|
|                                         |
|o4 : ChainComplex                        |
+-----------------------------------------+

Ways to use this method:
========================

  * ChainComplex ** Ring -- a binary operator,
    usually used for tensor product or Cartesian product

ChainComplex ++ ChainComplex -- direct sum
******************************************

Synopsis
========

  * Operator: ++,

Description
===========

C++D -- direct sum of chain complexes and maps
+-------------------------------------------+
|i1 : C = resolution cokernel matrix {{4,5}}|
|                                           |
|       1       1                           |
|o1 = ZZ  <-- ZZ                            |
|                                           |
|     0       1                             |
|                                           |
|o1 : ChainComplex                          |
+-------------------------------------------+
|i2 : C ++ C[-2]                            |
|                                           |
|       1       1       1       1           |
|o2 = ZZ  <-- ZZ  <-- ZZ  <-- ZZ            |
|                                           |
|     0       1       2       3             |
|                                           |
|o2 : ChainComplex                          |
+-------------------------------------------+

Ways to use this method:
========================

  * ChainComplex ++ ChainComplex -- direct
    sum
  * "ChainComplexMap ++ ChainComplexMap"
  * "GradedModule ++ GradedModule"

ChainComplex ^ ZZ -- access member, cohomological degree
********************************************************

Synopsis
========

  * Operator: ^,
  * Usage:
        C^n
  * Inputs:
      * C
      * n
  * Outputs:
      * a module, The (-n)-th component C_(-n) of C

Description
===========

Subscripts refer to homological degree, and superscripts refer to cohomological
degree. It is only a matter of notation: C_(-n) is always the same as C^n.
+-----------------------------------+
|i1 : R = QQ[x,y,z];                |
+-----------------------------------+
|i2 : C = res coker vars R          |
|                                   |
|      1      3      3      1       |
|o2 = R  <-- R  <-- R  <-- R  <-- 0 |
|                                   |
|     0      1      2      3      4 |
|                                   |
|o2 : ChainComplex                  |
+-----------------------------------+
|i3 : C = dual C                    |
|                                   |
|             1      3      3      1|
|o3 = 0  <-- R  <-- R  <-- R  <-- R |
|                                   |
|     -4     -3     -2     -1     0 |
|                                   |
|o3 : ChainComplex                  |
+-----------------------------------+
|i4 : C^2                           |
|                                   |
|      3                            |
|o4 = R                             |
|                                   |
|o4 : R-module, free, degrees {3:-2}|
+-----------------------------------+
|i5 : C^2 == C_(-2)                 |
|                                   |
|o5 = true                          |
+-----------------------------------+

See also
========

  * ChainComplex -- the class of all chain complexes
  * ChainComplex ^ Array -- projection onto summand

Ways to use this method:
========================

  * ChainComplex ^ ZZ -- access member, cohomological
    degree

ChainComplex _ ZZ -- component
******************************

Synopsis
========

  * Operator: _,
  * Usage:
        C_i
  * Inputs:
      * C, or a graded module,
      * i
  * Outputs:
      * a module, the i-th component of C

Description
===========

+-------------------------------------------------------------------------+
|i1 : R = QQ[x,y,z]/(x^3,y^3,z^3,x*y*z);                                  |
+-------------------------------------------------------------------------+
|i2 : C = res(coker vars R, LengthLimit=>8)                               |
|                                                                         |
|      1      3      7      16      37      86      200      465      1081|
|o2 = R  <-- R  <-- R  <-- R   <-- R   <-- R   <-- R    <-- R    <-- R    |
|                                                                         |
|     0      1      2      3       4       5       6        7        8    |
|                                                                         |
|o2 : ChainComplex                                                        |
+-------------------------------------------------------------------------+
|i3 : rank C_7                                                            |
|                                                                         |
|o3 = 465                                                                 |
+-------------------------------------------------------------------------+
|i4 : C.dd_3                                                              |
|                                                                         |
|o4 = {2} | x  0 -z2 0   0  -xy 0 y2 0 0   0  0  0 xz2 xy2 0   |          |
|     {2} | -y 0 0   -z2 yz y2  0 0  0 0   x2 0  0 0   0   x2y |          |
|     {2} | z  0 0   0   0  0   0 0  0 -y2 0  x2 0 0   0   0   |          |
|     {3} | 0  z y   x   0  0   0 0  0 0   0  0  0 0   0   0   |          |
|     {3} | 0  0 0   0   z  y   x 0  0 0   0  0  0 0   0   0   |          |
|     {3} | 0  0 0   0   0  0   0 z  y x   0  0  0 0   0   0   |          |
|     {3} | 0  0 0   0   0  0   0 0  0 0   z  y  x 0   0   0   |          |
|                                                                         |
|             7      16                                                   |
|o4 : Matrix R  <-- R                                                     |
+-------------------------------------------------------------------------+

Programming hint
================

The chain complex C is implemented as a hash table, but since the computation
of a projective resolution can be stopped prematurely, Macaulay2 doesn't bother
populating the hash table with the relevant free modules until explicitly
requested by the user, for example, in response to the command C_i described
above.  The hash table C can be examined directly with code like C#i, but in
order to populate the hash table completely, use complete(ChainComplex).

See also
========

  * resolution -- projective resolution
  * ChainComplex ^ ZZ -- access member, cohomological
    degree
  * ChainComplexMap _ ZZ -- component map

Ways to use this method:
========================

  * ChainComplex _ ZZ -- component
  * "GradedModule _ ZZ"

ChainComplex _ ZZ = Thing -- install component of chain complex
***************************************************************

Synopsis
========

  * Operator: _,
  * Usage:
        C_i = M
  * Inputs:
      * C
      * i
      * M
  * Outputs:
      * install M as the i-th module of the chain complex C

Description
===========

+-----------------------+
|i1 : R = ZZ[x..z]      |
|                       |
|o1 = R                 |
|                       |
|o1 : PolynomialRing    |
+-----------------------+
|i2 : C = chainComplex R|
|                       |
|o2 = 0                 |
|                       |
|o2 : ChainComplex      |
+-----------------------+
|i3 : C_2 = R^11        |
|                       |
|      11               |
|o3 = R                 |
|                       |
|o3 : R-module, free    |
+-----------------------+
|i4 : C_4 = R^13        |
|                       |
|      13               |
|o4 = R                 |
|                       |
|o4 : R-module, free    |
+-----------------------+
|i5 : C                 |
|                       |
|      11            13 |
|o5 = R   <-- 0 <-- R   |
|                       |
|     2       3     4   |
|                       |
|o5 : ChainComplex      |
+-----------------------+

See also
========

  * ChainComplexMap _ ZZ = Thing, --
    install component of chain complex map

Ways to use this method:
========================

  * ChainComplex _ ZZ = Thing -- install
    component of chain complex

ChainComplex Array -- degree shift
**********************************

Synopsis
========

  * Operator: SPACE,
  * Usage:
        D = C[i]
  * Inputs:
      * C,
      * i, an array, an array [i] containing an integer i
  * Outputs:
      * D, a new chain complex D in which D_j is C_(i+j).  The signs of the
        differentials are reversed if i is odd.

Description
===========

+----------------------------------+
|i1 : R = QQ[x..z];                |
+----------------------------------+
|i2 : C = res coker vars R         |
|                                  |
|      1      3      3      1      |
|o2 = R  <-- R  <-- R  <-- R  <-- 0|
|                                  |
|     0      1      2      3      4|
|                                  |
|o2 : ChainComplex                 |
+----------------------------------+
|i3 : C[3]                         |
|                                  |
|      1      3      3      1      |
|o3 = R  <-- R  <-- R  <-- R  <-- 0|
|                                  |
|     -3     -2     -1     0      1|
|                                  |
|o3 : ChainComplex                 |
+----------------------------------+

Ways to use this method:
========================

  * ChainComplex Array -- degree shift

chainComplex(GradedModule) -- make a chain complex from a graded module
***********************************************************************

Synopsis
========

  * Function: chainComplex,
  * Usage:
        chainComplex M
  * Inputs:
      * M
  * Outputs:
      * the chain complex made from M by installing the zero map as
        differential

See also
========

  * chain complexes

Ways to use this method:
========================

  * chainComplex(GradedModule) -- make a
    chain complex from a graded module

chainComplex(List) -- make a chain complex
******************************************

Synopsis
========

  * Function: chainComplex,
  * Usage:
        C = chainComplex{f1,f2,f3,...}
        C = chainComplex(f1,f2,f3,...)
  * Inputs:
      * f1,f2,f3,..., homomorphisms over the same ring, forming a complex
  * Outputs:
      * C, a chain complex, the given complex, where f1 ==
        C.dd_1, f2 == CC.dd_2, etc.

Description
===========

The maps f1, f2, ... must be defined over the same base ring, and they must
form a complex: the target of f(i+1) is the source of fi.

The following example illustrates how chainComplex adjusts the degrees of the
modules involved to ensure that sources and targets of the differentials
correspond exactly.
+---------------------------------------------------------+
|i1 : R = ZZ/101[x,y]                                     |
|                                                         |
|o1 = R                                                   |
|                                                         |
|o1 : PolynomialRing                                      |
+---------------------------------------------------------+
|i2 : C = chainComplex{matrix{{x,y}},matrix{{x*y},{-x^2}}}|
|                                                         |
|      1      2      1                                    |
|o2 = R  <-- R  <-- R                                     |
|                                                         |
|     0      1      2                                     |
|                                                         |
|o2 : ChainComplex                                        |
+---------------------------------------------------------+
We check that this is a complex:
+----------------+
|i3 : C.dd^2 == 0|
|                |
|o3 = true       |
+----------------+
The homology of this complex:
+----------------------------------------------+
|i4 : HH C                                     |
|                                              |
|o4 = 0 : cokernel | x y |                     |
|                                              |
|     1 : subquotient ({1} | -y |, {1} | xy  |)|
|                      {1} | x  |  {1} | -x2 | |
|                                              |
|     2 : image 0                              |
|                                              |
|o4 : GradedModule                             |
+----------------------------------------------+

See also
========

  * chain complexes

Ways to use this method:
========================

  * chainComplex(List) -- make a chain complex
  * "chainComplex(Sequence)"

chainComplex(Matrix) -- make a small chain complex
**************************************************

Synopsis
========

  * Function: chainComplex,
  * Usage:
        chainComplex f
  * Inputs:
      * f
  * Outputs:
      * a chain complex with the map f serving as the differential C.dd_1

Description
===========

+-------------------------+
|i1 : R = QQ[x,y];        |
+-------------------------+
|i2 : f = vars R          |
|                         |
|o2 = | x y |             |
|                         |
|             1      2    |
|o2 : Matrix R  <-- R     |
+-------------------------+
|i3 : chainComplex f      |
|                         |
|      1      2           |
|o3 = R  <-- R            |
|                         |
|     0      1            |
|                         |
|o3 : ChainComplex        |
+-------------------------+
|i4 : HH oo               |
|                         |
|o4 = 0 : cokernel | x y ||
|                         |
|     1 : image {1} | -y ||
|               {1} | x  ||
|                         |
|o4 : GradedModule        |
+-------------------------+

See also
========

  * chain complexes

Ways to use this method:
========================

  * chainComplex(Matrix) -- make a small chain
    complex

chainComplex(Ring) -- make an empty chain complex over a ring
*************************************************************

Synopsis
========

  * Function: chainComplex,
  * Usage:
        chainComplex R
  * Inputs:
      * R
  * Outputs:
      * an empty chain complex over R

Description
===========

The resulting chain complex can be further populated with modules and maps.
+------------------------------------------------+
|i1 : C = chainComplex ZZ                        |
|                                                |
|o1 = 0                                          |
|                                                |
|o1 : ChainComplex                               |
+------------------------------------------------+
|i2 : C.dd_101 = random(ZZ^2,ZZ^3)               |
|                                                |
|o2 = | 8 3 8 |                                  |
|     | 1 7 3 |                                  |
|                                                |
|              2       3                         |
|o2 : Matrix ZZ  <-- ZZ                          |
+------------------------------------------------+
|i3 : C.dd_105 = id_(ZZ^2)                       |
|                                                |
|o3 = | 1 0 |                                    |
|     | 0 1 |                                    |
|                                                |
|              2       2                         |
|o3 : Matrix ZZ  <-- ZZ                          |
+------------------------------------------------+
|i4 : C                                          |
|                                                |
|       2       3                       2       2|
|o4 = ZZ  <-- ZZ  <-- 0   <-- 0   <-- ZZ  <-- ZZ |
|                                                |
|     100     101     102     103     104     105|
|                                                |
|o4 : ChainComplex                               |
+------------------------------------------------+
|i5 : C.dd                                       |
|                                                |
|             2                  3               |
|o5 = 100 : ZZ  <------------- ZZ  : 101         |
|                  | 8 3 8 |                     |
|                  | 1 7 3 |                     |
|                                                |
|             2                2                 |
|     104 : ZZ  <----------- ZZ  : 105           |
|                  | 1 0 |                       |
|                  | 0 1 |                       |
|                                                |
|o5 : ChainComplexMap                            |
+------------------------------------------------+

Ways to use this method:
========================

  * chainComplex(Ring) -- make an empty chain
    complex over a ring

ChainComplexMap -- the class of all maps between chain complexes
****************************************************************

Description
===========

The usual algebraic operations are available: addition, subtraction, scalar
multiplication, and composition.  The identity map from a chain complex to
itself can be produced with id.  An attempt to add (subtract, or
compare) a ring element to a chain complex will result in the ring element
being multiplied by the appropriate identity map.

Functions and methods returning a chain complex map:
====================================================

  * "ChainComplexMap * ChainComplexMap" -- see *, -- a binary
    operator, usually used for multiplication
  * "ChainComplexMap + ChainComplexMap" -- see +, -- a unary or binary
    operator, usually used for addition
  * "- ChainComplexMap" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "ChainComplexMap - ChainComplexMap" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * ChainComplex ** ChainComplexMap,
    -- tensor product
  * "Module ** ChainComplexMap" -- see ChainComplex ** ChainComplexMap,
    -- tensor product
  * "ChainComplexMap ++ ChainComplexMap" -- see ChainComplex ++ ChainComplex,
    -- direct sum
  * ChainComplexMap ** ChainComplex,
    -- tensor product
  * "ChainComplexMap ** Module" -- see ChainComplexMap ** ChainComplex,
    -- tensor product
  * ChainComplexMap ** ChainComplexMap
    -- tensor product
  * ChainComplexMap ^ ZZ -- iterated composition
  * ChainComplexMap Array -- degree shift
  * dual(ChainComplexMap) -- dual of a chain
    complex
  * extend(ChainComplex,ChainComplex,Matrix)
    -- extend a module map to
    a chain map, if possible
  * "Hom(ChainComplexMap,Module)" -- see Hom(Module,ChainComplex),
    -- the Hom functor
  * "Hom(Module,ChainComplexMap)" -- see Hom(Module,ChainComplex),
    -- the Hom functor
  * "inducedMap(ChainComplex,ChainComplex)" -- see
    inducedMap(Module,Module), -- compute the
    map induced by the identity
  * map(ChainComplex,ChainComplex,ChainComplexMap) (missing documentation)
  * map(ChainComplex,ChainComplex,Function)
    -- make a map of chain
    complexes
  * "ChainComplexMap ^ Array" -- see Matrix ^ Array, --
    component of map corresponding to summand of target
  * "ChainComplexMap _ Array" -- see Matrix _ Array, --
    component of map corresponding to summand of source
  * "minimalPresentation(ChainComplexMap)" -- see
    minimalPresentation(Module), -- minimal
    presentation of a module
  * "prune(ChainComplexMap)" -- see minimalPresentation(Module),
    -- minimal presentation of a module
  * "ChainComplex ^ Array" -- see Module ^ Array, --
    projection onto summand
  * "ChainComplex _ Array" -- see Module _ Array, --
    inclusion from summand
  * "nullhomotopy(ChainComplexMap)" -- see nullhomotopy, --
    make a null homotopy
  * resolution(Matrix) -- given a module map
    represented by a matrix, produce a comparison map between resolutions of
    its source and target
  * RingMap ChainComplexMap (missing documentation)
  * "tensorAssociativity(ChainComplex,ChainComplex,ChainComplex)" -- see
    tensorAssociativity, -- associativity isomorphisms for
    tensor products

Methods that use a chain complex map:
=====================================

  * "RingElement * ChainComplexMap" -- see *, -- a binary operator,
    usually used for multiplication
  * "ChainComplexMap + RingElement" -- see +, -- a unary or binary
    operator, usually used for addition
  * "ChainComplexMap + ZZ" -- see +, -- a unary or binary operator,
    usually used for addition
  * "RingElement + ChainComplexMap" -- see +, -- a unary or binary
    operator, usually used for addition
  * "ZZ + ChainComplexMap" -- see +, -- a unary or binary operator,
    usually used for addition
  * "ChainComplexMap - RingElement" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "RingElement - ChainComplexMap" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * ChainComplexMap == ChainComplexMap (missing documentation)
  * ChainComplexMap == RingElement (missing documentation)
  * ChainComplexMap == ZZ (missing documentation)
  * ChainComplexMap _ ZZ -- component map
  * ChainComplexMap _ ZZ = Thing, --
    install component of chain complex map
  * "coimage(ChainComplexMap)" -- see coimage, -- coimage of a
    map
  * "cokernel(ChainComplexMap)" -- see cokernel, -- cokernel of
    a map of modules, graded modules, or chaincomplexes
  * "complete(ChainComplexMap)" -- see complete,
  * "components(ChainComplexMap)" -- see components, -- list
    the components of a direct sum
  * cone(ChainComplexMap)
  * degree(ChainComplexMap) (missing documentation)
  * "formation(ChainComplexMap)" -- see formation, -- recover
    the methods used to make a module
  * HH ChainComplexMap -- homology of a chain
    complex map
  * HH^ZZ ChainComplexMap -- cohomology of a
    chain complex map
  * HH_ZZ ChainComplexMap -- homology of a
    chain complex map
  * "image(ChainComplexMap)" -- see image, -- image of a map
  * isCommutative(ChainComplexMap) (missing documentation)
  * "isHomogeneous(ChainComplexMap)" -- see isHomogeneous,
    -- whether something is homogeneous (graded)
  * kernel(ChainComplexMap) -- kernel of a
    chain complex map
  * "ring(ChainComplexMap)" -- see ring, -- get the associated ring
    of an object
  * RingElement == ChainComplexMap (missing documentation)
  * source(ChainComplexMap) --  find the
    source of a map of chain complexes
  * sum(ChainComplexMap) -- direct sum of the
    components of a chain map
  * target(ChainComplexMap) --  find the
    target of a map of chain complexes
  * transpose(ChainComplexMap), --
    transpose a map of chain complexes
  * ZZ == ChainComplexMap (missing documentation)

For the programmer
==================

The object ChainComplexMap, is a type, with
ancestor classes GradedModuleMap, <
MutableHashTable < HashTable <
Thing.

ChainComplexMap ** ChainComplex -- tensor product
*************************************************

Synopsis
========

  * Operator: **,

Description
===========

f ** C -- tensor product of a map of chain complexes with a chain complex.

See also
========

  * ChainComplexMap -- the class of all maps between
    chain complexes

Ways to use this method:
========================

  * ChainComplexMap ** ChainComplex,
    -- tensor product
  * "ChainComplexMap ** Module"

ChainComplexMap ** ChainComplexMap -- tensor product
****************************************************

Synopsis
========

  * Operator: **,

Description
===========

f ** g -- tensor product of two maps of chain complexes.

See also
========

  * ChainComplexMap -- the class of all maps between
    chain complexes

Ways to use this method:
========================

  * ChainComplexMap ** ChainComplexMap
    -- tensor product

ChainComplexMap ^ ZZ -- iterated composition
********************************************

Synopsis
========

  * Operator: ^,
  * Usage:
        f^n
  * Inputs:
      * f, or a a graded module map,
      * n
  * Outputs:
      * a chain complex map, the composite f o f o ...
        o f (n times)

Description
===========

If f is a GradedModuleMap, then so is the result.

One use of this function is to determine if a chain complex is well-defined.
The chain complex will be well-defined if the square of the differential is
zero.
+----------------------------------+
|i1 : R = QQ[x,y,z];               |
+----------------------------------+
|i2 : C = res coker vars R         |
|                                  |
|      1      3      3      1      |
|o2 = R  <-- R  <-- R  <-- R  <-- 0|
|                                  |
|     0      1      2      3      4|
|                                  |
|o2 : ChainComplex                 |
+----------------------------------+
|i3 : C.dd^2 == 0                  |
|                                  |
|o3 = true                         |
+----------------------------------+

See also
========

  * ChainComplex -- the class of all chain complexes

Ways to use this method:
========================

  * ChainComplexMap ^ ZZ -- iterated composition
  * "GradedModuleMap ^ ZZ"

ChainComplexMap _ ZZ -- component map
*************************************

Synopsis
========

  * Operator: _,
  * Usage:
        p_i
  * Inputs:
      * p, a map D <- C of chain complexes, of degree d, say
      * i
  * Outputs:
      * a matrix, the component D_(i+d) <- C_i

Description
===========

+------------------------------------------------------------------+
|i1 : R = ZZ/101[a..c];                                            |
+------------------------------------------------------------------+
|i2 : I = image vars R                                             |
|                                                                  |
|o2 = image | a b c |                                              |
|                                                                  |
|                             1                                    |
|o2 : R-module, submodule of R                                     |
+------------------------------------------------------------------+
|i3 : J = image symmetricPower (2,vars R)                          |
|                                                                  |
|o3 = image | a2 ab ac b2 bc c2 |                                  |
|                                                                  |
|                             1                                    |
|o3 : R-module, submodule of R                                     |
+------------------------------------------------------------------+
|i4 : g = extend( resolution (R^1/I), resolution (R^1/J), id_(R^1))|
|                                                                  |
|          1             1                                         |
|o4 = 0 : R  <--------- R  : 0                                     |
|               | 1 |                                              |
|                                                                  |
|          3                           6                           |
|     1 : R  <----------------------- R  : 1                       |
|               {1} | a b 0 0 0 0 |                                |
|               {1} | 0 0 b 0 0 0 |                                |
|               {1} | 0 0 0 a b c |                                |
|                                                                  |
|          3                               8                       |
|     2 : R  <--------------------------- R  : 2                   |
|               {2} | 0 b 0 0 0 0 0 0 |                            |
|               {2} | 0 0 a b 0 0 0 0 |                            |
|               {2} | 0 0 0 0 0 b 0 0 |                            |
|                                                                  |
|          1                     3                                 |
|     3 : R  <----------------- R  : 3                             |
|               {3} | 0 b 0 |                                      |
|                                                                  |
|     4 : 0 <----- 0 : 4                                           |
|              0                                                   |
|                                                                  |
|o4 : ChainComplexMap                                              |
+------------------------------------------------------------------+
|i5 : g_1                                                          |
|                                                                  |
|o5 = {1} | a b 0 0 0 0 |                                          |
|     {1} | 0 0 b 0 0 0 |                                          |
|     {1} | 0 0 0 a b c |                                          |
|                                                                  |
|             3      6                                             |
|o5 : Matrix R  <-- R                                              |
+------------------------------------------------------------------+
|i6 : g_2                                                          |
|                                                                  |
|o6 = {2} | 0 b 0 0 0 0 0 0 |                                      |
|     {2} | 0 0 a b 0 0 0 0 |                                      |
|     {2} | 0 0 0 0 0 b 0 0 |                                      |
|                                                                  |
|             3      8                                             |
|o6 : Matrix R  <-- R                                              |
+------------------------------------------------------------------+
The map p may also be a graded module map.

See also
========

  * ChainComplex _ ZZ -- component
  * extend -- extend a module map to a chain map, if possible
  * resolution -- projective resolution
  * image -- image of a map
  * vars -- variables
  * symmetricPower -- symmetric power

Ways to use this method:
========================

  * ChainComplexMap _ ZZ -- component map
  * "GradedModuleMap _ ZZ"

ChainComplexMap _ ZZ = Thing -- install component of chain complex map
**********************************************************************

Synopsis
========

  * Operator: _,
  * Usage:
        f_i = g
  * Inputs:
      * f
      * i
      * g
  * Outputs:
      * install g as the i-th module of the chain complex map f

Description
===========

+----------------------------------+
|i1 : R = ZZ[x..z]                 |
|                                  |
|o1 = R                            |
|                                  |
|o1 : PolynomialRing               |
+----------------------------------+
|i2 : C = chainComplex R           |
|                                  |
|o2 = 0                            |
|                                  |
|o2 : ChainComplex                 |
+----------------------------------+
|i3 : C.dd                         |
|                                  |
|o3 = 0                            |
|                                  |
|o3 : ChainComplexMap              |
+----------------------------------+
|i4 : C.dd_1 = vars R              |
|                                  |
|o4 = | x y z |                    |
|                                  |
|             1      3             |
|o4 : Matrix R  <-- R              |
+----------------------------------+
|i5 : C.dd_3 = transpose vars R    |
|                                  |
|o5 = {-1} | x |                   |
|     {-1} | y |                   |
|     {-1} | z |                   |
|                                  |
|             3      1             |
|o5 : Matrix R  <-- R              |
+----------------------------------+
|i6 : C.dd                         |
|                                  |
|          1                 3     |
|o6 = 0 : R  <------------- R  : 1 |
|               | x y z |          |
|                                  |
|          3         3             |
|     1 : R  <----- R  : 2         |
|               0                  |
|                                  |
|          3                  1    |
|     2 : R  <-------------- R  : 3|
|               {-1} | x |         |
|               {-1} | y |         |
|               {-1} | z |         |
|                                  |
|o6 : ChainComplexMap              |
+----------------------------------+
|i7 : C                            |
|                                  |
|      1      3      3      1      |
|o7 = R  <-- R  <-- R  <-- R       |
|                                  |
|     0      1      2      3       |
|                                  |
|o7 : ChainComplex                 |
+----------------------------------+
|i8 : HH C                         |
|                                  |
|o8 = 0 : cokernel | x y z |       |
|                                  |
|     1 : image {1} | -y 0  -z |   |
|               {1} | x  -z 0  |   |
|               {1} | 0  y  x  |   |
|                                  |
|     2 : cokernel {-1} | x |      |
|                  {-1} | y |      |
|                  {-1} | z |      |
|                                  |
|     3 : image 0                  |
|                                  |
|o8 : GradedModule                 |
+----------------------------------+
|i9 : prune HH C                   |
|                                  |
|o9 = 0 : cokernel | z y x |       |
|                                  |
|     1 : cokernel {2} | z  |      |
|                  {2} | x  |      |
|                  {2} | -y |      |
|                                  |
|     2 : cokernel {-1} | x |      |
|                  {-1} | y |      |
|                  {-1} | z |      |
|                                  |
|     3 : 0                        |
|                                  |
|o9 : GradedModule                 |
+----------------------------------+

See also
========

  * ChainComplex _ ZZ = Thing -- install
    component of chain complex

Ways to use this method:
========================

  * ChainComplexMap _ ZZ = Thing, --
    install component of chain complex map

ChainComplexMap Array -- degree shift
*************************************

Synopsis
========

  * Operator: SPACE,
  * Usage:
        g = f[i]
  * Inputs:
      * f,
      * i, an array, an array [i] containing an integer i
  * Outputs:
      * g, a new chain complex map g in which g_j is f_(i+j).

Description
===========

+---------------------------------------+
|i1 : R = QQ[x..z];                     |
+---------------------------------------+
|i2 : C = res coker vars R;             |
+---------------------------------------+
|i3 : f = id_C                          |
|                                       |
|          1             1              |
|o3 = 0 : R  <--------- R  : 0          |
|               | 1 |                   |
|                                       |
|          3                     3      |
|     1 : R  <----------------- R  : 1  |
|               {1} | 1 0 0 |           |
|               {1} | 0 1 0 |           |
|               {1} | 0 0 1 |           |
|                                       |
|          3                     3      |
|     2 : R  <----------------- R  : 2  |
|               {2} | 1 0 0 |           |
|               {2} | 0 1 0 |           |
|               {2} | 0 0 1 |           |
|                                       |
|          1                 1          |
|     3 : R  <------------- R  : 3      |
|               {3} | 1 |               |
|                                       |
|     4 : 0 <----- 0 : 4                |
|              0                        |
|                                       |
|o3 : ChainComplexMap                   |
+---------------------------------------+
|i4 : f[3]                              |
|                                       |
|           1             1             |
|o4 = -3 : R  <--------- R  : -3        |
|                | 1 |                  |
|                                       |
|           3                     3     |
|     -2 : R  <----------------- R  : -2|
|                {1} | 1 0 0 |          |
|                {1} | 0 1 0 |          |
|                {1} | 0 0 1 |          |
|                                       |
|           3                     3     |
|     -1 : R  <----------------- R  : -1|
|                {2} | 1 0 0 |          |
|                {2} | 0 1 0 |          |
|                {2} | 0 0 1 |          |
|                                       |
|          1                 1          |
|     0 : R  <------------- R  : 0      |
|               {3} | 1 |               |
|                                       |
|     1 : 0 <----- 0 : 1                |
|              0                        |
|                                       |
|o4 : ChainComplexMap                   |
+---------------------------------------+

Ways to use this method:
========================

  * ChainComplexMap Array -- degree shift

changeBase -- change integer base
*********************************

Synopsis
========

  * Usage:
        changeBase(n, newbase)
        changeBase(str, oldbase)
        changeBase(str, oldbase, newbase)
  * Inputs:
      * n, an integer,
      * str, a string,
      * oldbase, an integer,
      * newbase, an integer,
  * Outputs:
      * an integer, or a string,

Description
===========

When both arguments are integers, the return value is a string representation
of the first argument in the base given by the second argument.

+------------------------+
|i1 : changeBase(255, 16)|
|                        |
|o1 = ff                 |
+------------------------+

Bases from 2 to 62 are supported.  If newbase is between 11 and 36, then the
digits representing 10 through newbase - 1 are the lowercase letters.

+-----------------------------------------------------------------------------+
|i2 : for n from 10 to 35 list changeBase(n, 36)                              |
|                                                                             |
|o2 = {a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x,|
|     ------------------------------------------------------------------------|
|     y, z}                                                                   |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

If newbase is between 37 and 62, then the digits representing 10 through 35 are
uppercase letters and the digits representing 36 through newbase - 1 are
lowercase letters.

+-----------------------------------------------------------------------------+
|i3 : for n from 10 to 61 list changeBase(n, 62)                              |
|                                                                             |
|o3 = {A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X,|
|     ------------------------------------------------------------------------|
|     Y, Z, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, |
|     ------------------------------------------------------------------------|
|     w, x, y, z}                                                             |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

If the first argument is a string, then we get the inverse operation, i.e., the
ZZ, object that the string represents in the given base.

+-------------------------+
|i4 : changeBase("ff", 16)|
|                         |
|o4 = 255                 |
+-------------------------+

Uppercase letters are also allowed when oldbase is between 11 and 36, as there
is no ambiguity.

+-------------------------+
|i5 : changeBase("FF", 16)|
|                         |
|o5 = 255                 |
+-------------------------+

If oldbase is 0, then the base is determined by the standard C prefix, i.e., 0b
or 0B for binary, 0 for octal, 0x or 0X for hexadecimal, and no prefix for
decimal.

+-----------------------------------------------------------------------------+
|i6 : apply({"0b10", "0B10", "010", "0x10", "0X10", "10"}, s -> changeBase(s, |
|                                                                             |
|o6 = {2, 2, 8, 16, 16, 10}                                                   |
|                                                                             |
|o6 : List                                                                    |
|-----------------------------------------------------------------------------|
|0))                                                                          |
+-----------------------------------------------------------------------------+

If a string and two integer arguments are given, then the integer represented
by the string is converted from one base to another, returning a string.

+----------------------------+
|i7 : changeBase("ff", 16, 2)|
|                            |
|o7 = 11111111               |
+----------------------------+

Ways to use changeBase:
=======================

  * "changeBase(String,ZZ)"
  * "changeBase(String,ZZ,ZZ)"
  * "changeBase(ZZ,ZZ)"

For the programmer
==================

The object changeBase, is a method function.

changeDirectory -- change the current working directory
*******************************************************

Synopsis
========

  * Usage:
        changeDirectory dir
  * Inputs:
      * dir, a string,
  * Outputs:
      * a string, the new working directory;

Description
===========

Change the current working directory to dir.

+------------------------------+
|i1 : dir = temporaryFileName()|
|                              |
|o1 = /tmp/M2-2532269-0/0      |
+------------------------------+
|i2 : makeDirectory dir        |
|                              |
|o2 = /tmp/M2-2532269-0/0      |
+------------------------------+
|i3 : changeDirectory dir      |
|                              |
|o3 = /tmp/M2-2532269-0/0/     |
+------------------------------+
|i4 : currentDirectory()       |
|                              |
|o4 = /tmp/M2-2532269-0/0/     |
+------------------------------+

If dir is omitted, then the current working directory is changed to the user's
home directory.

See also
========

  * currentDirectory -- current working directory

For the programmer
==================

The object changeDirectory, is a compiled function.

char -- computes the characteristic of the ring or field
********************************************************

Synopsis
========

  * Usage:
        char F
  * Inputs:
      * F, a ring,
  * Outputs:
      * the characteristic of the ring.

Description
===========

+---------------------------------------------+
|i1 : R = ZZ/10007[x,y];                      |
+---------------------------------------------+
|i2 : char R                                  |
|                                             |
|o2 = 10007                                   |
+---------------------------------------------+
|i3 : R = ZZ[x]/823671827384723894723894723892|
|                                             |
|o3 = R                                       |
|                                             |
|o3 : QuotientRing                            |
+---------------------------------------------+
|i4 : char R                                  |
|                                             |
|o4 = 823671827384723894723894723892          |
+---------------------------------------------+

Ways to use char:
=================

  * "char(Ring)"
  * char(AffineVariety) (Varieties) -- the
    characteristic of the coordinate ring of a variety
  * "char(ProjectiveVariety)" -- see char(AffineVariety) (Varieties),
    -- the characteristic of the coordinate
    ring of a variety

For the programmer
==================

The object char, is a method function.

characters -- get characters from a string
******************************************

Synopsis
========

  * Usage:
        characters s
  * Inputs:
      * s, a string,
  * Outputs:
      * a list, of the characters in the string s

Description
===========

The characters are represented by strings.

+----------------------+
|i1 : characters "asdf"|
|                      |
|o1 = {a, s, d, f}     |
|                      |
|o1 : List             |
+----------------------+

utf8 characters are correctly treated:

+--------------------------------------+
|i2 : characters "π ≈ 3.14159"         |
|                                      |
|o2 = {π,  , ≈,  , 3, ., 1, 4, 1, 5, 9}|
|                                      |
|o2 : List                             |
+--------------------------------------+

To get the one-byte characters of the string, use toList,
instead.

See also
========

  * String -- the class of all strings

For the programmer
==================

The object characters, is a compiled function.

chi
***

Description
===========

This function is a method function, defined in the core so multiple packages
can add methods to it.

For the programmer
==================

The object chi, is a method function.

clean -- Set to zero elements that are approximately zero
*********************************************************

Synopsis
========

  * Usage:
        clean(epsilon,M)
        clean_epsilon M
  * Inputs:
      * epsilon, a real number,
      * M, a matrix, or a a ring element,
  * Outputs:
      * a matrix, or a ring element,

Description
===========

If the input is a matrix, or a ring element,
then the result has the same type, where each real or complex number
coefficient that is less than epsilon in absolute value is replaced with zero.

+------------------------------------------------+
|i1 : e = 1e-11;                                 |
+------------------------------------------------+
|i2 : M = random(RR^4,RR^4)                      |
|                                                |
|o2 = | .892712 .0258884 .461944 .0741835 |      |
|     | .673395 .714827  .775187 .808694  |      |
|     | .29398  .89189   .909047 .362835  |      |
|     | .632944 .231053  .314897 .706096  |      |
|                                                |
|                4         4                     |
|o2 : Matrix RR    <-- RR                        |
|              53        53                      |
+------------------------------------------------+
|i3 : M * (M + 1) + 1 - M^2 - M                  |
|                                                |
|o3 = | 1            0 0           0            ||
|     | 1.11022e-16  1 1.11022e-16 -2.22045e-16 ||
|     | 1.11022e-16  0 1           -2.22045e-16 ||
|     | -2.22045e-16 0 0           1            ||
|                                                |
|                4         4                     |
|o3 : Matrix RR    <-- RR                        |
|              53        53                      |
+------------------------------------------------+
|i4 : clean_e oo                                 |
|                                                |
|o4 = | 1 0 0 0 |                                |
|     | 0 1 0 0 |                                |
|     | 0 0 1 0 |                                |
|     | 0 0 0 1 |                                |
|                                                |
|                4         4                     |
|o4 : Matrix RR    <-- RR                        |
|              53        53                      |
+------------------------------------------------+
Cleaning a polynomial is a way to get rid of small terms.
+-----------------------------------------------------------------------------+
|i5 : CC[x];                                                                  |
+-----------------------------------------------------------------------------+
|i6 : f = product(5,j -> x - exp(2*pi*j*ii/5))                                |
|                                                                             |
|      5                                  4                   3               |
|o6 = x  + (2.22045e-16 - 1.11022e-16*ii)x  - 1.11022e-16*ii*x  + (-          |
|     ------------------------------------------------------------------------|
|                                   2                                         |
|     1.11022e-16 - 1.11022e-16*ii)x  - 1.11022e-16*ii*x - 1 + 5.55112e-16*ii |
|                                                                             |
|o6 : CC  [x]                                                                 |
|       53                                                                    |
+-----------------------------------------------------------------------------+
|i7 : clean_e f                                                               |
|                                                                             |
|      5                                                                      |
|o7 = x  - 1                                                                  |
|                                                                             |
|o7 : CC  [x]                                                                 |
|       53                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * norm
  * RR -- the class of all real numbers
  * CC -- the class of all complex numbers
  * fillMatrix -- fill a mutable matrix with random numbers

Ways to use clean:
==================

  * "clean(RR,Matrix)"
  * "clean(RR,MutableMatrix)"
  * "clean(RR,Number)"
  * "clean(RR,RingElement)"

For the programmer
==================

The object clean, is a method function.

clearAll -- forget everything
*****************************

Synopsis
========

  * Usage:
        clearAll

Description
===========

clearAll is a command that attempts to release memory by clearing the values
retained by the output line symbols and all the user symbols.

See also
========

  * userSymbols -- a list of the user's symbols
  * clearOutput -- forget output values

For the programmer
==================

The object clearAll, is a command.

clearOutput -- forget output values
***********************************

Synopsis
========

  * Usage:
        clearOutput

Description
===========

clearOutput is a command that attempts to release memory by clearing the values
retained by the output line symbols.

See also
========

  * clearAll -- forget everything

For the programmer
==================

The object clearOutput, is a command.

close -- close a file
*********************

Description
===========

f << close -- closes the file f.
close f -- closes the file f.

In the case of an output file, any buffered output is first written to the
file, and the return value is an integer, normally 0, or -1 on error, or the
return status of the child process in case the file was a pipe.

If the file was open for both input and output, both directions are closed.

If the file is a pipe to another process, i.e., the filename began with the
character !, we will wait for the process to terminate.  If you don't want to
wait for the process to terminate, open the file with openInOut,
and if necessary, use closeIn, to close it, to
indicate that it has received all its input.

If the file is stdio then it is left open, and no error is signaled.

Ways to use close:
==================

  * "File << Manipulator" -- see File << Thing, -- print
    to a file
  * "Nothing << Manipulator" -- see File << Thing, --
    print to a file
  * "Manipulator Database" -- see Manipulator, -- the class
    of all file manipulators
  * "Manipulator File" -- see Manipulator, -- the class of
    all file manipulators
  * "Manipulator Nothing" -- see Manipulator, -- the class
    of all file manipulators
  * "new Manipulator from Function" -- see Manipulator, --
    the class of all file manipulators
  * "methods(Manipulator)" -- see methods, -- list methods
  * "Manipulator NetFile" -- see NetFile, -- the class of all
    net files
  * "NetFile << Manipulator" -- see NetFile, -- the class of all
    net files

For the programmer
==================

The object close, is a manipulator.

closeIn -- close an input file
******************************

Description
===========

f << closeIn -- closes the input file f.
closeIn f -- closes the input file f.

If the file was open only for input, then close, is easier to use
and has the same effect.

If the file was open for both input and output, it remains open for output.

Ways to use closeIn:
====================

  * "File << Manipulator" -- see File << Thing, -- print
    to a file
  * "Nothing << Manipulator" -- see File << Thing, --
    print to a file
  * "Manipulator Database" -- see Manipulator, -- the class
    of all file manipulators
  * "Manipulator File" -- see Manipulator, -- the class of
    all file manipulators
  * "Manipulator Nothing" -- see Manipulator, -- the class
    of all file manipulators
  * "new Manipulator from Function" -- see Manipulator, --
    the class of all file manipulators
  * "methods(Manipulator)" -- see methods, -- list methods
  * "Manipulator NetFile" -- see NetFile, -- the class of all
    net files
  * "NetFile << Manipulator" -- see NetFile, -- the class of all
    net files

For the programmer
==================

The object closeIn, is a manipulator.

closeOut -- close an output file
********************************

Description
===========

f << closeOut -- closes the output file f.
closeOut f -- closes the output file f.

Any buffered output is first written to the file, and the return value is an
integer, normally 0, or -1 on error, or the return status of the child process
in case the file was a pipe.

If the file was open only for output, then close, is easier to use
and has the same effect.

If the file was open for both input and output, it remains open for input.

Ways to use closeOut:
=====================

  * "File << Manipulator" -- see File << Thing, -- print
    to a file
  * "Nothing << Manipulator" -- see File << Thing, --
    print to a file
  * "Manipulator Database" -- see Manipulator, -- the class
    of all file manipulators
  * "Manipulator File" -- see Manipulator, -- the class of
    all file manipulators
  * "Manipulator Nothing" -- see Manipulator, -- the class
    of all file manipulators
  * "new Manipulator from Function" -- see Manipulator, --
    the class of all file manipulators
  * "methods(Manipulator)" -- see methods, -- list methods
  * "Manipulator NetFile" -- see NetFile, -- the class of all
    net files
  * "NetFile << Manipulator" -- see NetFile, -- the class of all
    net files

For the programmer
==================

The object closeOut, is a manipulator.

codim -- compute the codimension
********************************

See also
========

  * dim -- compute the Krull dimension

Ways to use codim:
==================

  * "codim(BettiTally)" -- see BettiTally, -- the class of
    all Betti tallies
  * codim(CoherentSheaf) (Varieties), --
    codimension of the support of a coherent sheaf on a projective variety
  * codim(Ideal) -- compute the codimension
  * codim(Module) -- codimension of the support of a
    module
  * codim(MonomialIdeal) -- compute the
    codimension
  * "codim(PolynomialRing)" -- see codim(QuotientRing),
    -- compute the codimension
  * codim(QuotientRing) -- compute the
    codimension
  * codim(Variety) (Varieties) -- codimension of a
    variety

For the programmer
==================

The object codim, is a method function with options.

codim(Ideal) -- compute the codimension
***************************************

Synopsis
========

  * Function: codim,
  * Usage:
        codim I
  * Inputs:
      * I
  * Optional inputs,:
      * Generic, => ..., default
        value false,
  * Outputs:
      * an integer, dim(R) - dim(R/I), where R is the ring
        containing I.

Description
===========

When R is equidimensional, this quantity is the codimension of the ideal I.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a..e];                                                       |
+-----------------------------------------------------------------------------+
|i2 : I = monomialCurveIdeal(R,{2,3,5,7})                                     |
|                                                                             |
|             2                               2     2    3           3      2 |
|o2 = ideal (d  - c*e, b*d - a*e, b*c - a*d, c d - b e, c  - a*b*e, b  - a*c )|
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : J = ideal presentation singularLocus(R/I);                              |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : codim J                                                                 |
|                                                                             |
|o4 = 4                                                                       |
+-----------------------------------------------------------------------------+
|i5 : radical J                                                               |
|                                                                             |
|o5 = ideal (d, c, b, a*e)                                                    |
|                                                                             |
|o5 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
The following may not be the expected result, because the ring is not
equidimensional.
+------------------------------------------+
|i6 : R = QQ[x,y]/(ideal(x,y) * ideal(x-1))|
|                                          |
|o6 = R                                    |
|                                          |
|o6 : QuotientRing                         |
+------------------------------------------+
|i7 : codim ideal(x,y)                     |
|                                          |
|o7 = 1                                    |
+------------------------------------------+

See also
========

  * dim(Ideal) -- compute the Krull dimension
  * dim(MonomialIdeal) -- compute the Krull dimension
  * codim(MonomialIdeal) -- compute the
    codimension

Ways to use this method:
========================

  * codim(Ideal) -- compute the codimension

codim(Ideal,Generic=>...)
*************************

Synopsis
========

  * Usage:
        codim(...,Generic=>true)
  * Consequences:
      * Allows the computation of the codimension to proceed without an error
        message, even if the ring is defined over the integers.  The
        computation proceeds by effectively tensoring first with the rational
        numbers.

Further information
===================

  * Default value: false,
  * Method: codim(Ideal), -- compute the codimension
  * Option key: Generic, -- an optional argument

Functions with optional argument named Generic:
===============================================

  * codim(CoherentSheaf,Generic=>...) (missing documentation)
  * codim(Ideal,Generic=>...)
  * "codim(Module,Generic=>...)"
  * "codim(PolynomialRing,Generic=>...)"
  * "codim(QuotientRing,Generic=>...)"
  * codim(MonomialIdeal,Generic=>...) (missing documentation)
  * codim(Variety,Generic=>...) (missing documentation)

codim(MonomialIdeal) -- compute the codimension
***********************************************

Synopsis
========

  * Function: codim,
  * Usage:
        codim I
  * Inputs:
      * I
  * Optional inputs,:
      * Generic (missing documentation) => ..., default value false,
  * Outputs:
      * an integer,

Description
===========

Computes the codimension of the monomial ideal I.
+----------------------------------+
|i1 : R = ZZ/101[a..e];            |
+----------------------------------+
|i2 : codim monomialIdeal (b,c,d)  |
|                                  |
|o2 = 3                            |
+----------------------------------+
|i3 : codim monomialIdeal (b^3,c^2)|
|                                  |
|o3 = 2                            |
+----------------------------------+

See also
========

  * dim(Ideal) -- compute the Krull dimension
  * dim(MonomialIdeal) -- compute the Krull dimension
  * codim(Ideal) -- compute the codimension

Ways to use this method:
========================

  * codim(MonomialIdeal) -- compute the
    codimension

codim(QuotientRing) -- compute the codimension
**********************************************

Synopsis
========

  * Function: codim,
  * Usage:
        codim R
  * Inputs:
      * R
  * Optional inputs,:
      * Generic, => ..., default
        value false,
  * Outputs:
      * an integer, the codimension of R

Description
===========

Computes the codimension of the presentation ideal of R over its ambient
polynomial ring.
+------------------------------------------+
|i1 : R = QQ[x,y]/(ideal(x,y) * ideal(x-1))|
|                                          |
|o1 = R                                    |
|                                          |
|o1 : QuotientRing                         |
+------------------------------------------+
|i2 : codim R                              |
|                                          |
|o2 = 1                                    |
+------------------------------------------+
However, the following may not be the expected result.
+------------------------------------------+
|i3 : R = QQ[x,y]/(ideal(x,y) * ideal(x-1))|
|                                          |
|o3 = R                                    |
|                                          |
|o3 : QuotientRing                         |
+------------------------------------------+
|i4 : codim R                              |
|                                          |
|o4 = 1                                    |
+------------------------------------------+
|i5 : codim (R/x)                          |
|                                          |
|o5 = 2                                    |
+------------------------------------------+

See also
========

  * dim(QuotientRing) -- compute the Krull dimension

Ways to use this method:
========================

  * "codim(PolynomialRing)"
  * codim(QuotientRing) -- compute the
    codimension

coefficient -- coefficient of a monomial
****************************************

Synopsis
========

  * Usage:
        coefficient(m,f)
  * Inputs:
      * m, a ring element, a monomial
      * f, a ring element, in the same ring R as m
  * Outputs:
      * a ring element, the coefficient of the monomial m
        in f as an element of the coefficient ring of R

Description
===========

+-----------------------------------------------------------------------------+
|i1 : R = GF(25,Variable=>a)[x,y,z];                                          |
+-----------------------------------------------------------------------------+
|i2 : f = ((a+1)*x+a*y+a^2*z)^2                                               |
|                                                                             |
|                2                          2                                 |
|o2 = (- 2a - 1)x  + (- a + 1)x*y + (a - 2)y  + 2x*z + (- 2a + 1)y*z + (2a +  |
|     ------------------------------------------------------------------------|
|        2                                                                    |
|     2)z                                                                     |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+
|i3 : coefficient(y^2,f)                                                      |
|                                                                             |
|o3 = a - 2                                                                   |
|                                                                             |
|o3 : GF 25                                                                   |
+-----------------------------------------------------------------------------+
The returned value is an element of the coefficient ring, even in the case when
that ring is another polynomial ring.
+-------------------------------+
|i4 : S = R[r,s,t];             |
+-------------------------------+
|i5 : coefficient(r,a*x*(r+a*s))|
|                               |
|o5 = a*x                       |
|                               |
|o5 : R                         |
+-------------------------------+

See also
========

  * coefficients -- monomials and their coefficients
  * monomials -- matrix of monomials in a ring element or
    matrix
  * coefficientRing -- get the coefficient ring

For the programmer
==================

The object coefficient, is a method function.

coefficientRing -- get the coefficient ring
*******************************************

Synopsis
========

  * Usage:
        coefficientRing R
  * Inputs:
      * R, a ring,
  * Outputs:
      * a ring, the coefficient ring of R

Description
===========

If R is a polynomial ring, then the coefficient ring is the base ring from
which the coefficients are drawn.  If R is constructed from a polynomial ring
as a quotient ring or a fraction ring or a sequence of such operations, then
the original coefficient ring is returned.
+-------------------------------------------+
|i1 : coefficientRing(ZZ/101[a][b])         |
|                                           |
|      ZZ                                   |
|o1 = ---[a]                                |
|     101                                   |
|                                           |
|o1 : PolynomialRing                        |
+-------------------------------------------+
|i2 : ultimate(coefficientRing,ZZ/101[a][b])|
|                                           |
|      ZZ                                   |
|o2 = ---                                   |
|     101                                   |
|                                           |
|o2 : QuotientRing                          |
+-------------------------------------------+

See also
========

  * ultimate -- ultimate value for an iteration
  * baseRings -- store the list of base rings of a ring

Ways to use coefficientRing:
============================

  * "coefficientRing(Ring)"

For the programmer
==================

The object coefficientRing, is a method function.

coefficients -- monomials and their coefficients
************************************************

Synopsis
========

  * Usage:
        (M,C) = coefficients f
  * Inputs:
      * f, a one-row Matrix, with n columns, say, or a
        RingElement, to be interpreted as a one-by-one matrix.
        (A future implementation will handle matrices with more than one row.)
  * Optional inputs,:
      * Variables => a list, default value null, a list v of
        variables. If a value for this option is not specified, all of the
        (top-level) variables are used.
      * Monomials => ..., default value null, a list or one-row matrix of
        monomials, each of which is formed using just variables in v.
  * Outputs:
      * M, a matrix, either the value of the Monomials option,
        if specified (converted to a one-row matrix, if necessary), or a
        one-row matrix of those monomials appearing in f that involve just
        variables in v, in descending order.  Let m denote the number of
        columns it has.
      * C, a matrix, the m by n matrix C such that C_(i,j) is
        the coefficient in f_(0,j) of the monomial M_(0,i). In other words, C
        is the unique matrix not involving the (specified) variables such that
        M*C == f, unless a value was specified for the Monomials option that
        did not include all the monomials in the variables v used by f

Description
===========

+---------------------------------+
|i1 : R = QQ[a,b,c,d,e,f][x,y];   |
+---------------------------------+
|i2 : F = a*x^2+b*x*y+c*y^2       |
|                                 |
|        2              2         |
|o2 = a*x  + b*x*y + c*y          |
|                                 |
|o2 : R                           |
+---------------------------------+
|i3 : (M,C) = coefficients F      |
|                                 |
|o3 = (| x2 xy y2 |, {2, 0} | a |)|
|                    {2, 0} | b | |
|                    {2, 0} | c | |
|                                 |
|o3 : Sequence                    |
+---------------------------------+
The resulting matrices have the following property.
+---------------------+
|i4 : M*C === matrix F|
|                     |
|o4 = true            |
+---------------------+
The Sylvester matrix of two generic quadratic forms:
+----------------------------------------------------------------+
|i5 : G = d*x^2+e*x*y+f*y^2                                      |
|                                                                |
|        2              2                                        |
|o5 = d*x  + e*x*y + f*y                                         |
|                                                                |
|o5 : R                                                          |
+----------------------------------------------------------------+
|i6 : P = matrix{{x*F,y*F,x*G,y*G}}                              |
|                                                                |
|o6 = | ax3+bx2y+cxy2 ax2y+bxy2+cy3 dx3+ex2y+fxy2 dx2y+exy2+fy3 ||
|                                                                |
|             1      4                                           |
|o6 : Matrix R  <-- R                                            |
+----------------------------------------------------------------+
|i7 : (M,C) = coefficients P                                     |
|                                                                |
|o7 = (| x3 x2y xy2 y3 |, {3, 0} | a 0 d 0 |)                    |
|                         {3, 0} | b a e d |                     |
|                         {3, 0} | c b f e |                     |
|                         {3, 0} | 0 c 0 f |                     |
|                                                                |
|o7 : Sequence                                                   |
+----------------------------------------------------------------+
|i8 : M*C === P                                                  |
|                                                                |
|o8 = true                                                       |
+----------------------------------------------------------------+
We may give the monomials directly.  This is useful if we are taking
coefficients of several elements or matrices, and need a consistent choice of
monomials.
+--------------------------------------------------------------+
|i9 : (M,C) = coefficients(P, Monomials=>{x^3,y^3,x^2*y,x*y^2})|
|                                                              |
|o9 = (| x3 y3 x2y xy2 |, {3, 0} | a 0 d 0 |)                  |
|                         {3, 0} | 0 c 0 f |                   |
|                         {3, 0} | b a e d |                   |
|                         {3, 0} | c b f e |                   |
|                                                              |
|o9 : Sequence                                                 |
+--------------------------------------------------------------+
If not all of the monomials are used, no error is signaled, but M*C == P no
longer holds.
+---------------------------------------------------+
|i10 : (M,C) = coefficients(P, Monomials=>{x^3,y^3})|
|                                                   |
|o10 = (| x3 y3 |, {3, 0} | a 0 d 0 |)              |
|                  {3, 0} | 0 c 0 f |               |
|                                                   |
|o10 : Sequence                                     |
+---------------------------------------------------+
|i11 : M*C == P                                     |
|                                                   |
|o11 = false                                        |
+---------------------------------------------------+

See also
========

  * monomials -- matrix of monomials in a ring element or
    matrix
  * content -- the content of a polynomial
  * exponents -- the exponents of a polynomial
  * listForm -- convert to list form
  * standardForm -- convert to standard form

Ways to use coefficients:
=========================

  * "coefficients(Matrix)"
  * "coefficients(RingElement)"

For the programmer
==================

The object coefficients, is a method function with options.

Cofactor
********

Description
===========

This symbol is used as one of the permissible values for the strategy option in
function dealing with determinants.

See also
========

  * exteriorPower(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * minors(...,Strategy=>...)
    -- choose between Bareiss,
    Cofactor and Dynamic algorithms
  * determinant(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms

For the programmer
==================

The object Cofactor, is a symbol.

cohomology -- general cohomology functor
****************************************

Description
===========

cohomology -- a method name available for computing expressions of the forms
HH^i(X) and HH^i(M,N).

If it is intended that i be of class ZZ, M be of class A, and N be
of class B, then the method can be installed with
     cohomology(ZZ, A, B) := opts -> (i,M,N) -> ...

See also
========

  * homology -- general homology functor
  * HH -- general homology and cohomology functor
  * ScriptedFunctor -- the class of all scripted
    functors

Ways to use cohomology:
=======================

  * HH^ZZ ChainComplex -- cohomology of a chain
    complex
  * HH^ZZ ChainComplexMap -- cohomology of a
    chain complex map
  * HH^ZZ Module -- local cohomology of a module
  * HH^ZZ SheafMap (missing documentation)
  * HH^ZZ SheafOfRings (Varieties) -- cohomology of a
    sheaf of rings on a projective variety
  * HH^ZZ SumOfTwists (Varieties) -- coherent sheaf
    cohomology module
  * HH^ZZ(AffineVariety,CoherentSheaf) (missing documentation)
  * "HH^ZZ CoherentSheaf" -- see HH^ZZ(ProjectiveVariety,CoherentSheaf) (Varieties),
    -- cohomology of a
    coherent sheaf on a projective variety
  * HH^ZZ(ProjectiveVariety,CoherentSheaf) (Varieties)
    -- cohomology of a
    coherent sheaf on a projective variety
  * HH^ZZ(ProjectiveVariety,SheafMap) (missing documentation)
  * HH^ZZ(ProjectiveVariety,SumOfTwists) (missing documentation)
  * HH^ZZ(Variety,SheafOfRings) (missing documentation)

For the programmer
==================

The object cohomology, is a method function with options.

coimage -- coimage of a map
***************************

Synopsis
========

  * Usage:
        coimage f
  * Inputs:
      * f, a ring map, a matrix, a chain complex map,
        or a graded module map, from A to B,
  * Outputs:
      * The object A/(kernel f)

Description
===========

In each of these cases, the coimage is isomorphic to the image, but the coimage
is presented as a quotient object of the source of the map, whereas the image
is presented as a subobject of the target of the map.  For rings, we can
represent quotient rings, but not subrings, in Macaulay2. Hence, for ring maps,
we can compute the coimage, but not the image.

The isomorphism between coimage and image is not always obvious, as the
following example shows.

+------------------------------------------------+
|i1 : R = QQ[a..d];                              |
+------------------------------------------------+
|i2 : M = matrix{{a^3,b^3-c^3,a*b*c,a*(b^2-c^2)}}|
|                                                |
|o2 = | a3 b3-c3 abc ab2-ac2 |                   |
|                                                |
|             1      4                           |
|o2 : Matrix R  <-- R                            |
+------------------------------------------------+
|i3 : image M                                    |
|                                                |
|o3 = image | a3 b3-c3 abc ab2-ac2 |             |
|                                                |
|                             1                  |
|o3 : R-module, submodule of R                   |
+------------------------------------------------+
|i4 : coimage M                                  |
|                                                |
|o4 = cokernel {3} | 0    -bc 0     -b2+c2 |     |
|              {3} | a    0   0     0      |     |
|              {3} | b-c  a2  b2-c2 0      |     |
|              {3} | -b-c 0   -bc   a2     |     |
|                                                |
|                            4                   |
|o4 : R-module, quotient of R                    |
+------------------------------------------------+
|i5 : kernel M                                   |
|                                                |
|o5 = image {3} | 0    -bc 0     -b2+c2 |        |
|           {3} | a    0   0     0      |        |
|           {3} | b-c  a2  b2-c2 0      |        |
|           {3} | -b-c 0   -bc   a2     |        |
|                                                |
|                             4                  |
|o5 : R-module, submodule of R                   |
+------------------------------------------------+

See also
========

  * image -- image of a map
  * cokernel -- cokernel of a map of modules, graded modules,
    or chaincomplexes
  * kernel -- kernel of a ringmap, matrix, or chain complex
  * comodule -- submodule to quotient module

Ways to use coimage:
====================

  * "coimage(ChainComplexMap)"
  * "coimage(GradedModuleMap)"
  * "coimage(Matrix)"
  * "coimage(RingMap)"
  * coimage(SheafMap) (missing documentation)

For the programmer
==================

The object coimage, is a method function.

cokernel -- cokernel of a map of modules, graded modules, or chaincomplexes
***************************************************************************

Synopsis
========

  * Usage:
        cokernel f
  * Inputs:
      * f : A --> Ba matrix, a chain complex map,
        a ring element, or a graded module map,
  * Outputs:
      * the object B/(image f)

Description
===========

coker is a synonym for cokernel.

The generators of the cokernel are provided by the generators of the target of
f.  In other words, cover target f and cover cokernel f are equal.

An argument f that is a RingElement, is interpreted as a one
by one matrix.

+-------------------------------------------------+
|i1 : R = ZZ[a..d];                               |
+-------------------------------------------------+
|i2 : M = cokernel matrix{{2*a-b,3*c-5*d,a^2-b-3}}|
|                                                 |
|o2 = cokernel | 2a-b 3c-5d a2-b-3 |              |
|                                                 |
|                            1                    |
|o2 : R-module, quotient of R                     |
+-------------------------------------------------+
If f is a matrix, and the target of f is a submodule, the resulting module will
be a subquotient, module.
+-----------------------------------------------------------------------------+
|i3 : f = map(a*M, M, a^3+a^2*b)                                              |
|                                                                             |
|o3 = {1} | a+10b+18 |                                                        |
|                                                                             |
|o3 : Matrix                                                                  |
+-----------------------------------------------------------------------------+
|i4 : (target f,source f)                                                     |
|                                                                             |
|o4 = (subquotient (| a |, | 2a-b 3c-5d a2-b-3 |), cokernel | 2a-b 3c-5d      |
|     ------------------------------------------------------------------------|
|     a2-b-3 |)                                                               |
|                                                                             |
|o4 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i5 : N = cokernel f                                                          |
|                                                                             |
|o5 = subquotient (| a |, | a2+10ab+18a 2a-b 3c-5d a2-b-3 |)                  |
|                                                                             |
|                               1                                             |
|o5 : R-module, subquotient of R                                              |
+-----------------------------------------------------------------------------+
|i6 : minimalPresentation N                                                   |
|                                                                             |
|o6 = cokernel | 81 27d 3c-5d 3b-18 a+b-9 9d2 bd-6d b2-b-30 3d3 d4 |          |
|                                                                             |
|                            1                                                |
|o6 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+

See also
========

  * cover -- get the covering free module
  * image -- image of a map
  * kernel -- kernel of a ringmap, matrix, or chain complex
  * coimage -- coimage of a map
  * comodule -- submodule to quotient module
  * minimalPresentation -- compute a minimal
    presentation
  * matrices to and from modules, --
    including kernel, cokernel and image

Ways to use cokernel:
=====================

  * "cokernel(ChainComplexMap)"
  * "cokernel(GradedModuleMap)"
  * "cokernel(Matrix)"
  * "cokernel(RingElement)"
  * cokernel(SheafMap) (missing documentation)

For the programmer
==================

The object cokernel, is a method function.

columnAdd -- add a multiple of one column to another
****************************************************

Synopsis
========

  * Usage:
        columnAdd(m,i,a,j)
  * Inputs:
      * m, a mutable matrix,
      * i, an integer,
      * a, a ring element, in the same ring as m
      * j, an integer,
  * Consequences:
      * The i th column of m is modified by adding a times the j th column of m

Description
===========

+---------------------------------------------+
|i1 : R = ZZ[a..f];                           |
+---------------------------------------------+
|i2 : m = mutableMatrix genericMatrix(R,a,2,3)|
|                                             |
|o2 = | a c e |                               |
|     | b d f |                               |
|                                             |
|o2 : MutableMatrix                           |
+---------------------------------------------+
|i3 : columnAdd(m,0,c,1)                      |
|                                             |
|o3 = | c2+a c e |                            |
|     | cd+b d f |                            |
|                                             |
|o3 : MutableMatrix                           |
+---------------------------------------------+
|i4 : m                                       |
|                                             |
|o4 = | c2+a c e |                            |
|     | cd+b d f |                            |
|                                             |
|o4 : MutableMatrix                           |
+---------------------------------------------+

See also
========

  * mutable matrices
  * row and column operations

Ways to use columnAdd:
======================

  * "columnAdd(MutableMatrix,ZZ,Number,ZZ)"
  * "columnAdd(MutableMatrix,ZZ,RingElement,ZZ)"

For the programmer
==================

The object columnAdd, is a method function.

columnate -- arrange strings in columns
***************************************

Description
===========

columnate(w,s) -- arranges the strings in the list s in columns, returning a
Net, suitable for output to a terminal with a linewidth of w.

+-----------------------------------------------+
|i1 : columnate(12, characters ascii (65 .. 90))|
|                                               |
|o1 = A F K P U Z                               |
|     B G L Q V                                 |
|     C H M R W                                 |
|     D I N S X                                 |
|     E J O T Y                                 |
+-----------------------------------------------+

For the programmer
==================

The object columnate, is a function closure.

columnMult -- multiply a column by a ring element
*************************************************

Synopsis
========

  * Usage:
        columnMult(m,i,a)
  * Inputs:
      * m, a mutable matrix,
      * i, an integer,
      * a, a ring element, in the same ring as m
  * Consequences:
      * The i th column of m is modified by multiplying it by a

Description
===========

+---------------------------------------------+
|i1 : R = ZZ[a..f]                            |
|                                             |
|o1 = R                                       |
|                                             |
|o1 : PolynomialRing                          |
+---------------------------------------------+
|i2 : m = mutableMatrix genericMatrix(R,a,2,3)|
|                                             |
|o2 = | a c e |                               |
|     | b d f |                               |
|                                             |
|o2 : MutableMatrix                           |
+---------------------------------------------+
|i3 : columnMult(m,0,c)                       |
|                                             |
|o3 = | ac c e |                              |
|     | bc d f |                              |
|                                             |
|o3 : MutableMatrix                           |
+---------------------------------------------+
|i4 : m                                       |
|                                             |
|o4 = | ac c e |                              |
|     | bc d f |                              |
|                                             |
|o4 : MutableMatrix                           |
+---------------------------------------------+

See also
========

  * mutable matrices
  * row and column operations

Ways to use columnMult:
=======================

  * "columnMult(MutableMatrix,ZZ,Number)"
  * "columnMult(MutableMatrix,ZZ,RingElement)"

For the programmer
==================

The object columnMult, is a method function.

columnPermute -- permute some columns
*************************************

Synopsis
========

  * Usage:
        columnPermute(m,i,{...})
  * Inputs:
      * m, a mutable matrix,
      * i, an integer, starting column
      * a list of integers, denoting a permutation of 0..d, for some number d
  * Consequences:
      * If the permutation is {p0,p1,...,pd}, then m is modified so that the
        i+j column becomes the i+pj column of the original matrix, for j=0..d

Description
===========

+-------------------------------------------------------+
|i1 : m = mutableMatrix map(ZZ^5,ZZ^6, (i,j) -> 100*i+j)|
|                                                       |
|o1 = | 0   1   2   3   4   5   |                       |
|     | 100 101 102 103 104 105 |                       |
|     | 200 201 202 203 204 205 |                       |
|     | 300 301 302 303 304 305 |                       |
|     | 400 401 402 403 404 405 |                       |
|                                                       |
|o1 : MutableMatrix                                     |
+-------------------------------------------------------+
|i2 : columnPermute(m,1,{2,0,1})                        |
|                                                       |
|o2 = | 0   3   1   2   4   5   |                       |
|     | 100 103 101 102 104 105 |                       |
|     | 200 203 201 202 204 205 |                       |
|     | 300 303 301 302 304 305 |                       |
|     | 400 403 401 402 404 405 |                       |
|                                                       |
|o2 : MutableMatrix                                     |
+-------------------------------------------------------+

See also
========

  * mutable matrices
  * row and column operations

Ways to use columnPermute:
==========================

  * "columnPermute(MutableMatrix,ZZ,List)"

For the programmer
==================

The object columnPermute, is a method function.

columnRankProfile -- find the column rank profile of a mutable matrix
*********************************************************************

Synopsis
========

  * Usage:
        columnRankProfile m
  * Inputs:
      * m, a mutable matrix, over RR, or
        CC,
  * Outputs:
      * a list, the lexicographically smallest list of indices of
        linearly independent columns generating the column space of m

Description
===========

+----------------------------------------------------------------------------+
|i1 : columnRankProfile transpose mutableMatrix {{1,2,3}, {0,0,0.}, {3,4,5} }|
|                                                                            |
|o1 = {0, 2}                                                                 |
|                                                                            |
|o1 : List                                                                   |
+----------------------------------------------------------------------------+

See also
========

  * rowRankProfile -- find the row rank profile of a
    mutable matrix

Ways to use columnRankProfile:
==============================

  * "columnRankProfile(MutableMatrix)"

For the programmer
==================

The object columnRankProfile, is a method function.

columnSwap -- interchange columns
*********************************

Synopsis
========

  * Usage:
        columnSwap(m,i,j)
  * Inputs:
      * m, a mutable matrix,
      * i, an integer,
      * j, an integer,
  * Consequences:
      * Interchanges the i th and j th columns of m

Description
===========

+----------------------------------------------+
|i1 : m = mutableMatrix matrix{{1,2,3},{4,5,6}}|
|                                              |
|o1 = | 1 2 3 |                                |
|     | 4 5 6 |                                |
|                                              |
|o1 : MutableMatrix                            |
+----------------------------------------------+
|i2 : columnSwap(m,0,1)                        |
|                                              |
|o2 = | 2 1 3 |                                |
|     | 5 4 6 |                                |
|                                              |
|o2 : MutableMatrix                            |
+----------------------------------------------+
|i3 : m                                        |
|                                              |
|o3 = | 2 1 3 |                                |
|     | 5 4 6 |                                |
|                                              |
|o3 : MutableMatrix                            |
+----------------------------------------------+

See also
========

  * mutable matrices
  * row and column operations

Ways to use columnSwap:
=======================

  * "columnSwap(MutableMatrix,ZZ,ZZ)"

For the programmer
==================

The object columnSwap, is a method function.

Command -- the class of all commands
************************************

Synopsis
========

  * Usage:
        Command g
  * Inputs:
      * g, a function or a string
  * Outputs:
      * a new command that will evaluate g() if g is a function, and will
        evaluate run g if g is a string

Description
===========

A command behaves as a function does if it is followed by an adjacent
expression that can serve as its argument or argument list.  In addition, if it
appears as the value of an expression typed by the user at top level (i.e., not
in a file), then it gets executed with empty argument list.
+----------------------------------+
|i1 : (f = Command ( () -> 2^30 );)|
+----------------------------------+
|i2 : f                            |
|                                  |
|o2 = 1073741824                   |
+----------------------------------+
|i3 : (c = Command "date";)        |
+----------------------------------+
|i4 : c                            |
|Fri Nov  1 10:22:51 AM EDT 2024   |
|                                  |
|o4 = 0                            |
+----------------------------------+

See also
========

  * run -- run an external command
  * AfterEval -- top level method applied after evaluation

Methods that use a command:
===========================

  * ? Command (missing documentation)
  * "code(Command)" -- see code, -- display source code
  * "Command Thing"
  * Command \ Set (missing documentation)
  * locate(Command) (missing documentation)
  * "methodOptions(Command)" -- see methodOptions(Function),
    -- recover the options used when a method
    function was created
  * "methods(Command)" -- see methods, -- list methods
  * options(Command) -- get optional arguments and
    default values of functions and methods
  * Set / Command (missing documentation)
  * /// Command \\ Thing /// -- see Thing // Function,
    -- apply a function
  * "Thing // Command" -- see Thing // Function, --
    apply a function
  * /// Command \ String /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// Command \ VirtualTally /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// Command \ VisibleList /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "List / Command" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "String / Command" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "VirtualTally / Command" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "VisibleList / Command" -- see VisibleList / Function,
    -- apply a function to elements of a list

Protected objects of class Command:
===================================

  * cite (PackageCitations) -- obtain bibtex citations for
    Macaulay2 packages
  * clearAll -- forget everything
  * clearOutput -- forget output values
  * "copyright" -- see Copyright and license,
  * edit -- edit source code
  * exit -- exit the program
  * help -- view documentation nodes
  * infoHelp -- view documentation in Info format
  * listLocalSymbols -- display of local symbols and
    their values
  * listUserSymbols -- display the user's symbols
  * profileSummary -- display profiling data
  * quit -- quit the program
  * restart -- restart Macaulay2
  * showClassStructure -- display class structure
  * showStructure -- display parent structure
  * showUserStructure -- show parent structure for
    those types defined by user
  * viewHelp -- view online documentation in a web browser

For the programmer
==================

The object Command, is a self initializing type,
with ancestor classes BasicList, <
Thing.

commandInterpreter -- the top level command interpreter
*******************************************************

Synopsis
========

  * Usage:
        commandInterpreter f
  * Inputs:
      * f, () or a dictionary, a symbol, an
        instance of the type Pseudocode, or a
        function,
  * Consequences:
      * the top level command interpreter will be called with the symbols in
        the lexical scope of f visible to the user.

Description
===========

One more i will be added to prompt each time the command interpreter is
entered.  To leave it, type end or the end of file character.
+--------------------------+
|i1 : f = (x -> y -> 11) 13|
|                          |
|o1 = f                    |
|                          |
|o1 : FunctionClosure      |
+--------------------------+
|i2 : commandInterpreter f |
+--------------------------+
|ii3 : x                   |
|                          |
|oo3 = 13                  |
+--------------------------+
|ii4 : end                 |
+--------------------------+
|i5 : x                    |
|                          |
|o5 = x                    |
|                          |
|o5 : Symbol               |
+--------------------------+
This facility is useful as a debugging tool, and is used by the standard
debugger.

For the programmer
==================

The object commandInterpreter, is a compiled function.

commonest -- the most common elements of a list or tally
********************************************************

Synopsis
========

  * Usage:
        commonest A
  * Inputs:
      * A, a visible list,
  * Outputs:
      * L, a list, a list of the elements of A with the most
        repetitions

Description
===========

If a single element is the most common, a list of length one is the output.

+--------------------------------------+
|i1 : commonest {a,a,a,a,b,b,b,c,c,d,e}|
|                                      |
|o1 = {a}                              |
|                                      |
|o1 : List                             |
+--------------------------------------+

In the case of a tie, all commonest elements are returned.

+---------------------------------------------------+
|i2 : A = {a,a,a,a,b,b,b,b,c,c,c,c,d,e}; commonest A|
|                                                   |
|o3 = {c, a, b}                                     |
|                                                   |
|o3 : List                                          |
+---------------------------------------------------+

commonest works on Tally,s and Set,s as well.

+------------------------+
|i4 : T = tally A        |
|                        |
|o4 = Tally{a => 4}      |
|           b => 4       |
|           c => 4       |
|           d => 1       |
|           e => 1       |
|                        |
|o4 : Tally              |
+------------------------+
|i5 : commonest T        |
|                        |
|o5 = {c, a, b}          |
|                        |
|o5 : List               |
+------------------------+
|i6 : S = set A          |
|                        |
|o6 = set {c, d, e, a, b}|
|                        |
|o6 : Set                |
+------------------------+
|i7 : commonest S        |
|                        |
|o7 = {c, d, e, a, b}    |
|                        |
|o7 : List               |
+------------------------+

(Since every element of a set is unique, it is unclear why one would need
commonest(Set).)

See also
========

  * number -- count how many elements of a list satisfy a
    condition
  * same -- whether everything in a list is the same
  * set -- make a set
  * tally -- tally the elements of a list, sequence, array, or
    string
  * unique -- eliminate duplicates from a list
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use commonest:
======================

  * "commonest(Set)"
  * "commonest(Tally)"
  * "commonest(VisibleList)"

For the programmer
==================

The object commonest, is a method function with a single argument.

commonRing -- find smallest containing ring
*******************************************

Synopsis
========

  * Usage:
        commonRing v
  * Inputs:
      * v, a list of numbers, ring elements, matrices, or things with rings,
        see
      * ring
  * Outputs:
      * a ring, the smallest ring to which all members of the list
        can be promoted

Description
===========

+---------------------------------------------+
|i1 : commonRing {1,2/3}                      |
|                                             |
|o1 = QQ                                      |
|                                             |
|o1 : Ring                                    |
+---------------------------------------------+
|i2 : commonRing {1,2.}                       |
|                                             |
|o2 = RR                                      |
|       53                                    |
|                                             |
|o2 : RealField                               |
+---------------------------------------------+
|i3 : commonRing {1,2p100,matrix{{3p200}}}    |
|                                             |
|o3 = RR                                      |
|       100                                   |
|                                             |
|o3 : RealField                               |
+---------------------------------------------+
|i4 : R = RR[x];                              |
+---------------------------------------------+
|i5 : commonRing {1,2p100,matrix{{3p200}},0_R}|
|                                             |
|o5 = R                                       |
|                                             |
|o5 : PolynomialRing                          |
+---------------------------------------------+

Ways to use commonRing:
=======================

  * "commonRing(List)"

For the programmer
==================

The object commonRing, is a method function.

comodule -- submodule to quotient module
****************************************

Synopsis
========

  * Usage:
        comodule M
        quotient M
  * Inputs:
      * M, a module, or an ideal,
  * Outputs:
      * a module, the quotient module N/M, if M is given as a
        submodule $M \subset N$, where N is either a free module or a quotient
        of a free module.

Description
===========

+-----------------------------+
|i1 : R = QQ[a..d];           |
+-----------------------------+
|i2 : I = ideal(a,b,c,d^3);   |
|                             |
|o2 : Ideal of R              |
+-----------------------------+
|i3 : comodule I              |
|                             |
|o3 = cokernel | a b c d3 |   |
|                             |
|                            1|
|o3 : R-module, quotient of R |
+-----------------------------+

See also
========

  * image -- image of a map
  * cokernel -- cokernel of a map of modules, graded modules,
    or chaincomplexes
  * kernel -- kernel of a ringmap, matrix, or chain complex

Ways to use comodule:
=====================

  * "comodule(Ideal)"
  * "comodule(Module)"

For the programmer
==================

The object comodule, is a method function.

compactMatrixForm -- global flag for compact printing
*****************************************************

Synopsis
========

  * Usage:
        compactMatrixForm = x
  * Consequences:
      * changes the display of matrices

Description
===========

compactMatrixForm is a global flag that specifies whether to display matrices
in compact form.

The default value is true.  The compact form is the form used by Macaulay, in
which the multiplication and exponentiation operators are suppressed from the
notation.
+--------------------------------------------------+
|i1 : R = ZZ[x,y];                                 |
+--------------------------------------------------+
|i2 : f = random(R^{2},R^2)                        |
|                                                  |
|o2 = {-2} | 8x2+xy+3y2 7x2+8xy+3y2 |              |
|                                                  |
|             1      2                             |
|o2 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i3 : compactMatrixForm = false;                   |
+--------------------------------------------------+
|i4 : f                                            |
|                                                  |
|           |    2           2    2            2  ||
|o4 = {-2}  |  8x  + x*y + 3y   7x  + 8x*y + 3y   ||
|                                                  |
|             1      2                             |
|o4 : Matrix R  <-- R                              |
+--------------------------------------------------+

Caveat
======

This flag currently has no effect outside of Standard, output
mode.

For the programmer
==================

The object compactMatrixForm, is a Boolean value.

compareExchange -- compares and possibly exchanges the value of an atomic integer
*********************************************************************************

Synopsis
========

  * Usage:
        compareExchange(x, y, z)
  * Inputs:
      * x, an atomic integer,
      * y, an integer,
      * z, an integer,
  * Outputs:
      * a Boolean value,

Description
===========

The values of x and y are compared.  If they agree, then true, is
returned and the value of z is stored in x.  Otherwise, see false, is
returned.  This operation occurs atomically and is thread safe.

+-----------------------------+
|i1 : x = new AtomicInt       |
|                             |
|o1 = 0                       |
|                             |
|o1 : AtomicInt               |
+-----------------------------+
|i2 : compareExchange(x, 2, 3)|
|                             |
|o2 = false                   |
+-----------------------------+
|i3 : x                       |
|                             |
|o3 = 0                       |
|                             |
|o3 : AtomicInt               |
+-----------------------------+
|i4 : compareExchange(x, 0, 3)|
|                             |
|o4 = true                    |
+-----------------------------+
|i5 : x                       |
|                             |
|o5 = 3                       |
|                             |
|o5 : AtomicInt               |
+-----------------------------+

Ways to use compareExchange:
============================

  * "compareExchange(AtomicInt,ZZ,ZZ)"

For the programmer
==================

The object compareExchange, is a method function.

CompiledFunction -- the class of all compiled functions
*******************************************************

Description
===========

Compiled functions in Macaulay2 are written in a special purpose language,
translated to C during compilation and not available to general users.
+---------------------+
|i1 : class drop      |
|                     |
|o1 = CompiledFunction|
|                     |
|o1 : Type            |
+---------------------+

Methods that use a compiled function:
=====================================

  * frames(CompiledFunction) (missing documentation)
  * localDictionaries(CompiledFunction) (missing documentation)

Protected objects of class CompiledFunction:
============================================

  * "addCancelTask" -- see addCancelTask(Task,Task),
    -- specify that the completion of one task
    triggers the cancellation of another
  * "addDependencyTask" -- see addDependencyTask(Task,Task),
    -- schedule a task, but ensure that it
    will not run until another task finishes
  * "addStartTask" -- see addStartTask(Task,Task),
    -- schedule a task upon completion of
    another
  * alarm -- set an alarm
  * "ancestor" -- see ancestor(Type,Type), --
    whether one type is an ancestor of another
  * any -- whether any elements satisfy a specified condition
  * append -- add an element to the end of a list
  * apply -- apply a function to each element
  * applyKeys -- apply a function to each key in a hash table
  * applyPairs -- apply a function to each pair in a hash
    table
  * applyValues -- apply a function to each value in a hash
    table
  * ascii -- ASCII character conversion
  * "atEndOfFile" -- see atEndOfFile(File), --
    test for end of file
  * "cancelTask" -- see cancelTask(Task), -- stop a
    task
  * changeDirectory -- change the current working
    directory
  * characters -- get characters from a string
  * class -- class of an object
  * clearEcho -- turn off echoing
  * collectGarbage -- collect the garbage in memory
  * combine -- combine hash tables
  * commandInterpreter -- the top level command
    interpreter
  * concatenate -- join strings
  * connectionCount -- the number of connections
  * copy -- copy an object
  * cpuTime -- seconds of cpu time used since Macaulay2 began
  * createTask -- create a task
  * currentColumnNumber -- current column number of
    the current input file
  * currentDirectory -- current working directory
  * currentRowNumber -- current row number of the
    current input file
  * currentTime -- get the current time
  * deepSplice -- remove all levels of subsequences from a
    sequence or list
  * difference -- difference
  * disassemble -- disassemble a pseudocode or function
  * drop -- drop some elements from a list or sequence.
  * echoOff -- turn off echoing
  * echoOn -- turn on echoing
  * erase -- remove a global symbol
  * exec -- execute another program
  * fileExecutable
  * fileExists -- whether a file exists
  * fileLength -- the length of a file
  * fileMode -- set or get file mode
  * fileReadable
  * fileTime -- get or set file modified time
  * fileWritable
  * firstkey -- get the first key
  * flagLookup -- flag a symbol
  * fork -- fork the process
  * frames -- get the frames associated to a closure
  * functionBody -- get the body of a function
  * GCstats -- information about the status of the garbage
    collector
  * get -- get the contents of a file
  * getc -- get a byte
  * getenv -- get value of environment variable
  * getGlobalSymbol -- create a global symbol in a
    global dictionary
  * getIOThreadMode -- get I/O thread mode
  * getNetFile -- get the sequence of completed lines (nets)
    from a net file
  * groupID -- the process group identifier
  * hash -- hash code of an object
  * hashTable -- make a hash table
  * horizontalJoin -- join nets or strings horizontally
  * identity -- the identity function
  * installMethod -- install methods
  * instance -- whether something has a certain type
  * isANumber -- whether a number is not not-a-number
  * "isCanceled" -- see isCanceled(Task), --
    whether a task has been canceled
  * isDirectory -- whether a file is a directory
  * isGlobalSymbol -- whether a global symbol with a
    given name exists
  * "isInputFile" -- see isInputFile(File), --
    whether a file is open for input
  * "isListener" -- see isListener(File), --
    whether a file is open for listening
  * isMutable -- whether something may be modified
  * isOpen -- whether a file or database is open
  * "isOutputFile" -- see isOutputFile(File), --
    whether a file is open for output
  * "isReady" -- see isReady(File), -- whether a file
    has data available for reading
  * isRegularFile -- whether a file is a regular file
  * join -- join lists, sequences, and iterable objects
  * keys -- keys used in a hash table, dictionary, or database
  * kill -- kill a process
  * left -- left endpoint of an interval
  * limitFiles
  * limitProcesses
  * "linkFile" -- see linkFile(String,String),
    -- make a new link to a file
  * localDictionaries -- get local dictionaries
  * lookup -- look up methods
  * lookupCount -- reference count for a symbol
  * merge -- merge two hash tables
  * mergePairs -- merge sorted lists of pairs
  * midpoint -- midpoint of an interval
  * mingle -- mingle elements of several lists
  * minimizeFilename -- minimize a file name
  * minus -- additive inverse
  * mkdir
  * nanosleep -- sleep for a given number of nanoseconds
  * newClass -- set the class and parent of an object
  * newNetFile -- create a new net file
  * nextkey -- the next key in a database
  * openDatabase -- open a database file
  * openDatabaseOut -- open a database file for writing
  * openFiles -- list the open files
  * "openIn" -- see openIn(String), -- open an input
    file
  * openInOut -- open an input output file
  * "openListener" -- see openListener(String),
    -- open a port for listening
  * "openOut" -- see openOut(String), -- open an
    output file
  * "openOutAppend" -- see openOutAppend(String),
    -- open an output file for appending
  * override -- override default values for optional arguments
  * pairs -- list the pairs in a hash table, dictionary, or basic
    list
  * parent -- parent type of an object
  * plus -- addition
  * power -- power
  * powermod -- powers of integers mod N
  * prepend -- add an element to the beginning of a list
  * printString -- lowlevel function to print a string,
    net, or symbol
  * processID -- the process identifier
  * protect -- protect a symbol
  * pseudocode -- produce the pseudocode for a function
  * read -- read from a file
  * readDirectory -- read the contents of a directory
  * readlink -- readlink fn
  * realpath -- convert a filename to one passing through no
    symbolic links
  * recursionDepth -- the current recursion depth
  * relativizeFilename -- relativize a file name
  * remove -- remove an entry from a mutable hash table, list,
    or database
  * removeDirectory -- remove a directory
  * removeFile -- remove a file
  * reorganize -- reorganize a database file
  * reverse -- reverse a list, sequence, or string
  * right -- right endpoint of an interval
  * run -- run an external command
  * scan -- apply a function to each element in a list or sequence
  * scanPairs -- apply a function to the pairs in a hash
    table
  * schedule -- schedule a task for execution
  * selectPairs -- select a part of a hash table by pairs
  * sequence -- make a sequence
  * serialNumber -- serial number of a dictionary, task,
    symbol, mutable hash table, or mutable list,
  * set -- make a set
  * setEcho -- turn on echoing
  * setGroupID -- set the process group identifier
  * setIOExclusive -- exclusive I/O for the current
    thread
  * setIOSynchronized -- synchronized I/O for threads
  * setIOUnSynchronized -- unsynchronized I/O for
    threads
  * size2 -- number of binary digits to the left of the point
  * sleep -- sleep for a while
  * splice -- remove subsequences from a sequence or list
  * stack -- join nets or string vertically
  * substring -- extract part of a string
  * symbolBody -- symbol bodies
  * symlinkFile -- make a symbolic link to a file
  * take -- Take some elements from a list or sequence.
  * tally -- tally the elements of a list, sequence, array, or
    string
  * "taskResult" -- see taskResult(Task), --
    retrieve the value returned by a task
  * times -- multiplication
  * toCC -- convert to high-precision complex number
  * toRR -- convert to high-precision real number
  * toRRi -- construct an interval
  * toSequence -- convert to sequence
  * uncurry -- uncurry a function
  * unsequence -- extract the single element from a sequence
    of length 1
  * unstack -- list the rows of a net
  * utf8 -- encode and decode unicode utf-8-encoded strings
  * "utf8check" -- see utf8, -- encode and decode unicode
    utf-8-encoded strings
  * utf8substring -- extract part of a utf8 string
  * values -- values in a hash table
  * wait -- wait for child process
  * wrap
  * youngest -- the youngest member of a sequence

For the programmer
==================

The object CompiledFunction, is a type,
with ancestor classes Function, < Thing.

CompiledFunctionBody -- the class of all compiled function bodies
*****************************************************************

Description
===========

A compiled function body is the body of a compiled function closure.  It is not
a function.
+---------------------------+
|i1 : source                |
|                           |
|o1 = source                |
|                           |
|o1 : MethodFunction        |
+---------------------------+
|i2 : functionBody source   |
|                           |
|o2 = CompiledFunctionBody[]|
|                           |
|o2 : CompiledFunctionBody  |
+---------------------------+

For the programmer
==================

The object CompiledFunctionBody, is a type,
with ancestor classes FunctionBody, < Thing.

CompiledFunctionClosure -- the class of all compiled function closures
**********************************************************************

Description
===========

Some compiled functions return compiled function closures as values.
+-------------------+
|i1 : class depth   |
|                   |
|o1 = MethodFunction|
|                   |
|o1 : Type          |
+-------------------+
|i2 : f = method()  |
|                   |
|o2 = f             |
|                   |
|o2 : MethodFunction|
+-------------------+
|i3 : class f       |
|                   |
|o3 = MethodFunction|
|                   |
|o3 : Type          |
+-------------------+

Types of compiled function closure:
===================================

  * MethodFunction -- a type of method function

Methods that use a compiled function closure:
=============================================

  * frames(CompiledFunctionClosure) (missing documentation)
  * localDictionaries(CompiledFunctionClosure) (missing documentation)

For the programmer
==================

The object CompiledFunctionClosure, is a
type, with ancestor classes Function, < Thing.

Complement -- a Strategy option value
*************************************

Description
===========

The standard (default) strategy for mingens, or trim,
is Complement, at least in the case where the module
(or ideal) is homogeneous, and the ring is (quotient ring of) a polynomial ring
over a field.  The other strategy, see Inhomogeneous, is
experimental.

For the programmer
==================

The object Complement, is a symbol.

complement(Matrix) -- find the minimal generators for cokernel of a matrix (low level form)
*******************************************************************************************

Synopsis
========

  * Function: complement,

Description
===========

complement f -- for a matrix f, return a map g with the same target whose
columns are minimal generators for the cokernel of f.

The map f must be homogeneous.

Ways to use this method:
========================

  * complement(Matrix) -- find the minimal
    generators for cokernel of a matrix (low level form)

complete
********

Description
===========

complete C -- completely fills out the chain complex C by calling upon the
engine to provide the maps and modules computed by resolution.

This is mainly intended for developers of new routines for chain complexes that
have to make use of their internal structure. Before running this routine, it
is not possible to determine which spots in a chain complex are actually
occupied by modules or maps.

Ways to use complete:
=====================

  * "complete(ChainComplexMap)"
  * "complete(GradedModule)"
  * complete(ChainComplex) -- complete the
    internal parts

For the programmer
==================

The object complete, is a method function.

complete(ChainComplex) -- complete the internal parts
*****************************************************

Synopsis
========

  * Function: complete,

Description
===========

complete C -- fills in the modules of a chain complex obtained as a resolution
with information from the engine.

For the sake of efficiency, when a chain complex arises as a resolution of a
module, the free modules are not filled in until they are needed.  This routine
can be used to fill them all in, and is called internally when a chain complex
is printed. Normally users will not need this function, unless they use
#, to obtain the modules of the chain complex, or use keys, to
see which spots are occupied by modules.
+--------------------------------------------------------------+
|i1 : R = ZZ/101[a..d];                                        |
+--------------------------------------------------------------+
|i2 : C = resolution cokernel vars R;                          |
+--------------------------------------------------------------+
|i3 : keys C                                                   |
|                                                              |
|o3 = {Resolution, dd, ring, cache}                            |
|                                                              |
|o3 : List                                                     |
+--------------------------------------------------------------+
|i4 : complete C;                                              |
+--------------------------------------------------------------+
|i5 : keys C                                                   |
|                                                              |
|o5 = {0, 1, 2, 3, 4, 5, complete, Resolution, ring, dd, cache}|
|                                                              |
|o5 : List                                                     |
+--------------------------------------------------------------+

Ways to use this method:
========================

  * complete(ChainComplex) -- complete the
    internal parts

ComplexField -- the class of all complex fields
***********************************************

Description
===========

A complex number ring is a ring whose elements are complex numbers of variable
precision.

For the programmer
==================

The object ComplexField, is a type, with
ancestor classes InexactField, < EngineRing
< Ring < Type < MutableHashTable
< HashTable < Thing.

components -- list the components of a direct sum
*************************************************

Description
===========

components x -- produces a list of the components of an element of a free
module.
components M -- the list of components for a module M which was formed as a
direct sum, or {M} if M was not formed as a direct sum.  Works also for
homomorphism, chain complexes, and graded modules.

See also
========

  * vector -- make a vector
  * directSum -- direct sum of modules or maps
  * ++ -- a binary operator, usually used for direct sum

Ways to use components:
=======================

  * "components(ChainComplexMap)"
  * "components(GradedModule)"
  * "components(GradedModuleMap)"
  * "components(Matrix)"
  * "components(Module)"
  * components(ChainComplex)
  * components(CoherentSheaf) (missing documentation)
  * components(SheafMap) (missing documentation)

For the programmer
==================

The object components, is a method function.

components(ChainComplex)
************************

Synopsis
========

  * Function: components,

Description
===========

components C -- returns from which C was formed, if C was formed as a direct
sum.

See also
========

  * isDirectSum -- whether something is a direct sum

Ways to use this method:
========================

  * components(ChainComplex)

compositions -- list the compositions of an integer
***************************************************

Synopsis
========

  * Usage:
        compositions(k, n)
  * Inputs:
      * k, an integer, a nonnegative integer, the number of parts in
        each composition
      * n, an integer, a nonnegative integer, the sum of each
        composition
  * Outputs:
      * a list, of all ordered lists of k nonnegative integers
        that sum to n

Description
===========

+-----------------------------------------------------------------------------+
|i1 : compositions(4, 2)                                                      |
|                                                                             |
|o1 = {{2, 0, 0, 0}, {1, 1, 0, 0}, {0, 2, 0, 0}, {1, 0, 1, 0}, {0, 1, 1, 0},  |
|     ------------------------------------------------------------------------|
|     {0, 0, 2, 0}, {1, 0, 0, 1}, {0, 1, 0, 1}, {0, 0, 1, 1}, {0, 0, 0, 2}}   |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+
|i2 : compositions(2, 4)                                                      |
|                                                                             |
|o2 = {{4, 0}, {3, 1}, {2, 2}, {1, 3}, {0, 4}}                                |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

To find all unordered compositions, we can use sort, or
rsort, to put each composition into a standard form, then use the
function unique, to remove duplicates.

+-----------------------------------------------------------------------------+
|i3 : unique apply(compositions(4, 10), comp -> rsort comp)                   |
|                                                                             |
|o3 = {{10, 0, 0, 0}, {9, 1, 0, 0}, {8, 2, 0, 0}, {7, 3, 0, 0}, {6, 4, 0, 0}, |
|     ------------------------------------------------------------------------|
|     {5, 5, 0, 0}, {8, 1, 1, 0}, {7, 2, 1, 0}, {6, 3, 1, 0}, {5, 4, 1, 0},   |
|     ------------------------------------------------------------------------|
|     {6, 2, 2, 0}, {5, 3, 2, 0}, {4, 4, 2, 0}, {4, 3, 3, 0}, {7, 1, 1, 1},   |
|     ------------------------------------------------------------------------|
|     {6, 2, 1, 1}, {5, 3, 1, 1}, {4, 4, 1, 1}, {5, 2, 2, 1}, {4, 3, 2, 1},   |
|     ------------------------------------------------------------------------|
|     {3, 3, 3, 1}, {4, 2, 2, 2}, {3, 3, 2, 2}}                               |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

In the next example, we use select, to find all the compositions
of 18 into 5 parts, with each part greater than or equal to 3.

+-----------------------------------------------------------------------------+
|i4 : select(compositions(5, 18), comp -> all(comp, c -> c>=3))               |
|                                                                             |
|o4 = {{6, 3, 3, 3, 3}, {5, 4, 3, 3, 3}, {4, 5, 3, 3, 3}, {3, 6, 3, 3, 3}, {5,|
|     ------------------------------------------------------------------------|
|     3, 4, 3, 3}, {4, 4, 4, 3, 3}, {3, 5, 4, 3, 3}, {4, 3, 5, 3, 3}, {3, 4,  |
|     ------------------------------------------------------------------------|
|     5, 3, 3}, {3, 3, 6, 3, 3}, {5, 3, 3, 4, 3}, {4, 4, 3, 4, 3}, {3, 5, 3,  |
|     ------------------------------------------------------------------------|
|     4, 3}, {4, 3, 4, 4, 3}, {3, 4, 4, 4, 3}, {3, 3, 5, 4, 3}, {4, 3, 3, 5,  |
|     ------------------------------------------------------------------------|
|     3}, {3, 4, 3, 5, 3}, {3, 3, 4, 5, 3}, {3, 3, 3, 6, 3}, {5, 3, 3, 3, 4}, |
|     ------------------------------------------------------------------------|
|     {4, 4, 3, 3, 4}, {3, 5, 3, 3, 4}, {4, 3, 4, 3, 4}, {3, 4, 4, 3, 4}, {3, |
|     ------------------------------------------------------------------------|
|     3, 5, 3, 4}, {4, 3, 3, 4, 4}, {3, 4, 3, 4, 4}, {3, 3, 4, 4, 4}, {3, 3,  |
|     ------------------------------------------------------------------------|
|     3, 5, 4}, {4, 3, 3, 3, 5}, {3, 4, 3, 3, 5}, {3, 3, 4, 3, 5}, {3, 3, 3,  |
|     ------------------------------------------------------------------------|
|     4, 5}, {3, 3, 3, 3, 6}}                                                 |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

For partitions of n into unordered, strictly positive parts, use
partitions, instead.

If a negative integer is given for n, an empty list is returned. If a negative
integer is given for k, it will cause an error.

See also
========

  * partitions -- list the partitions of an integer
  * subsets -- produce the subsets of a set or list
  * combinatorial functions

Ways to use compositions:
=========================

  * "compositions(ZZ,ZZ)"
  * compositions(ZZ) (missing documentation)

For the programmer
==================

The object compositions, is a method function.

compress -- extract nonzero columns from a matrix
*************************************************

Synopsis
========

  * Usage:
        compress m
  * Inputs:
      * m, a matrix,
  * Outputs:
      * a matrix, the matrix consisting of nonzero columns of m

Description
===========

+-------------------------------------+
|i1 : m = matrix {{1,2,0,0},{0,0,1,0}}|
|                                     |
|o1 = | 1 2 0 0 |                     |
|     | 0 0 1 0 |                     |
|                                     |
|              2       4              |
|o1 : Matrix ZZ  <-- ZZ               |
+-------------------------------------+
|i2 : compress m                      |
|                                     |
|o2 = | 1 2 0 |                       |
|     | 0 0 1 |                       |
|                                     |
|              2       3              |
|o2 : Matrix ZZ  <-- ZZ               |
+-------------------------------------+

See also
========

  * matrices

Ways to use compress:
=====================

  * "compress(Matrix)"

For the programmer
==================

The object compress, is a method function.

computing syzygies
******************

A syzygy among the columns of a matrix is, by definition, an element of the
kernel of the corresponding map between free modules, and the easiest way to
compute the syzygies applying the function kernel.
+------------------------------+
|i1 : R = QQ[x..z];            |
+------------------------------+
|i2 : f = vars R               |
|                              |
|o2 = | x y z |                |
|                              |
|             1      3         |
|o2 : Matrix R  <-- R          |
+------------------------------+
|i3 : K = kernel f             |
|                              |
|o3 = image {1} | -y 0  -z |   |
|           {1} | x  -z 0  |   |
|           {1} | 0  y  x  |   |
|                              |
|                             3|
|o3 : R-module, submodule of R |
+------------------------------+
The answer is provided as a submodule of the source of f.  The function
super, can be used to produce the module that K is a submodule of;
indeed, this works for any module.
+----------------------------------+
|i4 : L = super K                  |
|                                  |
|      3                           |
|o4 = R                            |
|                                  |
|o4 : R-module, free, degrees {3:1}|
+----------------------------------+
|i5 : L == source f                |
|                                  |
|o5 = true                         |
+----------------------------------+
The matrix whose columns are the generators of K, lifted to the ambient free
module of L if necessary, can be obtained with the function generators,
an abbreviation for which is gens.
+---------------------+
|i6 : g = generators K|
|                     |
|o6 = {1} | -y 0  -z ||
|     {1} | x  -z 0  ||
|     {1} | 0  y  x  ||
|                     |
|             3      3|
|o6 : Matrix R  <-- R |
+---------------------+
We can check at least that the columns of g are syzygies of the columns of f by
checking that f*g is zero.
+---------------------+
|i7 : f*g             |
|                     |
|o7 = 0               |
|                     |
|             1      3|
|o7 : Matrix R  <-- R |
+---------------------+
|i8 : f*g == 0        |
|                     |
|o8 = true            |
+---------------------+
Use the function syz, if you need detailed control over the extent
of the computation.

cone -- mapping cone or polyhedral cone
***************************************

See also
========

  * cone(ChainComplexMap)
  * cone(ComplexMap) (Complexes) -- make the
    mapping cone of a morphism of chain complexes
  * cone(Polyhedron) (Polyhedra) -- Take the cone
    over a polyhedron
  * null -- the unique member of the empty class

Ways to use cone:
=================

  * cone(ChainComplexMap)
  * cone(Polyhedron) (Polyhedra) -- Take the cone
    over a polyhedron

For the programmer
==================

The object cone, is a method function.

cone(ChainComplexMap)
*********************

Synopsis
========

  * Function: cone,
  * Usage:
        cone f
  * Inputs:
      * f
  * Outputs:
      * the mapping cone of a f

Description
===========

+--------------------------------------------------------+
|i1 : R = ZZ/101[x,y,z]                                  |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : m = image vars R                                   |
|                                                        |
|o2 = image | x y z |                                    |
|                                                        |
|                             1                          |
|o2 : R-module, submodule of R                           |
+--------------------------------------------------------+
|i3 : m2 = image symmetricPower(2,vars R)                |
|                                                        |
|o3 = image | x2 xy xz y2 yz z2 |                        |
|                                                        |
|                             1                          |
|o3 : R-module, submodule of R                           |
+--------------------------------------------------------+
|i4 : M = R^1/m2                                         |
|                                                        |
|o4 = cokernel | x2 xy xz y2 yz z2 |                     |
|                                                        |
|                            1                           |
|o4 : R-module, quotient of R                            |
+--------------------------------------------------------+
|i5 : N = R^1/m                                          |
|                                                        |
|o5 = cokernel | x y z |                                 |
|                                                        |
|                            1                           |
|o5 : R-module, quotient of R                            |
+--------------------------------------------------------+
|i6 : C = cone extend(resolution N,resolution M,id_(R^1))|
|                                                        |
|      1      4      9      9      3                     |
|o6 = R  <-- R  <-- R  <-- R  <-- R  <-- 0               |
|                                                        |
|     0      1      2      3      4      5               |
|                                                        |
|o6 : ChainComplex                                       |
+--------------------------------------------------------+
Let's check that the homology is correct; for example, HH_0 should be zero.
+-----------------+
|i7 : prune HH_0 C|
|                 |
|o7 = 0           |
|                 |
|o7 : R-module    |
+-----------------+
Let's check that HH_1 is isomorphic to m/m2.
+---------------------------------------+
|i8 : prune HH_1 C                      |
|                                       |
|o8 = cokernel {1} | z y x 0 0 0 0 0 0 ||
|              {1} | 0 0 0 z y x 0 0 0 ||
|              {1} | 0 0 0 0 0 0 z y x ||
|                                       |
|                            3          |
|o8 : R-module, quotient of R           |
+---------------------------------------+
|i9 : prune (m/m2)                      |
|                                       |
|o9 = cokernel {1} | z y x 0 0 0 0 0 0 ||
|              {1} | 0 0 0 z y x 0 0 0 ||
|              {1} | 0 0 0 0 0 0 z y x ||
|                                       |
|                            3          |
|o9 : R-module, quotient of R           |
+---------------------------------------+

Ways to use this method:
========================

  * cone(ChainComplexMap)

conjugate -- complex conjugate
******************************

Synopsis
========

  * Usage:
        conjugate z
  * Inputs:
      * z
  * Outputs:
      * a complex number, the complex conjugate of z

Description
===========

+-------------------------+
|i1 : conjugate(1+2.5*ii) |
|                         |
|o1 = 1-2.5*ii            |
|                         |
|o1 : CC (of precision 53)|
+-------------------------+
|i2 : conjugate 3         |
|                         |
|o2 = 3                   |
+-------------------------+

Ways to use conjugate:
======================

  * "conjugate(CC)"
  * "conjugate(Constant)"
  * "conjugate(Number)"
  * conjugate(Partition) -- conjugate a
    partition

For the programmer
==================

The object conjugate, is a method function.

conjugate(Partition) -- conjugate a partition
*********************************************

Synopsis
========

  * Function: conjugate,
  * Usage:
        conjugate p
  * Inputs:
      * p
  * Outputs:
      * the conjugate of p

Description
===========

+-----------------------------------------------------------------------------+
|i1 : partitions 4                                                            |
|                                                                             |
|o1 = {Partition{4}, Partition{3, 1}, Partition{2, 2}, Partition{2, 1, 1},    |
|     ------------------------------------------------------------------------|
|     Partition{1, 1, 1, 1}}                                                  |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+
|i2 : conjugate \ oo                                                          |
|                                                                             |
|o2 = {Partition{1, 1, 1, 1}, Partition{2, 1, 1}, Partition{2, 2},            |
|     ------------------------------------------------------------------------|
|     Partition{3, 1}, Partition{4}}                                          |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * conjugate(Partition) -- conjugate a
    partition

connectionCount -- the number of connections
********************************************

Description
===========

connectionCount f -- returns the number of connections accepted by the listener
f so far.

For the programmer
==================

The object connectionCount, is a compiled function.

Constant
********

Description
===========

A constant is a symbolic entity that can be approximated by a real or complex
number to any desired accuracy.  It is converted to a numeric value of the
correct precision, when necessary.

+-------------------------------------------+
|i1 : pi                                    |
|                                           |
|o1 = pi                                    |
|                                           |
|o1 : Constant                              |
+-------------------------------------------+
|i2 : +pi                                   |
|                                           |
|o2 = 3.141592653589793                     |
|                                           |
|o2 : RR (of precision 53)                  |
+-------------------------------------------+
|i3 : numeric_100 pi                        |
|                                           |
|o3 = 3.141592653589793238462643383279      |
|                                           |
|o3 : RR (of precision 100)                 |
+-------------------------------------------+
|i4 : 2. * pi                               |
|                                           |
|o4 = 6.283185307179586                     |
|                                           |
|o4 : RR (of precision 53)                  |
+-------------------------------------------+
|i5 : 2p100 * pi                            |
|                                           |
|o5 = 6.283185307179586476925286766559      |
|                                           |
|o5 : RR (of precision 100)                 |
+-------------------------------------------+
|i6 : exp(2*pi*ii/17)                       |
|                                           |
|o6 = .9324722294043558+.3612416661871529*ii|
|                                           |
|o6 : CC (of precision 53)                  |
+-------------------------------------------+

See also
========

  * numeric -- convert to floating point
  * defaultPrecision -- default precision of numbers

Methods that use an object of class Constant:
=============================================

  * "Constant !" -- see !, -- factorial
  * "Constant * Constant" -- see *, -- a binary operator, usually
    used for multiplication
  * "Constant * InexactNumber" -- see *, -- a binary operator,
    usually used for multiplication
  * "Constant * Number" -- see *, -- a binary operator, usually used
    for multiplication
  * "InexactNumber * Constant" -- see *, -- a binary operator,
    usually used for multiplication
  * "Number * Constant" -- see *, -- a binary operator, usually used
    for multiplication
  * "+ Constant" -- see +, -- a unary or binary operator, usually used
    for addition
  * "Constant + Constant" -- see +, -- a unary or binary operator,
    usually used for addition
  * "Constant + InexactNumber" -- see +, -- a unary or binary
    operator, usually used for addition
  * "Constant + Number" -- see +, -- a unary or binary operator,
    usually used for addition
  * "InexactNumber + Constant" -- see +, -- a unary or binary
    operator, usually used for addition
  * "Number + Constant" -- see +, -- a unary or binary operator,
    usually used for addition
  * "- Constant" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "Constant - Constant" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "Constant - InexactNumber" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "Constant - Number" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "InexactNumber - Constant" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "Number - Constant" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * abs(Constant) (missing documentation)
  * "conjugate(Constant)" -- see conjugate, -- complex
    conjugate
  * "Constant * RingElement"
  * "Constant + RingElement"
  * "Constant - RingElement"
  * "Constant / Constant"
  * "Constant / InexactNumber"
  * "Constant / Number"
  * "Constant / RingElement"
  * "Constant ^ Constant"
  * "Constant ^ InexactNumber"
  * "Constant ^ Number"
  * "InexactNumber / Constant"
  * "InexactNumber ^ Constant"
  * "Number / Constant"
  * "Number ^ Constant"
  * "RingElement * Constant"
  * "RingElement + Constant"
  * "RingElement - Constant"
  * "RingElement / Constant"
  * Constant == Constant (missing documentation)
  * Constant == InexactNumber (missing documentation)
  * Constant == Number (missing documentation)
  * Constant == RingElement (missing documentation)
  * Constant ? Constant (missing documentation)
  * Constant ? Number (missing documentation)
  * Constant ^ RingFamily (missing documentation)
  * "floor(Constant)" -- see floor(Number), -- floor
    function
  * InexactNumber == Constant (missing documentation)
  * InexactNumber ? Constant (missing documentation)
  * isc(Constant) (missing documentation)
  * "isFinite(Constant)" -- see isFinite, -- whether a number
    is finite
  * "isInfinite(Constant)" -- see isInfinite, -- whether a
    number is infinite
  * "isReal(Constant)" -- see isReal, -- whether a number is real
  * Number == Constant (missing documentation)
  * Number ? Constant (missing documentation)
  * "numeric(Constant)" -- see numeric, -- convert to floating
    point
  * "numeric(InfiniteNumber,Constant)" -- see numeric, --
    convert to floating point
  * "numeric(ZZ,Constant)" -- see numeric, -- convert to
    floating point
  * "numericInterval(Constant)" -- see numericInterval,
    -- converts to an interval
  * "numericInterval(ZZ,Constant)" -- see numericInterval,
    -- converts to an interval
  * promote(Constant,type of InexactNumber') (missing documentation)
  * promote(Constant,type of RingElement) (missing documentation)
  * ring(Constant) (missing documentation)
  * RingElement == Constant (missing documentation)
  * "round(Constant)" -- see round, -- round a number

Protected objects of class Constant:
====================================

  * CatalanConstant -- Catalan's constant
  * EulerConstant -- the Euler-Mascheroni constant
  * ii -- the square root of -1
  * pi

For the programmer
==================

The object Constant, is a type, with ancestor
classes Number, < Thing.

constructing maps between modules
*********************************

Let's start with a free module.
+---------------------+
|i1 : R = ZZ/5[x,y,z];|
+---------------------+
|i2 : F = R^3         |
|                     |
|      3              |
|o2 = R               |
|                     |
|o2 : R-module, free  |
+---------------------+
A list of indices can be used to produce homomorphisms corresponding to the
corresponding basis vectors.
+---------------------+
|i3 : F_{0,1,2}       |
|                     |
|o3 = | 1 0 0 |       |
|     | 0 1 0 |       |
|     | 0 0 1 |       |
|                     |
|             3      3|
|o3 : Matrix R  <-- R |
+---------------------+
|i4 : F_{0,1}         |
|                     |
|o4 = | 1 0 |         |
|     | 0 1 |         |
|     | 0 0 |         |
|                     |
|             3      2|
|o4 : Matrix R  <-- R |
+---------------------+
|i5 : F_{1,2}         |
|                     |
|o5 = | 0 0 |         |
|     | 1 0 |         |
|     | 0 1 |         |
|                     |
|             3      2|
|o5 : Matrix R  <-- R |
+---------------------+
Matrices are viewed as linear transformations.
+------------------------+
|i6 : f = matrix{{x,y,z}}|
|                        |
|o6 = | x y z |          |
|                        |
|             1      3   |
|o6 : Matrix R  <-- R    |
+------------------------+

content -- the content of a polynomial
**************************************

Synopsis
========

  * Usage:
        content f
        content(f, x)
  * Inputs:
      * f, a ring element,
      * x, a ring element, a variable in the ring of f
  * Outputs:
      * an ideal, the content of a matrix or polynomial

Description
===========

The content is the ideal in the base ring generated by the coefficients.

+----------------------------+
|i1 : R = ZZ[x,y]            |
|                            |
|o1 = R                      |
|                            |
|o1 : PolynomialRing         |
+----------------------------+
|i2 : content(4*x + 6*x^5)   |
|                            |
|o2 = ideal (6, 4)           |
|                            |
|o2 : Ideal of ZZ            |
+----------------------------+
|i3 : content(4*x + 6*x^5, x)|
|                            |
|o3 = ideal (6, 4)           |
|                            |
|o3 : Ideal of R             |
+----------------------------+
|i4 : content(4*x + 6*x^5, y)|
|                            |
|             5              |
|o4 = ideal(6x  + 4x)        |
|                            |
|o4 : Ideal of R             |
+----------------------------+
|i5 : generator oo           |
|                            |
|       5                    |
|o5 = 6x  + 4x               |
|                            |
|o5 : R                      |
+----------------------------+

Code
====

../../../../../Macaulay2/m2/matrix1.m2:659:33-659:66: --source code:
content(RingElement) := Ideal => (f) -> ideal \\ last \ listForm f
../../../../../Macaulay2/m2/matrix1.m2:660:46-660:99: --source code:
content(RingElement, RingElement) := Ideal => (f,x) -> ideal last coefficients(
-------------------------------------------------------------------------------
f, Variables => {x})

See also
========

  * exponents -- the exponents of a polynomial
  * coefficients -- monomials and their coefficients
  * listForm -- convert to list form
  * standardForm -- convert to standard form
  * monomials -- matrix of monomials in a ring element or
    matrix

Ways to use content:
====================

  * "content(RingElement)"
  * "content(RingElement,RingElement)"

For the programmer
==================

The object content, is a method function.

continue -- continue with the next iteration of a loop
******************************************************

Synopsis
========

  * Usage:
        continue x
  * Inputs:
      * x
  * Consequences:
      * the currently executing list-clause of a for,-loop or
        while,-loop is finished, and iteration continues with the
        do,-clause or the next iteration of the loop, if any.  The value x
        is added to the list being accumulated. If x is omitted, then no value
        is added to the list, and the statement may be used in a do-clause.
      * Alternatively, as a debugger command, causes execution to be resumed,
        starting with the current expression.

Description
===========

+---------------------------------------------------------------------------+
|i1 : for i from 1 to 4 list (continue 4; print ho) do print hi             |
|hi                                                                         |
|hi                                                                         |
|hi                                                                         |
|hi                                                                         |
|                                                                           |
|o1 = {4, 4, 4, 4}                                                          |
|                                                                           |
|o1 : List                                                                  |
+---------------------------------------------------------------------------+
|i2 : for i from 1 to 4 list (continue ; 14) do print hi                    |
|hi                                                                         |
|hi                                                                         |
|hi                                                                         |
|hi                                                                         |
|                                                                           |
|o2 = {}                                                                    |
|                                                                           |
|o2 : List                                                                  |
+---------------------------------------------------------------------------+
|i3 : for i from 1 to 4 list 14 do print hi                                 |
|hi                                                                         |
|hi                                                                         |
|hi                                                                         |
|hi                                                                         |
|                                                                           |
|o3 = {14, 14, 14, 14}                                                      |
|                                                                           |
|o3 : List                                                                  |
+---------------------------------------------------------------------------+
|i4 : i = 0 ; while i < 10 do ( i = i+1; if i == 5 then continue ; print i )|
|1                                                                          |
|2                                                                          |
|3                                                                          |
|4                                                                          |
|6                                                                          |
|7                                                                          |
|8                                                                          |
|9                                                                          |
|10                                                                         |
+---------------------------------------------------------------------------+

Here is an example of the use of continue, in the debugger
after altering a value so continuation will not cause the error to recur.

+-----------------------------------------------------------------------------+
|i6 : load "Macaulay2Doc/demo1.m2"                                            |
+-----------------------------------------------------------------------------+
|i7 : code g                                                                  |
|                                                                             |
|o7 = /usr/local/share/Macaulay2/Macaulay2Doc/                                |
|     demo1.m2:11:4-14:9: --source code:                                      |
|     g = y -> (                                                              |
|          c := f(y-1);                                                       |
|          d := f(y-2);                                                       |
|          c+d)                                                               |
+-----------------------------------------------------------------------------+
|i8 : g 2                                                                     |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|8:10-8:13: --source code:                                                    |
|     b := 1/x;                                                               |
|-----------------------------------------------------------------------------|
|error: division by zero                                                      |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
|ii9 : code f                                                                 |
|                                                                             |
|oo9 = /usr/local/share/Macaulay2/Macaulay2Doc/                               |
|      demo1.m2:6:5-9:9: --source code:                                       |
|      f := x -> (                                                            |
|           a := "hi there";                                                  |
|           b := 1/x;                                                         |
|           b+1)                                                              |
+-----------------------------------------------------------------------------+
|ii10 : x                                                                     |
|                                                                             |
|oo10 = 0                                                                     |
+-----------------------------------------------------------------------------+
|ii11 : x = 11                                                                |
|                                                                             |
|oo11 = 11                                                                    |
+-----------------------------------------------------------------------------+
|ii12 : continue                                                              |
|                                                                             |
|      34                                                                     |
|o12 = --                                                                     |
|      11                                                                     |
|                                                                             |
|o12 : QQ                                                                     |
+-----------------------------------------------------------------------------+

For the programmer
==================

The object continue, is a keyword.

contract -- contract one matrix by another
******************************************

See also
========

  * diff and contract
  * contract' -- contract a matrix by a
    matrix, the dual notion

Ways to use contract:
=====================

  * contract(Matrix,Matrix) -- contract a
    matrix by a matrix
  * "contract(Matrix,Number)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Matrix,RingElement)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Matrix,Vector)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Number,Matrix)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Number,Number)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Number,RingElement)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Number,Vector)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(RingElement,Matrix)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(RingElement,Number)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(RingElement,RingElement)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(RingElement,Vector)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Vector,Matrix)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Vector,Number)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Vector,RingElement)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Vector,Vector)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix

For the programmer
==================

The object contract, is a method function.

contract'(Matrix,Matrix) -- contract a matrix by a matrix, the dual notion
**************************************************************************

Synopsis
========

  * Function: contract',
  * Usage:
        h = contract'(m,n)
  * Inputs:
      * m, a map m : F <--- P between free modules of ranks f and p.
      * n, a map n : G <--- Q between free modules of ranks g and q.
  * Outputs:
      * h, a matrix with the shape h : F ** dual G <--- P ** dual Q, whose

        entry in the slot h            is the result of contracting m   , by
                           g*i+j,q*k+l                               i,k
        n   .
         j,l

Description
===========

This function is identical to diff'(Matrix,Matrix),
except that the multiplication by integers that
occurs during differentiation is omitted.

See also
========

  * contract -- contract one matrix by another
  * diff and contract

Ways to use this method:
========================

  * contract'(Matrix,Matrix) -- contract
    a matrix by a matrix, the dual notion

contract(Matrix,Matrix) -- contract a matrix by a matrix
********************************************************

Synopsis
========

  * Function: contract,
  * Usage:
        h = contract(m,n)
  * Inputs:
      * m, a map m : F <--- P between free modules of ranks f and p.
      * n, a map n : G <--- Q between free modules of ranks g and q.
  * Outputs:
      * h, the contraction of n by m, a matrix with the shape h : dual F ** G

        <--- dual P ** Q, whose entry in the slot h            is the result of
                                                   g*i+j,q*k+l
        contracting n   , by m
                     j,l      i,k

Description
===========

The arguments can also be ring elements or vectors.
+-----------------------------------+
|i1 : R = ZZ[x,y,z]                 |
|                                   |
|o1 = R                             |
|                                   |
|o1 : PolynomialRing                |
+-----------------------------------+
|i2 : f = vars R ** vars R          |
|                                   |
|o2 = | x2 xy xz xy y2 yz xz yz z2 ||
|                                   |
|             1      9              |
|o2 : Matrix R  <-- R               |
+-----------------------------------+
|i3 : contract(transpose vars R, f) |
|                                   |
|o3 = {1} | x y z y 0 0 z 0 0 |     |
|     {1} | 0 x 0 x y z 0 z 0 |     |
|     {1} | 0 0 x 0 0 y x y z |     |
|                                   |
|             3      9              |
|o3 : Matrix R  <-- R               |
+-----------------------------------+
|i4 : contract(x, f)                |
|                                   |
|o4 = | x y z y 0 0 z 0 0 |         |
|                                   |
|             1      9              |
|o4 : Matrix R  <-- R               |
+-----------------------------------+
|i5 : contract(y, f)                |
|                                   |
|o5 = | 0 x 0 x y z 0 z 0 |         |
|                                   |
|             1      9              |
|o5 : Matrix R  <-- R               |
+-----------------------------------+
|i6 : contract(z, f)                |
|                                   |
|o6 = | 0 0 x 0 0 y x y z |         |
|                                   |
|             1      9              |
|o6 : Matrix R  <-- R               |
+-----------------------------------+

This function is identical to diff(Matrix,Matrix),
except that the multiplication by integers that
occurs during differentiation is omitted.

See also
========

  * contract' -- contract a matrix by a
    matrix, the dual notion
  * diff and contract

Ways to use this method:
========================

  * contract(Matrix,Matrix) -- contract a
    matrix by a matrix
  * "contract(Matrix,Number)"
  * "contract(Matrix,RingElement)"
  * "contract(Matrix,Vector)"
  * "contract(Number,Matrix)"
  * "contract(Number,Number)"
  * "contract(Number,RingElement)"
  * "contract(Number,Vector)"
  * "contract(RingElement,Matrix)"
  * "contract(RingElement,Number)"
  * "contract(RingElement,RingElement)"
  * "contract(RingElement,Vector)"
  * "contract(Vector,Matrix)"
  * "contract(Vector,Number)"
  * "contract(Vector,RingElement)"
  * "contract(Vector,Vector)"

COPYING-GPL-2 -- GNU General Public License, version 2
******************************************************

                    GNU GENERAL PUBLIC LICENSE
                       Version 2, June 1991

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

                            Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Lesser General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

                    GNU GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term "modification".)  Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

  2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

    a) You must cause the modified files to carry prominent notices
    stating that you changed the files and the date of any change.

    b) You must cause any work that you distribute or publish, that in
    whole or in part contains or is derived from the Program or any
    part thereof, to be licensed as a whole at no charge to all third
    parties under the terms of this License.

    c) If the modified program normally reads commands interactively
    when run, you must cause it, when started running for such
    interactive use in the most ordinary way, to print or display an
    announcement including an appropriate copyright notice and a
    notice that there is no warranty (or else, saying that you provide
    a warranty) and that users may redistribute the program under
    these conditions, and telling the user how to view a copy of this
    License.  (Exception: if the Program itself is interactive but
    does not normally print such an announcement, your work based on
    the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

    a) Accompany it with the complete corresponding machine-readable
    source code, which must be distributed under the terms of Sections
    1 and 2 above on a medium customarily used for software interchange; or,

    b) Accompany it with a written offer, valid for at least three
    years, to give any third party, for a charge no more than your
    cost of physically performing source distribution, a complete
    machine-readable copy of the corresponding source code, to be
    distributed under the terms of Sections 1 and 2 above on a medium
    customarily used for software interchange; or,

    c) Accompany it with the information you received as to the offer
    to distribute corresponding source code.  (This alternative is
    allowed only for noncommercial distribution and only if you
    received the program in object code or executable form with such
    an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

  5. You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

  7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

  9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

  10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

                            NO WARRANTY

  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

                     END OF TERMS AND CONDITIONS

            How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

    <one line to give the program's name and a brief idea of what it does.>
    Copyright (C) <year>  <name of author>

    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; either version 2 of the License, or
    (at your option) any later version.

    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.,
    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) year name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License.  Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary.  Here is a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
  `Gnomovision' (which makes passes at compilers) written by James Hacker.

  <signature of Ty Coon>, 1 April 1989
  Ty Coon, President of Vice

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Lesser General
Public License instead of this License.

COPYING-GPL-3 -- GNU General Public License, version 3
******************************************************

                    GNU GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

 Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

                            Preamble

  The GNU General Public License is a free, copyleft license for
software and other kinds of works.

  The licenses for most software and other practical works are designed
to take away your freedom to share and change the works.  By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users.  We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors.  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.

  To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights.  Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received.  You must make sure that they, too, receive
or can get the source code.  And you must show them these terms so they
know their rights.

  Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.

  For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software.  For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.

  Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so.  This is fundamentally incompatible with the aim of
protecting users' freedom to change the software.  The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable.  Therefore, we
have designed this version of the GPL to prohibit the practice for those
products.  If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.

  Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary.  To prevent this, the GPL assures that
patents cannot be used to render the program non-free.

  The precise terms and conditions for copying, distribution and
modification follow.

                       TERMS AND CONDITIONS

  0. Definitions.

  "This License" refers to version 3 of the GNU General Public License.

  "Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.

  "The Program" refers to any copyrightable work licensed under this
License.  Each licensee is addressed as "you".  "Licensees" and
"recipients" may be individuals or organizations.

  To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy.  The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.

  A "covered work" means either the unmodified Program or a work based
on the Program.

  To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy.  Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.

  To "convey" a work means any kind of propagation that enables other
parties to make or receive copies.  Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.

  An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License.  If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.

  1. Source Code.

  The "source code" for a work means the preferred form of the work
for making modifications to it.  "Object code" means any non-source
form of a work.

  A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.

  The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form.  A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.

  The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities.  However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work.  For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.

  The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.

  The Corresponding Source for a work in source code form is that
same work.

  2. Basic Permissions.

  All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met.  This License explicitly affirms your unlimited
permission to run the unmodified Program.  The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work.  This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.

  You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force.  You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright.  Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.

  Conveying under any other circumstances is permitted solely under
the conditions stated below.  Sublicensing is not allowed; section 10
makes it unnecessary.

  3. Protecting Users' Legal Rights From Anti-Circumvention Law.

  No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.

  When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.

  4. Conveying Verbatim Copies.

  You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.

  You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.

  5. Conveying Modified Source Versions.

  You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:

    a) The work must carry prominent notices stating that you modified
    it, and giving a relevant date.

    b) The work must carry prominent notices stating that it is
    released under this License and any conditions added under section
    7.  This requirement modifies the requirement in section 4 to
    "keep intact all notices".

    c) You must license the entire work, as a whole, under this
    License to anyone who comes into possession of a copy.  This
    License will therefore apply, along with any applicable section 7
    additional terms, to the whole of the work, and all its parts,
    regardless of how they are packaged.  This License gives no
    permission to license the work in any other way, but it does not
    invalidate such permission if you have separately received it.

    d) If the work has interactive user interfaces, each must display
    Appropriate Legal Notices; however, if the Program has interactive
    interfaces that do not display Appropriate Legal Notices, your
    work need not make them do so.

  A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit.  Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.

  6. Conveying Non-Source Forms.

  You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:

    a) Convey the object code in, or embodied in, a physical product
    (including a physical distribution medium), accompanied by the
    Corresponding Source fixed on a durable physical medium
    customarily used for software interchange.

    b) Convey the object code in, or embodied in, a physical product
    (including a physical distribution medium), accompanied by a
    written offer, valid for at least three years and valid for as
    long as you offer spare parts or customer support for that product
    model, to give anyone who possesses the object code either (1) a
    copy of the Corresponding Source for all the software in the
    product that is covered by this License, on a durable physical
    medium customarily used for software interchange, for a price no
    more than your reasonable cost of physically performing this
    conveying of source, or (2) access to copy the
    Corresponding Source from a network server at no charge.

    c) Convey individual copies of the object code with a copy of the
    written offer to provide the Corresponding Source.  This
    alternative is allowed only occasionally and noncommercially, and
    only if you received the object code with such an offer, in accord
    with subsection 6b.

    d) Convey the object code by offering access from a designated
    place (gratis or for a charge), and offer equivalent access to the
    Corresponding Source in the same way through the same place at no
    further charge.  You need not require recipients to copy the
    Corresponding Source along with the object code.  If the place to
    copy the object code is a network server, the Corresponding Source
    may be on a different server (operated by you or a third party)
    that supports equivalent copying facilities, provided you maintain
    clear directions next to the object code saying where to find the
    Corresponding Source.  Regardless of what server hosts the
    Corresponding Source, you remain obligated to ensure that it is
    available for as long as needed to satisfy these requirements.

    e) Convey the object code using peer-to-peer transmission, provided
    you inform other peers where the object code and Corresponding
    Source of the work are being offered to the general public at no
    charge under subsection 6d.

  A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.

  A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling.  In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage.  For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product.  A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.

  "Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source.  The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.

  If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information.  But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).

  The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed.  Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.

  Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.

  7. Additional Terms.

  "Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law.  If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.

  When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it.  (Additional permissions may be written to require their own
removal in certain cases when you modify the work.)  You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.

  Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:

    a) Disclaiming warranty or limiting liability differently from the
    terms of sections 15 and 16 of this License; or

    b) Requiring preservation of specified reasonable legal notices or
    author attributions in that material or in the Appropriate Legal
    Notices displayed by works containing it; or

    c) Prohibiting misrepresentation of the origin of that material, or
    requiring that modified versions of such material be marked in
    reasonable ways as different from the original version; or

    d) Limiting the use for publicity purposes of names of licensors or
    authors of the material; or

    e) Declining to grant rights under trademark law for use of some
    trade names, trademarks, or service marks; or

    f) Requiring indemnification of licensors and authors of that
    material by anyone who conveys the material (or modified versions of
    it) with contractual assumptions of liability to the recipient, for
    any liability that these contractual assumptions directly impose on
    those licensors and authors.

  All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10.  If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term.  If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.

  If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.

  Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.

  8. Termination.

  You may not propagate or modify a covered work except as expressly
provided under this License.  Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).

  However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.

  Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.

  Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License.  If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.

  9. Acceptance Not Required for Having Copies.

  You are not required to accept this License in order to receive or
run a copy of the Program.  Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance.  However,
nothing other than this License grants you permission to propagate or
modify any covered work.  These actions infringe copyright if you do
not accept this License.  Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.

  10. Automatic Licensing of Downstream Recipients.

  Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License.  You are not responsible
for enforcing compliance by third parties with this License.

  An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations.  If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.

  You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License.  For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.

  11. Patents.

  A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based.  The
work thus licensed is called the contributor's "contributor version".

  A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version.  For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.

  Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.

  In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement).  To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.

  If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients.  "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.

  If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.

  A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License.  You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.

  Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.

  12. No Surrender of Others' Freedom.

  If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all.  For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.

  13. Use with the GNU Affero General Public License.

  Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work.  The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.

  14. Revised Versions of this License.

  The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

  Each version is given a distinguishing version number.  If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation.  If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.

  If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.

  Later license versions may give you additional or different
permissions.  However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.

  15. Disclaimer of Warranty.

  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

  16. Limitation of Liability.

  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.

  17. Interpretation of Sections 15 and 16.

  If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.

                     END OF TERMS AND CONDITIONS

            How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

    <one line to give the program's name and a brief idea of what it does.>
    Copyright (C) <year>  <name of author>

    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, either version 3 of the License, or
    (at your option) any later version.

    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, see <https://www.gnu.org/licenses/>.

Also add information on how to contact you by electronic and paper mail.

  If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:

    <program>  Copyright (C) <year>  <name of author>
    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License.  Of course, your program's commands
might be different; for a GUI interface, you would use an "about box".

  You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
<https://www.gnu.org/licenses/>.

  The GNU General Public License does not permit incorporating your program
into proprietary programs.  If your program is a subroutine library, you
may consider it more useful to permit linking proprietary applications with
the library.  If this is what you want to do, use the GNU Lesser General
Public License instead of this License.  But first, please read
<https://www.gnu.org/licenses/why-not-lgpl.html>.

Core -- the core part of Macaulay2
**********************************

Description
===========

This package contains the core functionality of Macaulay2, without the
documentation, which is in the package Macaulay2Doc.

For the programmer
==================

The object Core, is a package.

cos -- compute the cosine
*************************

Synopsis
========

  * Usage:
        cos x
        cos I
  * Inputs:
      * x, a real number,
      * I, a real interval,
  * Outputs:
      * a real number, the cosine of x
      * a real interval, an interval containing the cosines of
        points of I

Description
===========

+-------------------------+
|i1 : cos 2               |
|                         |
|o1 = -.4161468365471424  |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

Ways to use cos:
================

  * "cos(CC)"
  * "cos(RR)"
  * "cos(RRi)"
  * cos(RingElement) (missing documentation)

For the programmer
==================

The object cos, is a method function.

cosh -- compute the hyperbolic cosine
*************************************

Synopsis
========

  * Usage:
        cosh x
        cosh I
  * Inputs:
      * x
      * I, a real interval,
  * Outputs:
      * a number, the hyperbolic cosine of x
      * a real interval, an interval containing the hyerbolic
        cosines of the points of I

Description
===========

+-------------------------+
|i1 : cosh .2             |
|                         |
|o1 = 1.020066755619076   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

Ways to use cosh:
=================

  * "cosh(CC)"
  * "cosh(RR)"
  * "cosh(RRi)"
  * cosh(RingElement) (missing documentation)

For the programmer
==================

The object cosh, is a method function.

cot -- cotangent
****************

Synopsis
========

  * Usage:
        cot x
        cot I
  * Inputs:
      * x
      * I, a real interval,
  * Outputs:
      * a real number, the cotangent of x
      * a real interval, an interval containing the cotangents of
        points of I

Description
===========

+-------------------------+
|i1 : cot(pi/3)           |
|                         |
|o1 = .577350269189626    |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See Trigonometric function (see
https://en.wikipedia.org/wiki/Trigonometric_function ).

Ways to use cot:
================

  * "cot(CC)"
  * "cot(RR)"
  * "cot(RRi)"

For the programmer
==================

The object cot, is a method function.

coth -- hyperbolic cotangent
****************************

Synopsis
========

  * Usage:
        coth x
        coth I
  * Inputs:
      * x
      * I, a real interval,
  * Outputs:
      * a real number, the hyperbolic cotangent of x
      * a real interval, an interval containing the hyperbolic
        cotangents of the points of I

Description
===========

+-------------------------+
|i1 : coth(pi/3)          |
|                         |
|o1 = 1.280878071045045   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See Hyperbolic function (see https://en.wikipedia.org/wiki/Hyperbolic_function
).

Ways to use coth:
=================

  * "coth(CC)"
  * "coth(RR)"
  * "coth(RRi)"

For the programmer
==================

The object coth, is a method function.

cover -- get the covering free module
*************************************

Description
===========

cover M -- yields the free module whose basis elements correspond to the
generators of M.

See also
========

  * ambient -- ambient free module of a subquotient, or ambient
    ring
  * super -- get the ambient module

Ways to use cover:
==================

  * cover(CoherentSheaf) (missing documentation)
  * cover(Matrix) -- get the map between the covering
    free modules
  * "cover(GradedModule)" -- see cover(Module), -- get
    the covering free module
  * cover(Module) -- get the covering free module
  * cover(SheafMap) (missing documentation)

For the programmer
==================

The object cover, is a method function.

cover(Matrix) -- get the map between the covering free modules
**************************************************************

Synopsis
========

  * Function: cover,
  * Usage:
        cover f
  * Inputs:
      * f
  * Outputs:
      * the corresponding map of free modules between the covers of the source
        and target of f

See also
========

  * cover(Module) -- get the covering free module

Ways to use this method:
========================

  * cover(Matrix) -- get the map between the covering
    free modules

cover(Module) -- get the covering free module
*********************************************

Synopsis
========

  * Function: cover,
  * Usage:
        F = cover M
  * Inputs:
      * M
  * Outputs:
      * F, the free module whose basis elements correspond to the generators of
        M.

Description
===========

The free module F is the source of the generator matrix of M.
+-------------------------------------------+
|i1 : R = QQ[a..f];                         |
+-------------------------------------------+
|i2 : g = matrix{{a,b},{c,d},{e,f}}         |
|                                           |
|o2 = | a b |                               |
|     | c d |                               |
|     | e f |                               |
|                                           |
|             3      2                      |
|o2 : Matrix R  <-- R                       |
+-------------------------------------------+
|i3 : M = subquotient(g,matrix{{b},{c},{d}})|
|                                           |
|o3 = subquotient (| a b |, | b |)          |
|                  | c d |  | c |           |
|                  | e f |  | d |           |
|                                           |
|                               3           |
|o3 : R-module, subquotient of R            |
+-------------------------------------------+
|i4 : cover M                               |
|                                           |
|      2                                    |
|o4 = R                                     |
|                                           |
|o4 : R-module, free, degrees {2:1}         |
+-------------------------------------------+
|i5 : cover M == source generators M        |
|                                           |
|o5 = true                                  |
+-------------------------------------------+

See also
========

  * ambient(Module) -- ambient free module
  * super(Module) -- get the ambient module

Ways to use this method:
========================

  * "cover(GradedModule)"
  * cover(Module) -- get the covering free module

coverMap(Module) -- the surjective map from a free module to a module corresponding to the generators
*****************************************************************************************************

Synopsis
========

  * Function: coverMap,
  * Usage:
        coverMap M
  * Inputs:
      * M
  * Outputs:
      * the surjective map from a free module to M corresponding to the
        generators

Description
===========

+--------------------------------+
|i1 : M = image matrix {{2},{0}} |
|                                |
|o1 = image | 2 |                |
|           | 0 |                |
|                                |
|                               2|
|o1 : ZZ-module, submodule of ZZ |
+--------------------------------+
|i2 : f = coverMap M             |
|                                |
|o2 = | 1 |                      |
|                                |
|                    1           |
|o2 : Matrix M <-- ZZ            |
+--------------------------------+
|i3 : isSurjective f             |
|                                |
|o3 = true                       |
+--------------------------------+

Ways to use this method:
========================

  * coverMap(Module) -- the surjective map from a
    free module to a module corresponding to the generators

cpuTime -- seconds of cpu time used since Macaulay2 began
*********************************************************

Synopsis
========

  * Usage:
        cpuTime()
  * Outputs:
      * a real number, the number of seconds of cpu time used since
        the program was started

Description
===========

+----------------------------------------------------------+
|i1 : t1 = cpuTime()                                       |
|                                                          |
|o1 = 143.842993791                                        |
|                                                          |
|o1 : RR (of precision 53)                                 |
+----------------------------------------------------------+
|i2 : for i from 0 to 1000000 do 223131321321*324234324324;|
+----------------------------------------------------------+
|i3 : t2 = cpuTime()                                       |
|                                                          |
|o3 = 144.841582943                                        |
|                                                          |
|o3 : RR (of precision 53)                                 |
+----------------------------------------------------------+
|i4 : t2-t1                                                |
|                                                          |
|o4 = .9985891519999939                                    |
|                                                          |
|o4 : RR (of precision 53)                                 |
+----------------------------------------------------------+

See also
========

  * time -- time a computation
  * timing -- time a computation
  * currentTime -- get the current time

For the programmer
==================

The object cpuTime, is a compiled function.

csc -- cosecant
***************

Synopsis
========

  * Usage:
        csc x
        csc I
  * Inputs:
      * x
      * I, a real interval,
  * Outputs:
      * a real number, the cosecant of x
      * a real interval, an interval containing the cosecants of
        the points of I

Description
===========

+-------------------------+
|i1 : csc(pi/3)           |
|                         |
|o1 = 1.154700538379252   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See Trigonometric function (see
https://en.wikipedia.org/wiki/Trigonometric_function ).

Ways to use csc:
================

  * "csc(CC)"
  * "csc(RR)"
  * "csc(RRi)"

For the programmer
==================

The object csc, is a method function.

csch -- hyperbolic cosecant
***************************

Synopsis
========

  * Usage:
        csch x
        csch I
  * Inputs:
      * x
      * I, a real interval,
  * Outputs:
      * a real number, the hyperbolic cosecant of x
      * a real interval, an interval containing the hyperbolic
        cosecants of the points of I

Description
===========

+-------------------------+
|i1 : csch(pi/3)          |
|                         |
|o1 = .8004052928885931   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See Hyperbolic function (see https://en.wikipedia.org/wiki/Hyperbolic_function
).

Ways to use csch:
=================

  * "csch(CC)"
  * "csch(RR)"
  * "csch(RRi)"

For the programmer
==================

The object csch, is a method function.

current -- the pseudocode that produced an error
************************************************

Synopsis
========

  * Usage:
        current
  * Outputs:
      * an instance of the type PseudocodeClosure, the
        pseudocode that produced an error, or null, if none

Description
===========

Use value, to evaluate the code again, for debugging purposes.
+-----------------------------------------------------------------------------+
|i1 : load "Macaulay2Doc/demo1.m2"                                            |
+-----------------------------------------------------------------------------+
|i2 : code g                                                                  |
|                                                                             |
|o2 = /usr/local/share/Macaulay2/Macaulay2Doc/                                |
|     demo1.m2:11:4-14:9: --source code:                                      |
|     g = y -> (                                                              |
|          c := f(y-1);                                                       |
|          d := f(y-2);                                                       |
|          c+d)                                                               |
+-----------------------------------------------------------------------------+
|i3 : g 2                                                                     |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|8:10-8:13: --source code:                                                    |
|     b := 1/x;                                                               |
|-----------------------------------------------------------------------------|
|error: division by zero                                                      |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
|ii4 : code current                                                           |
|                                                                             |
|oo4 = /usr/local/share/Macaulay2/Macaulay2Doc/                               |
|      demo1.m2:8:10-8:13: --source code:                                     |
|           b := 1/x;                                                         |
+-----------------------------------------------------------------------------+
|ii5 : current                                                                |
|                                                                             |
|oo5 = 2-OP / 1                                                               |
|             local-fetch 0 0                                                 |
|                                                                             |
|oo5 : PseudocodeClosure                                                      |
+-----------------------------------------------------------------------------+
|ii6 : disassemble current                                                    |
|                                                                             |
|oo6 = (2-OP / 1 (local-fetch 0 0))                                           |
+-----------------------------------------------------------------------------+
|ii7 : value current                                                          |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3): error: division by|
|-----------------------------------------------------------------------------|
|zero                                                                         |
+-----------------------------------------------------------------------------+
|ii8 : x = 11                                                                 |
|                                                                             |
|oo8 = 11                                                                     |
+-----------------------------------------------------------------------------+
|ii9 : value current                                                          |
|                                                                             |
|       1                                                                     |
|oo9 = --                                                                     |
|      11                                                                     |
|                                                                             |
|oo9 : QQ                                                                     |
+-----------------------------------------------------------------------------+
|ii10 : continue                                                              |
|                                                                             |
|      34                                                                     |
|o10 = --                                                                     |
|      11                                                                     |
|                                                                             |
|o10 : QQ                                                                     |
+-----------------------------------------------------------------------------+

For the programmer
==================

The object current, is null.

currentColumnNumber -- current column number of the current input file
**********************************************************************

Synopsis
========

  * Usage:
        currentColumnNumber()
  * Outputs:
      * an integer, the current column number of the current input
        file

Description
===========

+--------------------------+
|i1 : currentColumnNumber()|
|                          |
|o1 = 0                    |
+--------------------------+

See also
========

  * currentRowNumber -- current row number of the
    current input file
  * currentFileName -- the current source file

For the programmer
==================

The object currentColumnNumber, is a compiled function.

currentFileDirectory -- the directory containing the current input file
***********************************************************************

Synopsis
========

  * Usage:
        currentFileDirectory
  * Outputs:
      * a string, the directory containing the current input
        file

Description
===========

+-------------------------+
|i1 : currentFileDirectory|
|                         |
|o1 = ./                  |
+-------------------------+

See also
========

  * currentFileName -- the current source file

For the programmer
==================

The object currentFileDirectory, is a string.

currentFileName -- the current source file
******************************************

Synopsis
========

  * Usage:
        currentFileName
  * Outputs:
      * a string, the name of the current source file

Description
===========

+--------------------+
|i1 : currentFileName|
|                    |
|o1 = currentString  |
+--------------------+

See also
========

  * currentRowNumber -- current row number of the
    current input file
  * currentColumnNumber -- current column number of
    the current input file
  * currentPosition -- the current position in the
    current source file

For the programmer
==================

The object currentFileName, is a string.

currentPosition -- the current position in the current source file
******************************************************************

Synopsis
========

  * Usage:
        currentPosition()
  * Outputs:
      * a file position, the current position in the
        source file

Description
===========

+----------------------------------------+
|i1 : currentPosition()                  |
|                                        |
|o1 = currentString:2:0                  |
|                                        |
|o1 : FilePosition                       |
+----------------------------------------+
|i2 : peek'_2 oo                         |
|                                        |
|o2 = FilePosition{"currentString", 2, 0}|
+----------------------------------------+

See also
========

  * currentRowNumber -- current row number of the
    current input file
  * currentColumnNumber -- current column number of
    the current input file

For the programmer
==================

The object currentPosition, is a function closure.

currentRowNumber -- current row number of the current input file
****************************************************************

Synopsis
========

  * Usage:
        currentRowNumber()
  * Outputs:
      * an integer, the current row number of the current input file

Description
===========

+-----------------------+
|i1 : currentRowNumber()|
|                       |
|o1 = 2                 |
+-----------------------+

See also
========

  * currentColumnNumber -- current column number of
    the current input file
  * currentFileName -- the current source file
  * currentPosition -- the current position in the
    current source file

For the programmer
==================

The object currentRowNumber, is a compiled function.

currentTime -- get the current time
***********************************

Synopsis
========

  * Usage:
        currentTime()
  * Outputs:
      * an integer, the current time, in seconds since 00:00:00
        1970-01-01 UTC, the beginning of the epoch

Description
===========

+------------------+
|i1 : currentTime()|
|                  |
|o1 = 1730471021   |
+------------------+

We can compute, roughly, how many years ago the epoch began as follows.

+------------------------------------------------------+
|i2 : currentTime() /( (365 + 97./400) * 24 * 60 * 60 )|
|                                                      |
|o2 = 54.836443678084                                  |
|                                                      |
|o2 : RR (of precision 53)                             |
+------------------------------------------------------+

We can also compute how many months account for the fractional part of that
number.

+-------------------------+
|i3 : 12 * (oo - floor oo)|
|                         |
|o3 = 10.03732413700803   |
|                         |
|o3 : RR (of precision 53)|
+-------------------------+

Compare that to the current date, available from a standard Unix command.

+-------------------------------+
|i4 : run "date"                |
|Fri Nov  1 10:23:41 AM EDT 2024|
|                               |
|o4 = 0                         |
+-------------------------------+

For the programmer
==================

The object currentTime, is a compiled function.

Database -- the class of all database files
*******************************************

Description
===========

A database file is just like a hash table, except both the keys and values have
to be strings.  In this example we create a database file, store a few entries,
remove an entry with remove, close the file, and then remove the
file.
+---------------------------------------------+
|i1 : filename = temporaryFileName () | ".dbm"|
|                                             |
|o1 = /tmp/M2-2534201-0/0.dbm                 |
+---------------------------------------------+
|i2 : x = openDatabaseOut filename            |
|                                             |
|o2 = /tmp/M2-2534201-0/0.dbm                 |
|                                             |
|o2 : Database                                |
+---------------------------------------------+
|i3 : x#"first" = "hi there"                  |
|                                             |
|o3 = hi there                                |
+---------------------------------------------+
|i4 : x#"first"                               |
|                                             |
|o4 = hi there                                |
+---------------------------------------------+
|i5 : x#"second" = "ho there"                 |
|                                             |
|o5 = ho there                                |
+---------------------------------------------+
|i6 : scanKeys(x,print)                       |
|second                                       |
|first                                        |
+---------------------------------------------+
|i7 : remove(x,"second")                      |
|                                             |
|o7 = ho there                                |
+---------------------------------------------+
|i8 : scanKeys(x,print)                       |
|first                                        |
+---------------------------------------------+
|i9 : close x                                 |
|                                             |
|o9 = 0                                       |
+---------------------------------------------+
|i10 : removeFile filename                    |
+---------------------------------------------+

See also
========

  * HashTable -- the class of all hash tables
  * String -- the class of all strings
  * removeFile -- remove a file

Functions and methods returning a database:
===========================================

  * "openDatabase(String)" -- see openDatabase, -- open a
    database file
  * "openDatabaseOut(String)" -- see openDatabaseOut, --
    open a database file for writing

Methods that use a database:
============================

  * "Database #? String" -- see #?, -- check existence of value in a
    list, hash table, database, or string
  * "Database # String" -- see BasicList # ZZ, -- get
    value from list, hash table, database, or string
  * "isOpen(Database)" -- see isOpen, -- whether a file or
    database is open
  * "keys(Database)" -- see keys, -- keys used in a hash table,
    dictionary, or database
  * "Manipulator Database" -- see Manipulator, -- the class
    of all file manipulators
  * "remove(Database,String)" -- see remove, -- remove an entry
    from a mutable hash table, list, or database
  * "scanKeys(Database,Function)" -- see scanKeys, -- apply a
    function to each key in a hash table or database

For the programmer
==================

The object Database, is a type, with ancestor
class Thing.

dd -- differential in a chain complex
*************************************

Description
===========

dd -- a symbol used as a key in a chain complex, under which are stored the
differentials.

The differentials are stored as the members in a chain complex map of degree
-1.  The map C.dd_i is the one whose source is the module C_i, and it is
arranged to be zero if no map has been stored in that spot.
+-----------------------------------+
|i1 : R = ZZ/101[a,b];              |
+-----------------------------------+
|i2 : C = resolution cokernel vars R|
|                                   |
|      1      2      1              |
|o2 = R  <-- R  <-- R  <-- 0        |
|                                   |
|     0      1      2      3        |
|                                   |
|o2 : ChainComplex                  |
+-----------------------------------+
|i3 : C.dd                          |
|                                   |
|          1               2        |
|o3 = 0 : R  <----------- R  : 1    |
|               | a b |             |
|                                   |
|          2                  1     |
|     1 : R  <-------------- R  : 2 |
|               {1} | -b |          |
|               {1} | a  |          |
|                                   |
|          1                        |
|     2 : R  <----- 0 : 3           |
|               0                   |
|                                   |
|o3 : ChainComplexMap               |
+-----------------------------------+
|i4 : C.dd_2                        |
|                                   |
|o4 = {1} | -b |                    |
|     {1} | a  |                    |
|                                   |
|             2      1              |
|o4 : Matrix R  <-- R               |
+-----------------------------------+

See also
========

  * ChainComplex -- the class of all chain complexes

For the programmer
==================

The object dd, is a symbol.

debugError -- a function to debug
*********************************

Synopsis
========

  * Usage:
        debugError()

Description
===========

In certain situations, after an error occurs, the offending code, in the form
of a function, will be stored in the variable debugError, so
the user can debug it by running it.

For the programmer
==================

The object debugError, is a compiled function.

debuggingMode -- whether to enter the debugger when an error occurs
*******************************************************************

Synopsis
========

  * Usage:
        debuggingMode = true
  * Consequences:
      * the debugger will be entered when an error occurs

For the programmer
==================

The object debuggingMode, is a Boolean value.

debugLevel -- current level debugging
*************************************

Synopsis
========

  * Usage:
        debugLevel = n
  * Inputs:
      * n, an integer,

Description
===========

Some M2 routines will display debugging information if debugLevel,
is set to a value greater than 0.

For the programmer
==================

The object debugLevel, is an integer.

decompose
*********

Description
===========

This function is a method function, defined in the core so multiple packages
can add methods to it.

See also
========

  * MinimalPrimes -- minimal primes and radical
    routines for ideals

Ways to use decompose:
======================

  * "decompose(Ideal)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal

For the programmer
==================

The object decompose, is a method function with options.

deepSplice -- remove all levels of subsequences from a sequence or list
***********************************************************************

Synopsis
========

  * Usage:
        deepSplice X
  * Inputs:
      * X, a basic list,
  * Outputs:
      * Y, a basic list, the new list resulting from
        replacing any element of X that is a sequence with its elements, at
        every level of nesting

Description
===========

Unlike the function splice, which removes a single nested level
of subsequences, deepSplice recursively flattens subsequences at all levels.

+------------------------------------------------------+
|i1 : X = {(), (0, (1, 2, (3, 4))), (5, (6, 7)), 8, 9};|
+------------------------------------------------------+
|i2 : splice X                                         |
|                                                      |
|o2 = {0, (1, 2, (3, 4)), 5, (6, 7), 8, 9}             |
|                                                      |
|o2 : List                                             |
+------------------------------------------------------+
|i3 : deepSplice X                                     |
|                                                      |
|o3 = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}                   |
|                                                      |
|o3 : List                                             |
+------------------------------------------------------+

deepSplice does not alter elements that are lists, arrays, or anything other
than sequences.

+------------------------------------------------------+
|i4 : Z = {(), {0, {1, 2, (3, 4)}}, [5, [6, 7]], 8, 9};|
+------------------------------------------------------+
|i5 : deepSplice Z                                     |
|                                                      |
|o5 = {{0, {1, 2, (3, 4)}}, [5, [6, 7]], 8, 9}         |
|                                                      |
|o5 : List                                             |
+------------------------------------------------------+

deepSplice works on sequences, too, and all other objects of class,
BasicList. The output matches the class of the input.

+------------------------------------------------------------+
|i6 : deepSplice ((), (0, (1, 2, (3, 4))), (5, (6, 7)), 8, 9)|
|                                                            |
|o6 = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9)                         |
|                                                            |
|o6 : Sequence                                               |
+------------------------------------------------------------+

Even if X is a MutableList, deepSplice returns a new list
rather than altering the definition of X.

+-------------------------------+
|i7 : M = new MutableList from X|
|                               |
|o7 = MutableList{...5...}      |
|                               |
|o7 : MutableList               |
+-------------------------------+
|i8 : deepSplice M              |
|                               |
|o8 = MutableList{...10...}     |
|                               |
|o8 : MutableList               |
+-------------------------------+
|i9 : M                         |
|                               |
|o9 = MutableList{...5...}      |
|                               |
|o9 : MutableList               |
+-------------------------------+

See also
========

  * flatten -- flatten a nested list or a matrix
  * splice -- remove subsequences from a sequence or list
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use deepSplice:
=======================

  * "deepSplice(BasicList)"

For the programmer
==================

The object deepSplice, is a compiled function.

default -- default member of a family
*************************************

Synopsis
========

  * Usage:
        default T
  * Inputs:
      * T
  * Outputs:
      * the default member of the family shadowed by T

Description
===========

+---------------------------+
|i1 : default RR            |
|                           |
|o1 = RR                    |
|       53                  |
|                           |
|o1 : RealField             |
+---------------------------+
|i2 : defaultPrecision = 100|
|                           |
|o2 = 100                   |
+---------------------------+
|i3 : default CC            |
|                           |
|o3 = CC                    |
|       100                 |
|                           |
|o3 : ComplexField          |
+---------------------------+
This function is used internally, and its implementation may change.

See also
========

  * defaultPrecision -- default precision of numbers

Ways to use default:
====================

  * "default(InexactFieldFamily)"

For the programmer
==================

The object default, is a method function.

defaultPrecision -- default precision of numbers
************************************************

Synopsis
========

  * Usage:
        defaultPrecision = n
  * Inputs:
      * n, an integer,
  * Consequences:
      * henceforth, when a real or complex number is to be created, and no
        precision is otherwise specified, the precision will be n

Description
===========

+-------------------------------------+
|i1 : defaultPrecision                |
|                                     |
|o1 = 53                              |
+-------------------------------------+
|i2 : 1/3.                            |
|                                     |
|o2 = .3333333333333333               |
|                                     |
|o2 : RR (of precision 53)            |
+-------------------------------------+
|i3 : defaultPrecision=100            |
|                                     |
|o3 = 100                             |
+-------------------------------------+
|i4 : 1/3.                            |
|                                     |
|o4 = .3333333333333333333333333333335|
|                                     |
|o4 : RR (of precision 100)           |
+-------------------------------------+
|i5 : RR[x]                           |
|                                     |
|o5 = RR   [x]                        |
|       100                           |
|                                     |
|o5 : PolynomialRing                  |
+-------------------------------------+
|i6 : numeric pi                      |
|                                     |
|o6 = 3.141592653589793238462643383279|
|                                     |
|o6 : RR (of precision 100)           |
+-------------------------------------+

For the programmer
==================

The object defaultPrecision, is an integer.

Degree -- specify the degree of a map
*************************************

Synopsis
========

  * Usage:
        map(..., Degree=>d)

Description
===========

Specifies that the degree of the map created should be d. The degree may be an
integer or a list of integers (multidegree). The length of the list should be
the same as the length of a degree for the ring, see degreeLength.

+--------------------------------------------+
|i1 : R = ZZ/101[x]                          |
|                                            |
|o1 = R                                      |
|                                            |
|o1 : PolynomialRing                         |
+--------------------------------------------+
|i2 : p = map(R^1, R^1, {{x^4}})             |
|                                            |
|o2 = | x4 |                                 |
|                                            |
|             1      1                       |
|o2 : Matrix R  <-- R                        |
+--------------------------------------------+
|i3 : isHomogeneous p                        |
|                                            |
|o3 = false                                  |
+--------------------------------------------+
|i4 : q = map(R^1, R^1, {{x^4}}, Degree => 4)|
|                                            |
|o4 = | x4 |                                 |
|                                            |
|             1      1                       |
|o4 : Matrix R  <-- R                        |
+--------------------------------------------+
|i5 : isHomogeneous q                        |
|                                            |
|o5 = true                                   |
+--------------------------------------------+

See also
========

  * map -- make a map
  * matrix -- make a matrix
  * inducedMap(...,Degree=>...)
    -- specify the degree of a
    map
  * matrix(...,Degree=>...) -- create a matrix from a
    doubly-nested list of ring elements or matrices

Functions with optional argument named Degree:
==============================================

  * "basis(...,Degree=>...)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * cohomology(...,Degree=>...) (missing documentation)
  * "map(...,Degree=>...)"
  * inducedMap(...,Degree=>...)
    -- specify the degree of a
    map
  * "matrix(...,Degree=>...)" -- see matrix(List), --
    create a matrix from a doubly-nested list of ring elements or matrices

For the programmer
==================

The object Degree, is a symbol.

degree
******

Description
===========

Degree is a common name, meaning different things for different kinds of
mathematical objects. In Macaulay2, there are currently three related, yet
different notions of degree:

Degree of polynomials or vectors of such
----------------------------------------

  * degree(RingElement)
  * degree(Vector)
  * degree(RingElement,RingElement)
    -- degree with respect to a variable
  * degree(ProjectiveHilbertPolynomial)

Degree of ideals, varieties and modules
---------------------------------------

  * degree(Ideal)
  * degree(Ring)
  * degree(Module)
  * degree(ProjectiveVariety) (Varieties)

Degree of homomorphisms
-----------------------

  * degree(Matrix) (missing documentation)
  * degree(ChainComplexMap) (missing documentation)
  * degree(GradedModuleMap) (missing documentation)

See also
========

  * degreeLength -- the length of the degree vector
  * degreesRing -- the ring or monoid of degrees

Ways to use degree:
===================

  * "degree(BettiTally)" -- see BettiTally, -- the class of
    all Betti tallies
  * degree(ChainComplexMap) (missing documentation)
  * degree(GradedModuleMap) (missing documentation)
  * degree(Ideal)
  * degree(Matrix) (missing documentation)
  * degree(Module)
  * degree(MonoidElement) (missing documentation)
  * degree(ProjectiveHilbertPolynomial)
  * degree(ProjectiveVariety) (Varieties)
  * degree(Ring)
  * degree(RingElement)
  * "degree(Vector)" -- see degree(RingElement),
  * degree(RingElement,RingElement)
    -- degree with respect to a variable
  * degree(SheafMap) (missing documentation)

For the programmer
==================

The object degree, is a method function.

degree(Ideal)
*************

Synopsis
========

  * Function: degree,
  * Usage:
        degree I
  * Inputs:
      * I, in a polynomial ring or quotient of a polynomial ring
  * Outputs:
      * an integer, the degree of the zero set of I

Description
===========

The degree of an ideal I in a ring S is the degree of the module S/I.  See
degree(Module), for more details.
+----------------------------------------+
|i1 : S = QQ[a..f];                      |
+----------------------------------------+
|i2 : I = ideal(a^5, b^5, c^5, d^5, e^5);|
|                                        |
|o2 : Ideal of S                         |
+----------------------------------------+
|i3 : degree I                           |
|                                        |
|o3 = 3125                               |
+----------------------------------------+
|i4 : degree(S^1/I)                      |
|                                        |
|o4 = 3125                               |
+----------------------------------------+
If the ideal is not homogeneous, then the degree returned is the degree of the
ideal of initial monomials (which is homogeneous).  If the monomial order is a
degree order (the default), this is the same as the degree of the projective
closure of the zero set of I.
+-----------------------------------------------------------------------------+
|i5 : I = intersect(ideal(a-1,b-1,c-1),ideal(a-2,b-1,c+1),ideal(a-4,b+7,c-3/4 |
|                                                                             |
|o5 : Ideal of S                                                              |
|-----------------------------------------------------------------------------|
|));                                                                          |
+-----------------------------------------------------------------------------+
|i6 : degree I                                                                |
|                                                                             |
|o6 = 3                                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * dim -- compute the Krull dimension
  * codim -- compute the codimension
  * genus (missing documentation)
  * genera (missing documentation)
  * hilbertSeries -- compute the Hilbert series
  * reduceHilbert -- reduce a Hilbert series expression
  * poincare -- assemble degrees of a ring, module, or ideal
    into a polynomial
  * hilbertPolynomial -- compute the Hilbert
    polynomial

Ways to use this method:
========================

  * degree(Ideal)

degree(ProjectiveHilbertPolynomial)
***********************************

Synopsis
========

  * Function: degree,
  * Usage:
        degree f
  * Inputs:
      * f, usually returned via hilbertPolynomial,
  * Outputs:
      * an integer, the degree of any graded module having this
        Hilbert polynomial

Description
===========

This degree is obtained from the Hilbert polynomial f as follows: if f = d
z^e/e! + lower terms in z, then d is returned. This is the lead coefficient of
the highestP^e in the ProjectiveHilbertPolynomial,
display.
+--------------------------------+
|i1 : R = QQ[a..d];              |
+--------------------------------+
|i2 : I = ideal(a^3, b^2, a*b*c);|
|                                |
|o2 : Ideal of R                 |
+--------------------------------+
|i3 : F = hilbertPolynomial I    |
|                                |
|o3 = - 2*P  + 4*P               |
|          0      1              |
|                                |
|o3 : ProjectiveHilbertPolynomial|
+--------------------------------+
|i4 : degree F                   |
|                                |
|o4 = 4                          |
+--------------------------------+
The degree of this polynomial may be recovered using dim,:
+----------+
|i5 : dim F|
|          |
|o5 = 1    |
+----------+
The dimension as a projective variety is also one less that the Krull dimension
of R/I
+--------------------------+
|i6 : (dim I - 1, degree I)|
|                          |
|o6 = (1, 4)               |
|                          |
|o6 : Sequence             |
+--------------------------+

See also
========

  * hilbertPolynomial -- compute the Hilbert
    polynomial

Ways to use this method:
========================

  * degree(ProjectiveHilbertPolynomial)

degree(Ring)
************

Synopsis
========

  * Function: degree,
  * Usage:
        degree R
  * Inputs:
      * R, a quotient of a polynomial ring
  * Outputs:
      * an integer, the degree of R

Description
===========

If R = S/I, where S is a polynomial ring, then the degree of R is by definition
the degree of I, or the degree of the S-module R.  See degree(Module),
for more details.
+---------------------------------------------+
|i1 : R = QQ[a..d]/(a*d-b*c, b^2-a*c, c^2-b*d)|
|                                             |
|o1 = R                                       |
|                                             |
|o1 : QuotientRing                            |
+---------------------------------------------+
|i2 : degree R                                |
|                                             |
|o2 = 3                                       |
+---------------------------------------------+

See also
========

  * degree(Module)

Ways to use this method:
========================

  * degree(Ring)

degree(RingElement)
*******************

Synopsis
========

  * Function: degree,
  * Usage:
        degree f
  * Inputs:
      * f, a ring element, or vector,
  * Outputs:
      * a list, the degree or multidegree of f

Description
===========

In Macaulay2, the degree of a polynomial is a list of integers. This is to
accommodate polynomial rings having multigradings.  The usual situation is when
the ring has the usual grading: each variable has length 1.
+-----------------------+
|i1 : R = QQ[a..d];     |
+-----------------------+
|i2 : degree (a^3-b-1)^2|
|                       |
|o2 = {6}               |
|                       |
|o2 : List              |
+-----------------------+
When not dealing with multigraded rings, obtaining the degree as a number is
generally more convenient:
+-----------------------------+
|i3 : first degree (a^3-b-1)^2|
|                             |
|o3 = 6                       |
+-----------------------------+
+-------------------------------------+
|i4 : S = QQ[a..d,Degrees=>{1,2,3,4}];|
+-------------------------------------+
|i5 : first degree (a+b+c^3)          |
|                                     |
|o5 = 9                               |
+-------------------------------------+
+------------------------------------------------------+
|i6 : T = QQ[a..d,Degrees=>{{0,1},{1,0},{-1,1},{3,4}}];|
+------------------------------------------------------+
|i7 : degree c                                         |
|                                                      |
|o7 = {-1, 1}                                          |
|                                                      |
|o7 : List                                             |
+------------------------------------------------------+
In a multigraded ring, the degree of a polynomial whose terms have different
degrees is perhaps non-intuitive: it is the maximum (in each of the component
degree) over each term:
+--------------------+
|i8 : degree c^5     |
|                    |
|o8 = {-5, 5}        |
|                    |
|o8 : List           |
+--------------------+
|i9 : degree d       |
|                    |
|o9 = {3, 4}         |
|                    |
|o9 : List           |
+--------------------+
|i10 : degree (c^5+d)|
|                    |
|o10 = {3, 5}        |
|                    |
|o10 : List          |
+--------------------+

See also
========

  * isHomogeneous -- whether something is homogeneous
    (graded)
  * degreeLength -- the length of the degree vector

Ways to use this method:
========================

  * degree(RingElement)
  * "degree(Vector)"

degree(RingElement,RingElement) -- degree with respect to a variable
********************************************************************

Synopsis
========

  * Function: degree,
  * Usage:
        degree(x,f)
  * Inputs:
      * x, a variable in the same ring
      * f, in a polynomial ring R
  * Outputs:
      * an integer, highest power of x occurring in f

Description
===========

+----------------------------------+
|i1 : R = QQ[a..d];                |
+----------------------------------+
|i2 : degree(b, a*b^5+b^7-3*a^10-3)|
|                                  |
|o2 = 7                            |
+----------------------------------+

Ways to use this method:
========================

  * degree(RingElement,RingElement)
    -- degree with respect to a variable

degreeLength -- the length of the degree vector
***********************************************

Synopsis
========

  * Usage:
        degreeLength A
  * Inputs:
      * A, a ring, or a monoid,
  * Outputs:
      * an integer, the length of a multidegree vector used as a
        degree of elements of A.

Description
===========

Example degreeLength ZZ degreeLength(ZZ[]) degreeLength(ZZ[x])
degreeLength(ZZ[x, Degrees => {{1,2,3}}]) degreeLength(ZZ[x,y,z, DegreeRank =>
3]) degreeLength(GF 9)

See also
========

  * degree
  * degreesRing -- the ring or monoid of degrees
  * degreesMonoid -- the ring or monoid of degrees
  * monoid(...,DegreeRank=>...)
    -- specify the degrees of the
    variables

Ways to use degreeLength:
=========================

  * "degreeLength(Monoid)"
  * "degreeLength(Ring)"

For the programmer
==================

The object degreeLength, is a method function.

DegreeOrder -- sort primarily by degree
***************************************

Description
===========

DegreeOrder -- an optional argument for use with certain functions, used to
specify sort order.

Functions with optional argument named DegreeOrder:
===================================================

  * rsort(...,DegreeOrder=>...)
    -- specify Ascending,
    Descending, or null
  * sort(...,DegreeOrder=>...)
    -- specify Ascending,
    Descending, or null
  * sortColumns(...,DegreeOrder=>...)
    -- specify Ascending,
    Descending, or null

For the programmer
==================

The object DegreeOrder, is a symbol.

degrees -- degrees of generators
********************************

Ways to use degrees:
====================

  * degrees(CoherentSheaf) (missing documentation)
  * degrees(Matrix) -- degrees of target and source
  * "degrees(FractionField)" -- see degrees(Ring), --
    degrees of generators
  * "degrees(Ideal)" -- see degrees(Ring), -- degrees
    of generators
  * "degrees(Module)" -- see degrees(Ring), -- degrees
    of generators
  * "degrees(Monoid)" -- see degrees(Ring), -- degrees
    of generators
  * "degrees(QuotientRing)" -- see degrees(Ring), --
    degrees of generators
  * degrees(Ring) -- degrees of generators

For the programmer
==================

The object degrees, is a method function.

degrees(Matrix) -- degrees of target and source
***********************************************

Synopsis
========

  * Function: degrees,
  * Usage:
        degrees f
  * Inputs:
      * f
  * Outputs:
      * a list {x,y} where x is the list of degrees of the target of f and y is
        the list of degrees of the source of f.

Description
===========

+------------------------------------------------------+
|i1 : S = ZZ/101[x,y,z,Degrees => {{2,3},{1,2},{2,0}}];|
+------------------------------------------------------+
|i2 : degrees vars S                                   |
|                                                      |
|o2 = {{{0, 0}}, {{2, 3}, {1, 2}, {2, 0}}}             |
|                                                      |
|o2 : List                                             |
+------------------------------------------------------+

See also
========

  * degreeLength -- the length of the degree vector
  * degreesRing -- the ring or monoid of degrees

Ways to use this method:
========================

  * degrees(Matrix) -- degrees of target and source

degrees(Ring) -- degrees of generators
**************************************

Synopsis
========

  * Function: degrees,
  * Usage:
        degrees A
  * Inputs:
      * A, a ring, an ideal, a module,
        or a monoid,
  * Outputs:
      * a list, the list of multi-degrees for the generators of A

Description
===========

+------------------------------------------------------+
|i1 : R = ZZ/101[x,y,z];                               |
+------------------------------------------------------+
|i2 : degrees R                                        |
|                                                      |
|o2 = {{1}, {1}, {1}}                                  |
|                                                      |
|o2 : List                                             |
+------------------------------------------------------+
|i3 : S = ZZ/101[x,y,z,Degrees => {{2,3},{1,2},{2,0}}];|
+------------------------------------------------------+
|i4 : degrees S                                        |
|                                                      |
|o4 = {{2, 3}, {1, 2}, {2, 0}}                         |
|                                                      |
|o4 : List                                             |
+------------------------------------------------------+
This function also applies to ideals, modules, and monoids.
+-----------------------------+
|i5 : I = ideal"xy2,xyz,y3"   |
|                             |
|               2          3  |
|o5 = ideal (x*y , x*y*z, y ) |
|                             |
|o5 : Ideal of S              |
+-----------------------------+
|i6 : degrees I               |
|                             |
|o6 = {{4, 7}, {5, 5}, {3, 6}}|
|                             |
|o6 : List                    |
+-----------------------------+
+------------------------------+
|i7 : degrees R^5              |
|                              |
|o7 = {{0}, {0}, {0}, {0}, {0}}|
|                              |
|o7 : List                     |
+------------------------------+
|i8 : degrees R^{1,2,3,4}      |
|                              |
|o8 = {{-1}, {-2}, {-3}, {-4}} |
|                              |
|o8 : List                     |
+------------------------------+

See also
========

  * degreeLength -- the length of the degree vector
  * degreesRing -- the ring or monoid of degrees

Ways to use this method:
========================

  * "degrees(FractionField)"
  * "degrees(Ideal)"
  * "degrees(Module)"
  * "degrees(Monoid)"
  * "degrees(QuotientRing)"
  * degrees(Ring) -- degrees of generators

degreesRing -- the ring or monoid of degrees
********************************************

Synopsis
========

  * Usage:
        degreesRing A
        degreesMonoid A
  * Inputs:
      * A, a ring, or a monoid,
  * Outputs:
      * a polynomial ring, or a monoid, a
        Laurent polynomial ring or monoid with inverses;

Description
===========

Given a ring or monoid A with degree length, $n$,
degreesRing and degreesMonoid produce a Laurent polynomial ring or monoid of
Laurent monomials in $n$ variables, respectively, whose monomials correspond to
the degrees of elements of A. The variable has no subscript when $n=1$.

+-----------------------------------------------------------------------------+
|i1 : A = ZZ[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : degreesRing A                                                           |
|                                                                             |
|o2 = ZZ[T]                                                                   |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : degreesMonoid A                                                         |
|                                                                             |
|o3 = monoid[T, Degrees => {1}, MonomialOrder => {MonomialSize => 32},        |
|                                                {Weights => {-1}   }         |
|                                                {GroupLex => 1     }         |
|                                                {Position => Up    }         |
|                                                                             |
|o3 : GeneralOrderedMonoid                                                    |
|-----------------------------------------------------------------------------|
|Inverses => true, Global => false]                                           |
+-----------------------------------------------------------------------------+
|i4 : degrees oo                                                              |
|                                                                             |
|o4 = {{1}}                                                                   |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : heft A                                                                  |
|                                                                             |
|o5 = {1}                                                                     |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : R = QQ[x,y, Degrees => {{1,-2}, {2,-1}}];                               |
+-----------------------------------------------------------------------------+
|i7 : degreesRing R                                                           |
|                                                                             |
|o7 = ZZ[T ..T ]                                                              |
|         0   1                                                               |
|                                                                             |
|o7 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i8 : degreesMonoid R                                                         |
|                                                                             |
|o8 = monoid[T ..T , Degrees => {1, 0}, MonomialOrder => {MonomialSize => 32},|
|             0   1                                      {Weights => {-1..0}} |
|                                                        {GroupLex => 2     } |
|                                                        {Position => Up    } |
|                                                                             |
|o8 : GeneralOrderedMonoid                                                    |
|-----------------------------------------------------------------------------|
|Inverses => true, Global => false]                                           |
+-----------------------------------------------------------------------------+
|i9 : degrees oo                                                              |
|                                                                             |
|o9 = {{1}, {0}}                                                              |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+
|i10 : heft R                                                                 |
|                                                                             |
|o10 = {1, 0}                                                                 |
|                                                                             |
|o10 : List                                                                   |
+-----------------------------------------------------------------------------+
|i11 : S = QQ[x,y, Degrees => {-2,1}];                                        |
+-----------------------------------------------------------------------------+
|i12 : degreesRing S                                                          |
|                                                                             |
|o12 = ZZ[T]                                                                  |
|                                                                             |
|o12 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i13 : degreesMonoid S                                                        |
|                                                                             |
|o13 = monoid[T, Degrees => {{}}, MonomialOrder => {MonomialSize => 32},      |
|                                                  {Weights => {-1}   }       |
|                                                  {GroupLex => 1     }       |
|                                                  {Position => Up    }       |
|                                                                             |
|o13 : GeneralOrderedMonoid                                                   |
|-----------------------------------------------------------------------------|
|Inverses => true, Global => false]                                           |
+-----------------------------------------------------------------------------+
|i14 : degrees oo                                                             |
|                                                                             |
|o14 = {{}}                                                                   |
|                                                                             |
|o14 : List                                                                   |
+-----------------------------------------------------------------------------+
|i15 : heft S                                                                 |
+-----------------------------------------------------------------------------+

Note that in the last example the ring does not have a heft vector.

See Hilbert series, and polynomials,
of modules over A are elements of its degrees ring over ZZ.  The
monomial ordering is chosen so that the Hilbert series, which has an infinite
number of terms, is bounded above by the weight. Elements of this ring are also
used as variables for Poincare polynomials generated by poincare,
and poincareN.

+-----------------------------------------------------------------+
|i16 : R = QQ[x,y, Degrees => {{1,-2,0}, {2,-1,1}}];              |
+-----------------------------------------------------------------+
|i17 : use degreesRing R                                          |
|                                                                 |
|o17 = ZZ[T ..T ]                                                 |
|          0   2                                                  |
|                                                                 |
|o17 : PolynomialRing                                             |
+-----------------------------------------------------------------+
|i18 : hilbertSeries module ideal vars R                          |
|                                                                 |
|         -2    2 -1      3 -3                                    |
|      T T   + T T  T  - T T  T                                   |
|       0 1     0 1  2    0 1  2                                  |
|o18 = -------------------------                                  |
|             2 -1           -2                                   |
|       (1 - T T  T )(1 - T T  )                                  |
|             0 1  2       0 1                                    |
|                                                                 |
|o18 : Expression of class Divide                                 |
+-----------------------------------------------------------------+
|i19 : (1+T_1+T_2^2)^3                                            |
|                                                                 |
|       3     2 2     2       4       2          6     4     2    |
|o19 = T  + 3T T  + 3T  + 3T T  + 6T T  + 3T  + T  + 3T  + 3T  + 1|
|       1     1 2     1     1 2     1 2     1    2     2     2    |
|                                                                 |
|o19 : ZZ[T ..T ]                                                 |
|          0   2                                                  |
+-----------------------------------------------------------------+

See also
========

  * use -- install or activate object
  * heft -- heft vector of ring or monoid
  * poincare -- assemble degrees of a ring, module, or ideal
    into a polynomial
  * poincareN -- assemble degrees into polynomial
  * hilbertFunction -- the Hilbert function
  * hilbertPolynomial -- compute the Hilbert
    polynomial
  * hilbertSeries -- compute the Hilbert series
  * degreeLength -- the length of the degree vector
  * monoid(...,DegreeRank=>...)
    -- specify the degrees of the
    variables

Ways to use degreesRing:
========================

  * "degreesRing(Monoid)"
  * "degreesRing(Ring)"
  * degreesRing(List) -- the ring or monoid of
    degrees
  * "degreesRing(ZZ)" -- see degreesRing(List), --
    the ring or monoid of degrees

For the programmer
==================

The object degreesRing, is a method function.

degreesRing(List) -- the ring or monoid of degrees
**************************************************

Synopsis
========

  * Function: degreesRing,
  * Usage:
        degreesRing L
        degreesMonoid L
        degreesRing n
        degreesMonoid n
  * Inputs:
      * a list, or an integer, see heft vectors,
        or degreeLength,;
  * Outputs:
      * A, a monoid, or a polynomial ring,
        a monoid of Laurent monomials or ring of Laurent polynomials.

Description
===========

These functions produce either a monoid of Laurent monomials or Laurent
polynomial ring $A$ in n variables, where n is the length of the list L, which
is typically a heft vector. Each monomial in the output
corresponds to a degree vector for a ring with heft vector L or degree length n
and no heft vector.

When a list is given, the variables of the output have degrees given by the
elements of L and weights are the negative of the degrees. When an integer is
given, then the number of variables is n, the degrees are all {}, and the
weights are all -1.

+-----------------------------------------------------------------------------+
|i1 : degreesMonoid {1,2,3}                                                   |
|                                                                             |
|o1 = monoid[T ..T , Degrees => {1..3}, MonomialOrder => {MonomialSize => 32  |
|             0   2                                      {Weights => {-1, -2, |
|                                                        {GroupLex => 3       |
|                                                        {Position => Up      |
|                                                                             |
|o1 : GeneralOrderedMonoid                                                    |
|-----------------------------------------------------------------------------|
|   }, Inverses => true, Global => false]                                     |
|-3}}                                                                         |
|   }                                                                         |
|   }                                                                         |
+-----------------------------------------------------------------------------+
|i2 : degreesMonoid 3                                                         |
|                                                                             |
|o2 = monoid[T ..T , Degrees => {3:{}}, MonomialOrder => {MonomialSize => 32},|
|             0   2                                      {Weights => {3:-1} } |
|                                                        {GroupLex => 3     } |
|                                                        {Position => Up    } |
|                                                                             |
|o2 : GeneralOrderedMonoid                                                    |
|-----------------------------------------------------------------------------|
|Inverses => true, Global => false]                                           |
+-----------------------------------------------------------------------------+

The monomial ordering used in the degrees ring is RevLex so the polynomials in
it will be displayed with the smallest exponents first, because such
polynomials are often used as Hilbert series.

Assign the degrees ring to a global variable or call use(Monoid),
to assign the indeterminates of the ring or monoid to global
variables.

+-----------------------------------------------------------------------------+
|i3 : assert instance(T_0, IndexedVariable)                                   |
+-----------------------------------------------------------------------------+
|i4 : use degreesMonoid 3                                                     |
|                                                                             |
|o4 = monoid[T ..T , Degrees => {3:{}}, MonomialOrder => {MonomialSize => 32},|
|             0   2                                      {Weights => {3:-1} } |
|                                                        {GroupLex => 3     } |
|                                                        {Position => Up    } |
|                                                                             |
|o4 : GeneralOrderedMonoid                                                    |
|-----------------------------------------------------------------------------|
|Inverses => true, Global => false]                                           |
+-----------------------------------------------------------------------------+
|i5 : assert instance(T_0, degreesMonoid 3)                                   |
+-----------------------------------------------------------------------------+
|i6 : A = degreesRing 4                                                       |
|                                                                             |
|o6 = A                                                                       |
|                                                                             |
|o6 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i7 : assert instance(T_0, degreesRing 4)                                     |
+-----------------------------------------------------------------------------+

See also
========

  * use -- install or activate object
  * heft -- heft vector of ring or monoid
  * degreeLength -- the length of the degree vector
  * division in polynomial rings with monomials less than 1

Ways to use this method:
========================

  * degreesRing(List) -- the ring or monoid of
    degrees
  * "degreesRing(ZZ)"

delete -- delete some elements of a list
****************************************

Synopsis
========

  * Usage:
        delete(x, A)
  * Inputs:
      * A, list or sequence
      * x, thing
  * Outputs:
      * A2, a new list from A with every occurrence of x removed

Description
===========

+-------------------------------------+
|i1 : delete(c, {a,b,c,d,e,a,b,c,d,e})|
|                                     |
|o1 = {a, b, d, e, a, b, d, e}        |
|                                     |
|o1 : List                            |
+-------------------------------------+

Equality is determined with ===, which is quick, but
not always intuitive. For instance, in the next example, the first item in the
list is not removed, because it is an element of QQ and will not match an
element of ZZ.

+-------------------------------+
|i2 : delete(1, {2/2, 3/2, 4/2})|
|                               |
|         3                     |
|o2 = {1, -, 2}                 |
|         2                     |
|                               |
|o2 : List                      |
+-------------------------------+

To delete items from a list by index, rather than value, see drop.

See also
========

  * drop -- drop some elements from a list or sequence.
  * positions -- which elements of a list satisfy a condition
  * select -- select from a list, hash table, or string
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use delete:
===================

  * "delete(Thing,BasicList)"

For the programmer
==================

The object delete, is a method function.

demark -- insert a string between elements of a list of strings
***************************************************************

Synopsis
========

  * Usage:
        demark(d, L)
  * Inputs:
      * d, a string,
      * L, a list, of strings
  * Outputs:
      * s, a string, the string obtained by concatenating the
        elements of L, with copies of the string d inserted between each pair

Description
===========

+------------------------------------------------------+
|i1 : demark("+", a..f)                                |
|                                                      |
|o1 = a+b+c+d+e+f                                      |
+------------------------------------------------------+
|i2 : demark(" and ", 6:"more")                        |
|                                                      |
|o2 = more and more and more and more and more and more|
+------------------------------------------------------+

To achieve a similar insertion while keeping the output as a list, see
mingle.

+------------------------------------------------------------------+
|i3 : mingle(6: "more", 5: "and")                                  |
|                                                                  |
|o3 = {more, and, more, and, more, and, more, and, more, and, more}|
|                                                                  |
|o3 : List                                                         |
+------------------------------------------------------------------+

See also
========

  * insert -- copy a list, inserting an element
  * join -- join lists, sequences, and iterable objects
  * mingle -- mingle elements of several lists
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

For the programmer
==================

The object demark, is a function closure.

denominator -- denominator of a fraction
****************************************

Synopsis
========

  * Usage:
        denominator x
  * Inputs:
      * x, a fraction
  * Outputs:
      * the denominator of x

Description
===========

+----------------------+
|i1 : denominator (4/6)|
|                      |
|o1 = 3                |
+----------------------+

+---------------------------------+
|i2 : R = frac(ZZ[x,y]);          |
+---------------------------------+
|i3 : denominator((x+2*y-3)/(x-y))|
|                                 |
|o3 = x - y                       |
|                                 |
|o3 : ZZ[x..y]                    |
+---------------------------------+

denominator also works with Hilbert series.
+---------------------------------+
|i4 : R = QQ[a..d]/(a^2,b^2,c^3); |
+---------------------------------+
|i5 : hf = hilbertSeries R        |
|                                 |
|           2    3    4     5    7|
|     1 - 2T  - T  + T  + 2T  - T |
|o5 = ----------------------------|
|                      4          |
|               (1 - T)           |
|                                 |
|o5 : Expression of class Divide  |
+---------------------------------+
|i6 : denominator hf              |
|                                 |
|            4                    |
|o6 = (1 - T)                     |
|                                 |
|o6 : Expression of class Product |
+---------------------------------+

For a Laurent polynomial in a ring with inverses of variables, it gives the
monomial needed to clear all the denominators in each of the terms.

+---------------------------------------------------------+
|i7 : R = QQ[x,y,z,Inverses => true, MonomialOrder => Lex]|
|                                                         |
|o7 = R                                                   |
|                                                         |
|o7 : PolynomialRing                                      |
+---------------------------------------------------------+
|i8 : denominator (x*y^-1+y*z^-2+1+y^-1*z^-1)             |
|                                                         |
|        2                                                |
|o8 = y*z                                                 |
|                                                         |
|o8 : R                                                   |
+---------------------------------------------------------+

See also
========

  * numerator -- numerator of a fraction
  * fraction fields
  * hilbertSeries -- compute the Hilbert series

Ways to use denominator:
========================

  * "denominator(Divide)"

For the programmer
==================

The object denominator, is a method function.

Descending -- specify descending order
**************************************

Description
===========

Descending -- a symbol used as a value for optional arguments
DegreeOrder, and MonomialOrder.

For the programmer
==================

The object Descending, is a symbol.

Descent
*******

Description
===========

A type of mutable hash table used by showUserStructure,
see showClassStructure, and
showStructure, to display their tree of results conveniently.

For the programmer
==================

The object Descent, is a type, with ancestor
classes MutableHashTable, < HashTable
< Thing.

Describe -- the class of the output of describe
***********************************************

Description
===========

This is a type of Holder, that contains the Expression,
produced by the method Describe.

For the programmer
==================

The object Describe, is a wrapper type,
with ancestor classes Holder, < Expression <
BasicList < Thing.

describe -- real description
****************************

Synopsis
========

  * Usage:
        describe X
  * Inputs:
      * X, a thing,
  * Outputs:
      * an expression,

Description
===========

describe X returns an Expression containing the real description of X,
bypassing the feature that causes certain types of things to acquire, for
brevity, the names of global variables to which they are assigned.

For example, it also displays the options used at creation of polynomial rings.

+-----------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c_1,c_2];                                          |
+-----------------------------------------------------------------------+
|i2 : R                                                                 |
|                                                                       |
|o2 = R                                                                 |
|                                                                       |
|o2 : PolynomialRing                                                    |
+-----------------------------------------------------------------------+
|i3 : describe R                                                        |
|                                                                       |
|      ZZ                                                               |
|o3 = ---[a..b, c ..c , Degrees => {4:1}, Heft => {1}]                  |
|     101        1   2                                                  |
+-----------------------------------------------------------------------+
|i4 : toString describe R                                               |
|                                                                       |
|o4 = (ZZ/101)[a..b, c_1..c_2, Degrees => {4:1}, Heft => {1}]           |
+-----------------------------------------------------------------------+
|i5 : toExternalString R                                                |
|                                                                       |
|o5 = (ZZ/101)[a..b, c_1..c_2, Degrees => {4:1}, Heft => {1}]           |
+-----------------------------------------------------------------------+
|i6 : QQ[x, dx, WeylAlgebra => { x => dx }]                             |
|                                                                       |
|o6 = QQ[x, dx]                                                         |
|                                                                       |
|o6 : PolynomialRing, 1 differential variable(s)                        |
+-----------------------------------------------------------------------+
|i7 : describe oo                                                       |
|                                                                       |
|o7 = QQ[x, dx, Degrees => {2:1}, Heft => {1}, WeylAlgebra => {{x, dx}}]|
+-----------------------------------------------------------------------+

See also
========

  * toString -- convert to a string
  * toExternalString -- convert to a readable string

Ways to use describe:
=====================

  * "describe(FractionField)"
  * "describe(GaloisField)"
  * "describe(Matrix)"
  * "describe(Module)"
  * "describe(Monoid)"
  * "describe(PolynomialRing)"
  * "describe(QuotientRing)"
  * "describe(RingMap)"
  * "describe(Thing)"
  * "describe(Vector)"

For the programmer
==================

The object describe, is a method function with a single argument.

determinant -- determinant of a matrix
**************************************

Synopsis
========

  * Usage:
        det M
  * Inputs:
      * M, a square matrix,
  * Optional inputs,:
      * Strategy, =>
        ..., default value null, choose between Bareiss, Cofactor and Dynamic
        algorithms
  * Outputs:
      * a ring element, which is the determinant of M

Description
===========

+----------------------------------------------------+
|i1 : R = QQ[vars(0..8)]                             |
|                                                    |
|o1 = R                                              |
|                                                    |
|o1 : PolynomialRing                                 |
+----------------------------------------------------+
|i2 : M = genericMatrix(R,2,2)                       |
|                                                    |
|o2 = | a c |                                        |
|     | b d |                                        |
|                                                    |
|             2      2                               |
|o2 : Matrix R  <-- R                                |
+----------------------------------------------------+
|i3 : det M                                          |
|                                                    |
|o3 = - b*c + a*d                                    |
|                                                    |
|o3 : R                                              |
+----------------------------------------------------+
|i4 : N = genericMatrix(R,3,3)                       |
|                                                    |
|o4 = | a d g |                                      |
|     | b e h |                                      |
|     | c f i |                                      |
|                                                    |
|             3      3                               |
|o4 : Matrix R  <-- R                                |
+----------------------------------------------------+
|i5 : det N                                          |
|                                                    |
|o5 = - c*e*g + b*f*g + c*d*h - a*f*h - b*d*i + a*e*i|
|                                                    |
|o5 : R                                              |
+----------------------------------------------------+

See also
========

  * exteriorPower -- exterior power
  * minors -- ideal generated by minors
  * permanents -- ideal generated by square permanents of a
    matrix
  * pfaffians -- ideal generated by Pfaffians

Ways to use determinant:
========================

  * "determinant(Matrix)"
  * "determinant(MutableMatrix)"
  * determinant(CoherentSheaf) (missing documentation)

For the programmer
==================

The object determinant, is a method function with options.

determinant(...,Strategy=>...) -- choose between Bareiss, Cofactor and Dynamic algorithms
*****************************************************************************************

Synopsis
========

  * Usage:
        determinant(M, Strategy => s)
  * Inputs:
      * M, a matrix,
      * s, a symbol, either Bareiss, Cofactor, or Dynamic
  * Consequences:
      * If s is Bareiss, then the Bareiss algorithm is used; if
        s is Cofactor, then cofactor expansion is used; if s
        is Dynamic, then a dynamic programming algorithm is
        used.

Description
===========

The ring, of M determines the default strategy.  If the ring is a
polynomial ring, or a field (as identified by
isField) then the Bareiss, algorithm is used.  If the
ring is a quotient ring, (which has not been declared a
field by toField), then the Cofactor,
algorithm is used.The Dynamic, algorithm implements a variant of
cofactor expansion that caches intermediate results. This strategy introduces
some memory overhead, but can be faster than Cofactor,
especially with sparse matrices of low degree.

Further information
===================

  * Default value: null
  * Function: determinant, -- determinant of a matrix
  * Option key: Strategy, -- an optional argument

Caveat
======

The Bareiss, algorithm returns a ring element that may differ
from the actual determinant by a zero divisor in the ring.  Thus, an incorrect
answer may be computed if the ring contains zero divisors.

See also
========

  * exteriorPower -- exterior power
  * minors -- ideal generated by minors

Functions with optional argument named Strategy:
================================================

  * "addHook(...,Strategy=>...)" -- see addHook, -- add a hook
    function to an object for later processing
  * adjoint(...,Strategy=>...) (missing documentation)
  * "annihilator(...,Strategy=>...)" -- see annihilator (Saturation),
    -- the annihilator ideal
  * "associatedPrimes(...,Strategy=>...)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "basis(...,Strategy=>...)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * canonicalBundle(...,Strategy=>...) (missing documentation)
  * "mingens(...,Strategy=>...)" -- see Complement, -- a
    Strategy option value
  * "trim(...,Strategy=>...)" -- see Complement, -- a
    Strategy option value
  * "compose(Module,Module,Module,Strategy=>...)" -- see compose,
    -- composition as a pairing on Hom-modules
  * cotangentSheaf(...,Strategy=>...) (missing documentation)
  * determinant(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * dual(ChainComplex,Strategy=>...) (missing documentation)
  * dual(Matrix,Strategy=>...) (missing documentation)
  * "dual(MonomialIdeal,List,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...),
  * "dual(MonomialIdeal,RingElement,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...),
  * dual(MonomialIdeal,Strategy=>...)
  * dual(SheafMap,Strategy=>...) (missing documentation)
  * "End(...,Strategy=>...)" -- see End, -- module of endomorphisms
  * exteriorPower(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * "gb(...,Strategy=>...)" -- see gb, -- compute a Gröbner basis
  * gcdLLL(...,Strategy=>...) (missing documentation)
  * "GF(...,Strategy=>...)" -- see GF, -- make a finite field
  * "groebnerBasis(...,Strategy=>...)" -- see groebnerBasis,
    -- Gröbner basis, as a matrix
  * hermite(...,Strategy=>...) (missing documentation)
  * "Hom(...,Strategy=>...)" -- see Hom, -- module of homomorphisms
  * "homomorphism'(...,Strategy=>...)" -- see homomorphism',
    -- get the element of Hom from a homomorphism
  * "hooks(...,Strategy=>...)" -- see hooks, -- list hooks
    attached to a key
  * "idealizer(...,Strategy=>...)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * integralClosure(...,Strategy=>...) (IntegralClosure),
    --
    control the algorithm used
  * "intersect(Ideal,Ideal,Strategy=>...)" -- see intersect(Ideal,Ideal),
    -- compute an intersection of a sequence of
    ideals or modules
  * "intersect(Module,Module,Strategy=>...)" -- see
    intersect(Ideal,Ideal), -- compute an
    intersection of a sequence of ideals or modules
  * "intersectInP(...,Strategy=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "isPrimary(...,Strategy=>...)" -- see isPrimary (PrimaryDecomposition),
    -- determine whether a submodule is
    primary
  * "isPrime(Ideal,Strategy=>...)" -- see isPrime(Ideal) (MinimalPrimes),
    -- whether an ideal is prime
  * LLL(...,Strategy=>...) (LLLBases)
    -- choose among
    different algorithms
  * "localize(...,Strategy=>...)" -- see localize (PrimaryDecomposition),
    -- localize an ideal at a prime ideal
  * "match(...,Strategy=>...)" -- see match, -- regular expression
    matching
  * "decompose(Ideal,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * minors(...,Strategy=>...)
    -- choose between Bareiss,
    Cofactor and Dynamic algorithms
  * "parallelApply(...,Strategy=>...)" -- see parallelApply,
    -- apply a function to each element in parallel
  * "primaryComponent(...,Strategy=>...)" -- see primaryComponent (PrimaryDecomposition),
    -- find a primary component
    corresponding to an associated prime
  * pushForward(...,Strategy=>...) (missing documentation)
  * quotient(...,Strategy=>...) (Saturation)
  * "radical(...,Strategy=>...)" -- see radical (MinimalPrimes),
    -- the radical of an ideal
  * "radicalContainment(...,Strategy=>...)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * "analyticSpread(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "associatedGradedRing(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "distinguished(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isLinearType(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isReduction(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "minimalReduction(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "multiplicity(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(Ideal,RingElement,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(Ideal,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "reesAlgebra(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * reesIdeal(...,Strategy=>...) (ReesAlgebra)
    -- Choose a
    strategy for the saturation step
  * "specialFiber(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "specialFiberIdeal(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "regSeqInIdeal(...,Strategy=>...)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * resolution(...,Strategy=>...)
  * saturate(...,Strategy=>...) (Saturation)
  * sheafHom(...,Strategy=>...) (missing documentation)
  * "primaryDecomposition(...,Strategy=>...)" -- see strategies for computing primary decomposition (PrimaryDecomposition),
  * "syz(...,Strategy=>...)" -- see syz(Matrix), --
    compute the syzygy matrix
  * "tangentCone(...,Strategy=>...)" -- see tangentCone(Ideal) (TangentCone),
  * tangentSheaf(...,Strategy=>...) (missing documentation)

Developer's Corner
******************

engine
******

The engine is the part of the program that is dedicated to performing the
computation of Gröbner bases with Buchberger's algorithm.  It is coded directly
in C++ for speed.

The Macaulay2 engine provides fast polynomial and matrix operations, and
Gröbner bases, syzygies, Hilbert functions, resolutions and other operations
that we feel need to be implemented directly for efficiency reasons.

diagonalMatrix -- make a diagonal matrix
****************************************

See also
========

  * matrices

Ways to use diagonalMatrix:
===========================

  * diagonalMatrix(Matrix) -- make a
    diagonal matrix from entries of a matrix
  * "diagonalMatrix(List)" -- see diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a
    list
  * "diagonalMatrix(Ring,List)" -- see diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a
    list
  * diagonalMatrix(Ring,ZZ,ZZ,List)
    -- make a diagonal matrix from a
    list
  * "diagonalMatrix(RingFamily,List)" -- see
    diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a list
  * "diagonalMatrix(RingFamily,ZZ,ZZ,List)" -- see
    diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a list
  * "diagonalMatrix(ZZ,ZZ,List)" -- see diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a
    list

For the programmer
==================

The object diagonalMatrix, is a method function.

diagonalMatrix(Matrix) -- make a diagonal matrix from entries of a matrix
*************************************************************************

Synopsis
========

  * Function: diagonalMatrix,
  * Usage:
        diagonalMatrix m
  * Inputs:
      * m, a matrix,
  * Outputs:
      * a matrix, a diagonal matrix whose diagonal entries are
        the entries of m

Description
===========

+--------------------------+
|i1 : R = QQ[a..d];        |
+--------------------------+
|i2 : diagonalMatrix vars R|
|                          |
|o2 = | a 0 0 0 |          |
|     | 0 b 0 0 |          |
|     | 0 0 c 0 |          |
|     | 0 0 0 d |          |
|                          |
|             4      4     |
|o2 : Matrix R  <-- R      |
+--------------------------+
If the matrix has more than one row, the first column is placed on the diagonal
first, then the second column, etc.
+---------------------------------------+
|i3 : diagonalMatrix matrix{{0,2},{4,6}}|
|                                       |
|o3 = | 0 0 0 0 |                       |
|     | 0 4 0 0 |                       |
|     | 0 0 2 0 |                       |
|     | 0 0 0 6 |                       |
|                                       |
|              4       4                |
|o3 : Matrix ZZ  <-- ZZ                 |
+---------------------------------------+

See also
========

  * matrices

Ways to use this method:
========================

  * diagonalMatrix(Matrix) -- make a
    diagonal matrix from entries of a matrix

diagonalMatrix(Ring,ZZ,ZZ,List) -- make a diagonal matrix from a list
*********************************************************************

Synopsis
========

  * Function: diagonalMatrix,
  * Usage:
        diagonalMatrix(R,L)
        diagonalMatrix L
        diagonalMatrix(m,n,L)
        diagonalMatrix(R,m,n,L)
  * Inputs:
      * R, a ring, the ring of the matrix, if specified
      * m, an integer, the number of rows, if specified
      * n, an integer, the number of columns, if specified
      * L, a list,  of elements in the ring R not longer than m or
        n
  * Outputs:
      * a matrix, a diagonal matrix whose diagonal entries are
        the elements of L

Description
===========

+----------------------------------+
|i1 : R = QQ[a..d];                |
+----------------------------------+
|i2 : diagonalMatrix{a,b,c,3/4}    |
|                                  |
|o2 = | a 0 0 0   |                |
|     | 0 b 0 0   |                |
|     | 0 0 c 0   |                |
|     | 0 0 0 3/4 |                |
|                                  |
|             4      4             |
|o2 : Matrix R  <-- R              |
+----------------------------------+
|i3 : diagonalMatrix(3,5,{a,b,3/4})|
|                                  |
|o3 = | a 0 0   0 0 |              |
|     | 0 b 0   0 0 |              |
|     | 0 0 3/4 0 0 |              |
|                                  |
|             3      5             |
|o3 : Matrix R  <-- R              |
+----------------------------------+
|i4 : diagonalMatrix(R,{1,2,3})    |
|                                  |
|o4 = | 1 0 0 |                    |
|     | 0 2 0 |                    |
|     | 0 0 3 |                    |
|                                  |
|             3      3             |
|o4 : Matrix R  <-- R              |
+----------------------------------+

See also
========

  * matrices

Ways to use this method:
========================

  * "diagonalMatrix(List)"
  * "diagonalMatrix(Ring,List)"
  * diagonalMatrix(Ring,ZZ,ZZ,List)
    -- make a diagonal matrix from a
    list
  * "diagonalMatrix(RingFamily,List)"
  * "diagonalMatrix(RingFamily,ZZ,ZZ,List)"
  * "diagonalMatrix(ZZ,ZZ,List)"

diameter -- diameter of an interval
***********************************

Synopsis
========

  * Usage:
        x = diameter I
  * Inputs:
      * I, a real interval,
  * Outputs:
      * x, a real number,

Description
===========

Returns the diameter (the difference between the endpoints) of the input
interval.

See also
========

  * left -- left endpoint of an interval
  * right -- right endpoint of an interval
  * midpoint -- midpoint of an interval

Ways to use diameter:
=====================

  * "diameter(RRi)"

For the programmer
==================

The object diameter, is a method function.

Dictionary -- the class of all dictionaries
*******************************************

Description
===========

A dictionary is a special sort of hash table whose keys are the strings, and
whose values are the corresponding symbols.
+-----------------------------+
|i1 : Core.Dictionary # "sin" |
|                             |
|o1 = sin                     |
|                             |
|o1 : Symbol                  |
+-----------------------------+
|i2 : Core.Dictionary #? "sin"|
|                             |
|o2 = true                    |
+-----------------------------+

Types of dictionary:
====================

  * GlobalDictionary -- the class of all global
    dictionaries
  * LocalDictionary -- the class of all local
    dictionaries

Methods that use a dictionary:
==============================

  * # Dictionary (missing documentation)
  * Dictionary # String (missing documentation)
  * Dictionary #? String (missing documentation)
  * "keys(Dictionary)" -- see keys, -- keys used in a hash table,
    dictionary, or database
  * length(Dictionary) -- length of a dictionary
  * "listSymbols(Dictionary)" -- see listSymbols, -- compact
    display of symbols and their values
  * "localDictionaries(Dictionary)" -- see localDictionaries,
    -- get local dictionaries
  * "package(Dictionary)" -- see package, -- get containing
    package
  * "pairs(Dictionary)" -- see pairs, -- list the pairs in a hash
    table, dictionary, or basic list
  * "values(Dictionary)" -- see values, -- values in a hash table

For the programmer
==================

The object Dictionary, is a type, with ancestor
class Thing.

dictionary -- determine the dictionary to which a symbol belongs
****************************************************************

Synopsis
========

  * Usage:
        dictionary x
  * Inputs:
      * x, a thing,
  * Outputs:
      * the dictionary to which the symbol x belongs

Description
===========

If x is the value of a symbol recorded in the internal table used to recover
global symbol from the values assigned to them, then that symbol is used.

Ways to use dictionary:
=======================

  * "dictionary(Keyword)"
  * "dictionary(Symbol)"
  * "dictionary(Thing)"

For the programmer
==================

The object dictionary, is a method function.

dictionaryPath
**************

Description
===========

The value of dictionaryPath, is the list of global
dictionaries whose symbols are visible.
+-----------------------------------------------------------------------------+
|i1 : dictionaryPath                                                          |
|                                                                             |
|o1 = {GlobalDictionary{}, PackageCitations.Dictionary, Varieties.Dictionary, |
|     ------------------------------------------------------------------------|
|     Truncations.Dictionary, Polyhedra.Dictionary, Saturation.Dictionary,    |
|     ------------------------------------------------------------------------|
|     Elimination.Dictionary, Isomorphism.Dictionary, OnlineLookup.Dictionary,|
|     ------------------------------------------------------------------------|
|     SimpleDoc.Dictionary, InverseSystems.Dictionary,                        |
|     ------------------------------------------------------------------------|
|     ConwayPolynomials.Dictionary, ReesAlgebra.Dictionary,                   |
|     ------------------------------------------------------------------------|
|     TangentCone.Dictionary, Classic.Dictionary, MinimalPrimes.Dictionary,   |
|     ------------------------------------------------------------------------|
|     PrimaryDecomposition.Dictionary, IntegralClosure.Dictionary,            |
|     ------------------------------------------------------------------------|
|     LLLBases.Dictionary, Macaulay2Doc.Dictionary, Core.Dictionary,          |
|     ------------------------------------------------------------------------|
|     GlobalDictionary{...1...}, PackageDictionary}                           |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * Dictionary -- the class of all dictionaries

For the programmer
==================

The object dictionaryPath, is a list.

diff -- differentiate or take difference
****************************************

Synopsis
========

  * Usage:
        diff(f,g) or diff(P) or diff(P,i)

Description
===========

This function has two different uses.  The most common use is for
differentiation: differentiate the second input by the first.

The second use, less common but sometimes useful, is to compute the difference
polynomial of a Hilbert polynomial.

The arguments can also be ring elements or vectors.
+-----------------------------------+
|i1 : R = ZZ[x,y,z]                 |
|                                   |
|o1 = R                             |
|                                   |
|o1 : PolynomialRing                |
+-----------------------------------+
|i2 : f = vars R ** vars R          |
|                                   |
|o2 = | x2 xy xz xy y2 yz xz yz z2 ||
|                                   |
|             1      9              |
|o2 : Matrix R  <-- R               |
+-----------------------------------+
|i3 : diff(transpose vars R, f)     |
|                                   |
|o3 = {1} | 2x y z y 0  0 z 0 0  |  |
|     {1} | 0  x 0 x 2y z 0 z 0  |  |
|     {1} | 0  0 x 0 0  y x y 2z |  |
|                                   |
|             3      9              |
|o3 : Matrix R  <-- R               |
+-----------------------------------+
|i4 : diff(x, f)                    |
|                                   |
|o4 = | 2x y z y 0 0 z 0 0 |        |
|                                   |
|             1      9              |
|o4 : Matrix R  <-- R               |
+-----------------------------------+
|i5 : diff(y, f)                    |
|                                   |
|o5 = | 0 x 0 x 2y z 0 z 0 |        |
|                                   |
|             1      9              |
|o5 : Matrix R  <-- R               |
+-----------------------------------+
|i6 : diff(z, f)                    |
|                                   |
|o6 = | 0 0 x 0 0 y x y 2z |        |
|                                   |
|             1      9              |
|o6 : Matrix R  <-- R               |
+-----------------------------------+

See also
========

  * diff and contract
  * diff' -- differentiate a matrix by a
    matrix, the dual notion
  * contract -- contract one matrix by another
  * jacobian -- the Jacobian matrix of partial derivatives
  * hilbertPolynomial -- compute the Hilbert
    polynomial

Ways to use diff:
=================

  * diff(Matrix,Matrix) -- differentiate a
    matrix by a matrix
  * "diff(Matrix,Vector)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * "diff(RingElement,Vector)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * "diff(Vector,Matrix)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * "diff(Vector,RingElement)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * "diff(Vector,Vector)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * diff(Matrix,RingElement), --
    differentiation
  * diff(ProjectiveHilbertPolynomial)
  * diff(ProjectiveHilbertPolynomial,ZZ)
  * diff(RingElement,Matrix), --
    differentiate each entry of a matrix
  * diff(RingElement,RingElement),
    -- differentiation

For the programmer
==================

The object diff, is a method function.

differentiation

difference operator for Hilbert polynomials

diff(RingElement,RingElement) -- differentiation
************************************************

Synopsis
========

  * Function: diff,
  * Usage:
        diff(x,f)
  * Inputs:
      * x, a polynomial
      * f, a polynomial in the same ring as x
  * Outputs:
      * the result of differentiating f by the differential operator
        corresponding to x.

Description
===========

If x is an indeterminate this is simply the usual differentiation.
+-----------------------------------------+
|i1 : R = QQ[x,y,z];                      |
+-----------------------------------------+
|i2 : diff(x,x^7 + 4*x^3*y - 3*y)         |
|                                         |
|       6      2                          |
|o2 = 7x  + 12x y                         |
|                                         |
|o2 : R                                   |
+-----------------------------------------+
|i3 : diff(x^2+y^2+z^2, y^2*z^2 - x^3 - 1)|
|                                         |
|       2     2                           |
|o3 = 2y  + 2z  - 6x                      |
|                                         |
|o3 : R                                   |
+-----------------------------------------+
Here is a shortcut that can save some typing.
+---------------+
|i4 : diff_x x^6|
|               |
|       5       |
|o4 = 6x        |
|               |
|o4 : R         |
+---------------+

See also
========

  * contract -- contract one matrix by another
  * jacobian -- the Jacobian matrix of partial derivatives
  * diff and contract

Ways to use this method:
========================

  * diff(RingElement,RingElement),
    -- differentiation

diff(RingElement,Matrix) -- differentiate each entry of a matrix
****************************************************************

Synopsis
========

  * Function: diff,
  * Usage:
        diff(x,f)
  * Inputs:
      * x, a polynomial
      * f, a matrix between free modules over the same ring as x
  * Outputs:
      * a matrix, having the same shape as f, whose (i,j) entry
        is the result of differentiating f_(i,j) by the differential operator
        corresponding to x.

Description
===========

The shape of the resulting matrix is the same as the shape of f, but the
degrees of the source module are different in an attempt to ensure that the
result is homogeneous.
+-----------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                        |
+-----------------------------------------------------------+
|i2 : f = matrix{{x^2-y*z, x*y*z + z^4}, {x-1, 2*y^2+z^2-1}}|
|                                                           |
|o2 = | x2-yz z4+xyz   |                                    |
|     | x-1   2y2+z2-1 |                                    |
|                                                           |
|             2      2                                      |
|o2 : Matrix R  <-- R                                       |
+-----------------------------------------------------------+
|i3 : diff(x,f)                                             |
|                                                           |
|o3 = | 2x yz |                                             |
|     | 1  0  |                                             |
|                                                           |
|             2      2                                      |
|o3 : Matrix R  <-- R                                       |
+-----------------------------------------------------------+
|i4 : diff(x^2-y*z,f)                                       |
|                                                           |
|o4 = | 3 -x |                                              |
|     | 0 0  |                                              |
|                                                           |
|             2      2                                      |
|o4 : Matrix R  <-- R                                       |
+-----------------------------------------------------------+

See also
========

  * contract -- contract one matrix by another
  * jacobian -- the Jacobian matrix of partial derivatives
  * diff and contract

Ways to use this method:
========================

  * diff(RingElement,Matrix), --
    differentiate each entry of a matrix

diff(Matrix,RingElement) -- differentiation
*******************************************

Synopsis
========

  * Function: diff,
  * Usage:
        diff(f,g)
  * Inputs:
      * f, a matrix
      * g, a polynomial with the same ring as f
  * Outputs:
      * the result of differentiating g by the differential operator
        corresponding to each entry of f.

Description
===========

The shape of the resulting matrix is the same as the shape of f, but the
degrees of the source module are different in an attempt to ensure that the
result is homogeneous.
+--------------------------------------+
|i1 : R = QQ[x,y,z,q];                 |
+--------------------------------------+
|i2 : f = vars R                       |
|                                      |
|o2 = | x y z q |                      |
|                                      |
|             1      4                 |
|o2 : Matrix R  <-- R                  |
+--------------------------------------+
|i3 : diff(f, (x+y-z)^2)               |
|                                      |
|o3 = | 2x+2y-2z 2x+2y-2z -2x-2y+2z 0 ||
|                                      |
|             1      4                 |
|o3 : Matrix R  <-- R                  |
+--------------------------------------+
|i4 : f2 = genericMatrix(R,2,2)        |
|                                      |
|o4 = | x z |                          |
|     | y q |                          |
|                                      |
|             2      2                 |
|o4 : Matrix R  <-- R                  |
+--------------------------------------+
|i5 : diff(f2, (x+y-z)^2)              |
|                                      |
|o5 = | 2x+2y-2z -2x-2y+2z |           |
|     | 2x+2y-2z 0         |           |
|                                      |
|             2      2                 |
|o5 : Matrix R  <-- R                  |
+--------------------------------------+

See also
========

  * contract -- contract one matrix by another
  * jacobian -- the Jacobian matrix of partial derivatives
  * diff and contract

Ways to use this method:
========================

  * diff(Matrix,RingElement), --
    differentiation

diff(Matrix,Matrix) -- differentiate a matrix by a matrix
*********************************************************

Synopsis
========

  * Function: diff,
  * Usage:
        diff(m,n)
  * Inputs:
      * m, a map m : F <--- P between free modules of ranks f and p.
      * n, a map n : G <--- Q between free modules of ranks g and q.
  * Outputs:
      * a matrix, with the shape h : dual F ** G <--- dual P **

        Q, whose entry in the slot h            is the result of
                                    g*i+j,q*k+l
        differentiating n    by the differential operator corresponding to
                         j,l
        m   .
         i,k

Description
===========

The arguments m and n may also be vectors or ring elements.
+-----------------------------------------------------+
|i1 : R = QQ[a,b,c][x,y,z]                            |
|                                                     |
|o1 = R                                               |
|                                                     |
|o1 : PolynomialRing                                  |
+-----------------------------------------------------+
|i2 : m = transpose vars R                            |
|                                                     |
|o2 = {-1, 0} | x |                                   |
|     {-1, 0} | y |                                   |
|     {-1, 0} | z |                                   |
|                                                     |
|             3      1                                |
|o2 : Matrix R  <-- R                                 |
+-----------------------------------------------------+
|i3 : n = matrix{{x^2-a*y^3, x^3-z^2*y, x*y-b, x*z-c}}|
|                                                     |
|o3 = | -ay3+x2 x3-yz2 xy-b xz-c |                    |
|                                                     |
|             1      4                                |
|o3 : Matrix R  <-- R                                 |
+-----------------------------------------------------+
|i4 : diff(m,n)                                       |
|                                                     |
|o4 = {1, 0} | 2x    3x2  y z |                       |
|     {1, 0} | -3ay2 -z2  x 0 |                       |
|     {1, 0} | 0     -2yz 0 x |                       |
|                                                     |
|             3      4                                |
|o4 : Matrix R  <-- R                                 |
+-----------------------------------------------------+

See also
========

  * diff' -- differentiate a matrix by a
    matrix, the dual notion
  * contract -- contract one matrix by another
  * diff and contract

Ways to use this method:
========================

  * diff(Matrix,Matrix) -- differentiate a
    matrix by a matrix
  * "diff(Matrix,Vector)"
  * "diff(RingElement,Vector)"
  * "diff(Vector,Matrix)"
  * "diff(Vector,RingElement)"
  * "diff(Vector,Vector)"

diff(ProjectiveHilbertPolynomial)
*********************************

Synopsis
========

  * Function: diff,

Description
===========

diff P -- compute the difference polynomial.

Ways to use this method:
========================

  * diff(ProjectiveHilbertPolynomial)

diff(ProjectiveHilbertPolynomial,ZZ)
************************************

Synopsis
========

  * Function: diff,

Description
===========

diff(P,i) -- compute the i-th difference polynomial

Ways to use this method:
========================

  * diff(ProjectiveHilbertPolynomial,ZZ)

diff and contract
*****************

We may use the function diff, to differentiate polynomials: the
first argument is the variable to differentiate with respect to, and the second
argument is the polynomial to be differentiated.
+-------------------------+
|i1 : R = QQ[a,b,t,x,y,z];|
+-------------------------+
|i2 : f = x^7 * y^11;     |
+-------------------------+
|i3 : diff(x,f)           |
|                         |
|       6 11              |
|o3 = 7x y                |
|                         |
|o3 : R                   |
+-------------------------+
|i4 : diff(y,f)           |
|                         |
|        7 10             |
|o4 = 11x y               |
|                         |
|o4 : R                   |
+-------------------------+
We indicate higher derivatives by simply multiplying the variables to
differentiate by.
+----------------+
|i5 : diff(x^2,f)|
|                |
|        5 11    |
|o5 = 42x y      |
|                |
|o5 : R          |
+----------------+
|i6 : diff(x*y,f)|
|                |
|        6 10    |
|o6 = 77x y      |
|                |
|o6 : R          |
+----------------+
|i7 : diff(y^2,f)|
|                |
|         7 9    |
|o7 = 110x y     |
|                |
|o7 : R          |
+----------------+
The first argument can also be a sum, in which case the sum of the answers
provided by each of its terms is returned.
+--------------------------------+
|i8 : diff(x+y,f)                |
|                                |
|        7 10     6 11           |
|o8 = 11x y   + 7x y             |
|                                |
|o8 : R                          |
+--------------------------------+
|i9 : diff(x^2+x*y+y^2,f)        |
|                                |
|         7 9      6 10      5 11|
|o9 = 110x y  + 77x y   + 42x y  |
|                                |
|o9 : R                          |
+--------------------------------+
Remark: the operation diff is useful, but it's not a natural one: it's not
invariant under linear coordinate changes; in effect, we've identified the a
free module with its dual.

The second argument can be a matrix, in which case each of its entries gets
differentiated.
+---------------------------------------+
|i10 : m = matrix {{x^3, x^4},{x^5,x^6}}|
|                                       |
|o10 = | x3 x4 |                        |
|      | x5 x6 |                        |
|                                       |
|              2      2                 |
|o10 : Matrix R  <-- R                  |
+---------------------------------------+
|i11 : diff(x,m)                        |
|                                       |
|o11 = | 3x2 4x3 |                      |
|      | 5x4 6x5 |                      |
|                                       |
|              2      2                 |
|o11 : Matrix R  <-- R                  |
+---------------------------------------+
|i12 : diff(x^2,m)                      |
|                                       |
|o12 = | 6x   12x2 |                    |
|      | 20x3 30x4 |                    |
|                                       |
|              2      2                 |
|o12 : Matrix R  <-- R                  |
+---------------------------------------+
The first argument can also be a matrix, in which case the matrices obtained
from each of its entries, acting upon the second argument, are concatenated.
Thus the shape of the first matrix plays the major role.
+-------------------------------------------------+
|i13 : diff(matrix {{x,x^2,x^3,x^4}}, m)          |
|                                                 |
|o13 = | 3x2 4x3 6x   12x2 6    24x   0    24    ||
|      | 5x4 6x5 20x3 30x4 60x2 120x3 120x 360x2 ||
|                                                 |
|              2      8                           |
|o13 : Matrix R  <-- R                            |
+-------------------------------------------------+
|i14 : diff(matrix {{x,x^2},{x^3,x^4}}, m)        |
|                                                 |
|o14 = | 3x2  4x3   6x   12x2  |                  |
|      | 5x4  6x5   20x3 30x4  |                  |
|      | 6    24x   0    24    |                  |
|      | 60x2 120x3 120x 360x2 |                  |
|                                                 |
|              4      4                           |
|o14 : Matrix R  <-- R                            |
+-------------------------------------------------+

Perhaps the most common usage of diff, is when one argument has a
single column and the other column has a single row.  For example, the Jacobian
matrix can be computed as follows.
+------------------------------------------------------+
|i15 : diff(matrix {{x},{y}}, matrix {{x^2, x*y, y^2}})|
|                                                      |
|o15 = | 2x y 0  |                                     |
|      | 0  x 2y |                                     |
|                                                      |
|              2      3                                |
|o15 : Matrix R  <-- R                                 |
+------------------------------------------------------+
-------------------------------------------------------------------------------
We can also compute the Hessian matrix of a quadratic form using diff,
as follows.
+----------------------------------------------------+
|i16 : v = matrix {{x,y}}                            |
|                                                    |
|o16 = | x y |                                       |
|                                                    |
|              1      2                              |
|o16 : Matrix R  <-- R                               |
+----------------------------------------------------+
|i17 : diff(v ** transpose v, 3*x^2 + 5*x*y + 11*y^2)|
|                                                    |
|o17 = {1} | 6 5  |                                  |
|      {1} | 5 22 |                                  |
|                                                    |
|              2      2                              |
|o17 : Matrix R  <-- R                               |
+----------------------------------------------------+
-------------------------------------------------------------------------------
As another example, we show how to compute the Wronskian of a polynomial f.
+---------------------------------------------------+
|i18 : f = x^3 + y^3 + z^3 - t*x*y*z                |
|                                                   |
|                   3    3    3                     |
|o18 = - t*x*y*z + x  + y  + z                      |
|                                                   |
|o18 : R                                            |
+---------------------------------------------------+
|i19 : v = matrix {{x,y,z}}                         |
|                                                   |
|o19 = | x y z |                                    |
|                                                   |
|              1      3                             |
|o19 : Matrix R  <-- R                              |
+---------------------------------------------------+
|i20 : det diff(transpose v * v, f)                 |
|                                                   |
|          3          2 3     2 3     2 3           |
|o20 = - 2t x*y*z - 6t x  - 6t y  - 6t z  + 216x*y*z|
|                                                   |
|o20 : R                                            |
+---------------------------------------------------+
-------------------------------------------------------------------------------
The function contract, is the same as diff, except
the multiplication by integers that occurs during differentiation is omitted.
+---------------------------------------------+
|i21 : contract(x,m)                          |
|                                             |
|o21 = | x2 x3 |                              |
|      | x4 x5 |                              |
|                                             |
|              2      2                       |
|o21 : Matrix R  <-- R                        |
+---------------------------------------------+
|i22 : contract(x^2,m)                        |
|                                             |
|o22 = | x  x2 |                              |
|      | x3 x4 |                              |
|                                             |
|              2      2                       |
|o22 : Matrix R  <-- R                        |
+---------------------------------------------+
|i23 : contract(matrix {{x,x^2,x^3,x^4}}, m)  |
|                                             |
|o23 = | x2 x3 x  x2 1  x  0 1  |             |
|      | x4 x5 x3 x4 x2 x3 x x2 |             |
|                                             |
|              2      8                       |
|o23 : Matrix R  <-- R                        |
+---------------------------------------------+
|i24 : contract(matrix {{x,x^2},{x^3,x^4}}, m)|
|                                             |
|o24 = | x2 x3 x  x2 |                        |
|      | x4 x5 x3 x4 |                        |
|      | 1  x  0  1  |                        |
|      | x2 x3 x  x2 |                        |
|                                             |
|              4      4                       |
|o24 : Matrix R  <-- R                        |
+---------------------------------------------+
One use is for picking out coefficients of homogeneous polynomials.
+----------------------------------------------+
|i25 : f                                       |
|                                              |
|                   3    3    3                |
|o25 = - t*x*y*z + x  + y  + z                 |
|                                              |
|o25 : R                                       |
+----------------------------------------------+
|i26 : v3 = symmetricPower(3,matrix{{x,y,z}})  |
|                                              |
|o26 = | x3 x2y x2z xy2 xyz xz2 y3 y2z yz2 z3 ||
|                                              |
|              1      10                       |
|o26 : Matrix R  <-- R                         |
+----------------------------------------------+
|i27 : contract(v3, f)                         |
|                                              |
|o27 = | 1 0 0 0 -t 0 1 0 0 1 |                |
|                                              |
|              1      10                       |
|o27 : Matrix R  <-- R                         |
+----------------------------------------------+
-------------------------------------------------------------------------------
As an example, the Sylvester resultant between homogeneous polynomials f(x,y)
and g(x,y) can be found in the following way.
+-------------------------------------+
|i28 : f = a * x^3 + b * x^2 * y + y^3|
|                                     |
|         3      2     3              |
|o28 = a*x  + b*x y + y               |
|                                     |
|o28 : R                              |
+-------------------------------------+
|i29 : g = b * x^3 + a * x * y^2 + y^3|
|                                     |
|         3        2    3             |
|o29 = b*x  + a*x*y  + y              |
|                                     |
|o29 : R                              |
+-------------------------------------+
Multiply each of these by all quadrics, obtaining a set of elements in degree
5.
+-----------------------------------------------------------------------------+
|i30 : n = matrix {{f,g}} ** symmetricPower(2,matrix {{x,y}})                 |
|                                                                             |
|o30 = | ax5+bx4y+x2y3 ax4y+bx3y2+xy4 ax3y2+bx2y3+y5 bx5+ax3y2+x2y3           |
|      -----------------------------------------------------------------------|
|      bx4y+ax2y3+xy4 bx3y2+axy4+y5 |                                         |
|                                                                             |
|              1      6                                                       |
|o30 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
Now create the matrix of coefficients by using contract against all monomials
of degree 5 in x and y, and compute its determinant.
+--------------------------------------------------------------------+
|i31 : M = contract(transpose symmetricPower(5,matrix {{x,y}}), n)   |
|                                                                    |
|o31 = {5} | a 0 0 b 0 0 |                                           |
|      {5} | b a 0 0 b 0 |                                           |
|      {5} | 0 b a a 0 b |                                           |
|      {5} | 1 0 b 1 a 0 |                                           |
|      {5} | 0 1 0 0 1 a |                                           |
|      {5} | 0 0 1 0 0 1 |                                           |
|                                                                    |
|              6      6                                              |
|o31 : Matrix R  <-- R                                               |
+--------------------------------------------------------------------+
|i32 : det M                                                         |
|                                                                    |
|         5    2 3    3     2 2       3    4    3     2        2    3|
|o32 = - a  - a b  - a b - a b  + 2a*b  - b  + a  - 3a b + 3a*b  - b |
|                                                                    |
|o32 : R                                                             |
+--------------------------------------------------------------------+
-------------------------------------------------------------------------------
The function diff', is the same as
diff, except that the first argument is differentiated by the second;
the shape of the first argument still plays the major role.
+-------------------------------------------------+
|i33 : diff'(m, matrix {{x,x^2,x^3,x^4}})         |
|                                                 |
|o33 = | 3x2 6x   6    0    4x3 12x2 24x   24    ||
|      | 5x4 20x3 60x2 120x 6x5 30x4 120x3 360x2 ||
|                                                 |
|              2      8                           |
|o33 : Matrix R  <-- R                            |
+-------------------------------------------------+
|i34 : diff'(m, matrix {{x,x^2},{x^3,x^4}})       |
|                                                 |
|o34 = | 3x2  6x   4x3   12x2  |                  |
|      | 6    0    24x   24    |                  |
|      | 5x4  20x3 6x5   30x4  |                  |
|      | 60x2 120x 120x3 360x2 |                  |
|                                                 |
|              4      4                           |
|o34 : Matrix R  <-- R                            |
+-------------------------------------------------+
The function contract', is the same as
contract, except that the first argument is contracted by the
second; the shape of the first argument still plays the major role.
+----------------------------------------------+
|i35 : contract'(m, matrix {{x,x^2,x^3,x^4}})  |
|                                              |
|o35 = | x2 x  1  0 x3 x2 x  1  |              |
|      | x4 x3 x2 x x5 x4 x3 x2 |              |
|                                              |
|              2      8                        |
|o35 : Matrix R  <-- R                         |
+----------------------------------------------+
|i36 : contract'(m, matrix {{x,x^2},{x^3,x^4}})|
|                                              |
|o36 = | x2 x  x3 x2 |                         |
|      | 1  0  x  1  |                         |
|      | x4 x3 x5 x4 |                         |
|      | x2 x  x3 x2 |                         |
|                                              |
|              4      4                        |
|o36 : Matrix R  <-- R                         |
+----------------------------------------------+
-------------------------------------------------------------------------------
All four of these operators are engineered so that the result is a homogeneous
matrix if the arguments are.  The operations diff, and
contract, are essentially partially defined division operations, so
it should come as no surprise that the source and target of diff(m,n) are the
same as those we would get from the tensor product transpose m^-1 ** n, if only
m were invertible.

See also
========

  * diff(Matrix,Matrix) -- differentiate a
    matrix by a matrix
  * contract(Matrix,Matrix) -- contract a
    matrix by a matrix
  * reshape -- reshape a matrix
  * adjoint -- the tensor-Hom adjunction maps

diff'(Matrix,Matrix) -- differentiate a matrix by a matrix, the dual notion
***************************************************************************

Synopsis
========

  * Function: diff',
  * Usage:
        h = diff'(m,n)
  * Inputs:
      * m, a map m : F <--- P between free modules of ranks f and p.
      * n, a map n : G <--- Q between free modules of ranks g and q.
  * Outputs:
      * h, a matrix with the shape h : F ** dual G <--- P ** dual Q, whose

        entry in the slot h            is the result of differentiating n   ,
                           g*i+j,q*k+l                                   j,l
        by m
            i,k

See also
========

  * diff -- differentiate or take difference
  * diff and contract

Ways to use this method:
========================

  * diff'(Matrix,Matrix) -- differentiate a
    matrix by a matrix, the dual notion

difference -- difference
************************

Synopsis
========

  * Usage:
        difference(x,y)

Description
===========

difference(x,y) returns x-y.

For the programmer
==================

The object difference, is a compiled function.

Digamma -- Digamma function
***************************

Synopsis
========

  * Usage:
        Digamma x
  * Inputs:
      * x
  * Outputs:
      * a real number, the digamma function (logarithmic derivative
        of the gamma function) of x

Description
===========

+-------------------------+
|i1 : Digamma 6           |
|                         |
|o1 = 1.7061176684318     |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See Digamma function (see https://en.wikipedia.org/wiki/Digamma_function ).

See also
========

  * Gamma -- Gamma function

Ways to use Digamma:
====================

  * "Digamma(CC)"
  * "Digamma(RR)"
  * "Digamma(RRi)"

For the programmer
==================

The object Digamma, is a method function.

dim -- compute the Krull dimension
**********************************

Caveat
======

To compute the dimension of a vector space, one should use rank.

Over the integers, the computation effectively tensors first with the rational
numbers, yielding the wrong answer in some cases.

See also
========

  * codim -- compute the codimension

Ways to use dim:
================

  * dim(AffineVariety) (Varieties) -- dimension
    of the affine variety
  * dim(Ideal) -- compute the Krull dimension
  * "dim(MonomialIdeal)" -- see dim(Ideal), -- compute
    the Krull dimension
  * dim(Module) -- compute the Krull dimension
  * dim(PolyhedralObject) (Polyhedra), --
    computes the dimension of a cone, polyhedron, fan or polyhedral complex
  * dim(ProjectiveHilbertPolynomial)
    -- the degree of the Hilbert
    polynomial
  * dim(ProjectiveVariety) (Varieties), --
    dimension of the projective variety
  * "dim(FractionField)" -- see dim(Ring), -- compute the
    Krull dimension
  * "dim(GaloisField)" -- see dim(Ring), -- compute the
    Krull dimension
  * "dim(InexactField)" -- see dim(Ring), -- compute the
    Krull dimension
  * "dim(PolynomialRing)" -- see dim(Ring), -- compute the
    Krull dimension
  * "dim(QuotientRing)" -- see dim(Ring), -- compute the
    Krull dimension
  * dim(Ring) -- compute the Krull dimension

For the programmer
==================

The object dim, is a method function.

dim(Ideal) -- compute the Krull dimension
*****************************************

Synopsis
========

  * Function: dim,
  * Usage:
        dim I
  * Inputs:
      * I
  * Outputs:
      * an integer,

Description
===========

Computes the Krull dimension of the base ring of I mod I.

The ideal of 3x3 commuting matrices:
+--------------------------------------------------+
|i1 : R = ZZ/101[x_(0,0)..x_(2,2),y_(0,0)..y_(2,2)]|
|                                                  |
|o1 = R                                            |
|                                                  |
|o1 : PolynomialRing                               |
+--------------------------------------------------+
|i2 : M = genericMatrix(R,x_(0,0),3,3)             |
|                                                  |
|o2 = | x_(0,0) x_(1,0) x_(2,0) |                  |
|     | x_(0,1) x_(1,1) x_(2,1) |                  |
|     | x_(0,2) x_(1,2) x_(2,2) |                  |
|                                                  |
|             3      3                             |
|o2 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i3 : N = genericMatrix(R,y_(0,0),3,3)             |
|                                                  |
|o3 = | y_(0,0) y_(1,0) y_(2,0) |                  |
|     | y_(0,1) y_(1,1) y_(2,1) |                  |
|     | y_(0,2) y_(1,2) y_(2,2) |                  |
|                                                  |
|             3      3                             |
|o3 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i4 : I = ideal flatten(M*N-N*M);                  |
|                                                  |
|o4 : Ideal of R                                   |
+--------------------------------------------------+
|i5 : dim I                                        |
|                                                  |
|o5 = 12                                           |
+--------------------------------------------------+
The dimension of a Stanley-Reisner monomial ideal associated to a simplicial
complex.

A hollow tetrahedron:
+----------------------------------------------------+
|i6 : needsPackage "SimplicialComplexes"             |
|                                                    |
|o6 = SimplicialComplexes                            |
|                                                    |
|o6 : Package                                        |
+----------------------------------------------------+
|i7 : R = QQ[a..d]                                   |
|                                                    |
|o7 = R                                              |
|                                                    |
|o7 : PolynomialRing                                 |
+----------------------------------------------------+
|i8 : D = simplicialComplex {a*b*c,a*b*d,a*c*d,b*c*d}|
|                                                    |
|o8 = simplicialComplex | bcd acd abd abc |          |
|                                                    |
|o8 : SimplicialComplex                              |
+----------------------------------------------------+
|i9 : I = monomialIdeal D                            |
|                                                    |
|o9 = monomialIdeal(a*b*c*d)                         |
|                                                    |
|o9 : MonomialIdeal of R                             |
+----------------------------------------------------+
|i10 : facets D                                      |
|                                                    |
|o10 = {b*c*d, a*c*d, a*b*d, a*b*c}                  |
|                                                    |
|o10 : List                                          |
+----------------------------------------------------+
|i11 : dim D                                         |
|                                                    |
|o11 = 2                                             |
+----------------------------------------------------+
|i12 : dim I                                         |
|                                                    |
|o12 = 3                                             |
+----------------------------------------------------+
Note that the dimension of the zero ideal is -1.

See also
========

  * ideal -- make an ideal
  * monomialIdeal -- make a monomial ideal
  * SimplicialComplexes -- exploring abstract
    simplicial complexes within commutative algebra

Ways to use this method:
========================

  * dim(Ideal) -- compute the Krull dimension
  * "dim(MonomialIdeal)"

dim(Module) -- compute the Krull dimension
******************************************

Synopsis
========

  * Function: dim,
  * Usage:
        dim M
  * Inputs:
      * M
  * Outputs:
      * an integer,

Description
===========

Computes the Krull dimension of the module M
+------------------------------------------+
|i1 : R = ZZ/31991[a,b,c,d]                |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : I = monomialCurveIdeal(R,{1,2,3})    |
|                                          |
|             2                    2       |
|o2 = ideal (c  - b*d, b*c - a*d, b  - a*c)|
|                                          |
|o2 : Ideal of R                           |
+------------------------------------------+
|i3 : M = Ext^1(I,R)                       |
|                                          |
|o3 = cokernel {-3} | a -b c |             |
|              {-3} | b -c d |             |
|                                          |
|                            2             |
|o3 : R-module, quotient of R              |
+------------------------------------------+
|i4 : dim M                                |
|                                          |
|o4 = 2                                    |
+------------------------------------------+
|i5 : N = Ext^0(I,R)                       |
|                                          |
|o5 = image {-2} | c2-bd |                 |
|           {-2} | bc-ad |                 |
|           {-2} | b2-ac |                 |
|                                          |
|                             3            |
|o5 : R-module, submodule of R             |
+------------------------------------------+
|i6 : dim N                                |
|                                          |
|o6 = 4                                    |
+------------------------------------------+
Note that the dimension of the zero module is -1.

See also
========

  * dim(Ring) -- compute the Krull dimension
  * dim(Ideal) -- compute the Krull dimension

Ways to use this method:
========================

  * dim(Module) -- compute the Krull dimension

dim(ProjectiveHilbertPolynomial) -- the degree of the Hilbert polynomial
************************************************************************

Synopsis
========

  * Function: dim,
  * Usage:
        dim P
  * Inputs:
      * P
  * Outputs:
      * an integer,

Description
===========

The command dim,is designed so that the result is the dimension of
the projective scheme that may have been used to produce the given Hilbert
polynomial.
+-----------------------------------------+
|i1 : V = Proj(QQ[x_0..x_5]/(x_0^3+x_5^3))|
|                                         |
|o1 = V                                   |
|                                         |
|o1 : ProjectiveVariety                   |
+-----------------------------------------+
|i2 : P = hilbertPolynomial V             |
|                                         |
|o2 = P  - 3*P  + 3*P                     |
|      2      3      4                    |
|                                         |
|o2 : ProjectiveHilbertPolynomial         |
+-----------------------------------------+
|i3 : dim P                               |
|                                         |
|o3 = 4                                   |
+-----------------------------------------+

See also
========

  * hilbertPolynomial -- compute the Hilbert
    polynomial
  * degree(ProjectiveHilbertPolynomial)
  * euler(ProjectiveHilbertPolynomial) (missing documentation)

Ways to use this method:
========================

  * dim(ProjectiveHilbertPolynomial)
    -- the degree of the Hilbert
    polynomial

dim(Ring) -- compute the Krull dimension
****************************************

Synopsis
========

  * Function: dim,
  * Usage:
        dim R
  * Inputs:
      * R
  * Outputs:
      * an integer,

Description
===========

Computes the Krull dimension of the given ring.

The singular locus of a cuspidal plane curve
+------------------------------+
|i1 : R = QQ[x,y,z]            |
|                              |
|o1 = R                        |
|                              |
|o1 : PolynomialRing           |
+------------------------------+
|i2 : I =ideal(y^2*z-x^3)      |
|                              |
|              3    2          |
|o2 = ideal(- x  + y z)        |
|                              |
|o2 : Ideal of R               |
+------------------------------+
|i3 : sing = singularLocus(R/I)|
|                              |
|o3 = sing                     |
|                              |
|o3 : QuotientRing             |
+------------------------------+
|i4 : dim sing                 |
|                              |
|o4 = 1                        |
+------------------------------+
The exterior algebra is artinian:
+---------------------------------------------------+
|i5 : R = ZZ/101[a,b,SkewCommutative => true]       |
|                                                   |
|o5 = R                                             |
|                                                   |
|o5 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i6 : dim R                                         |
|                                                   |
|o6 = 0                                             |
+---------------------------------------------------+
The Weyl algebra in 2 variables:
+---------------------------------------------------------+
|i7 : R = ZZ/101[x,dx,y,dy,WeylAlgebra => {x=>dx, y=>dy}];|
+---------------------------------------------------------+
|i8 : dim R                                               |
|                                                         |
|o8 = 4                                                   |
+---------------------------------------------------------+

See also
========

  * codim -- compute the codimension
  * dim(AffineVariety) (Varieties) -- dimension
    of the affine variety

Ways to use this method:
========================

  * "dim(FractionField)"
  * "dim(GaloisField)"
  * "dim(InexactField)"
  * "dim(PolynomialRing)"
  * "dim(QuotientRing)"
  * dim(Ring) -- compute the Krull dimension

directSum -- direct sum of modules or maps
******************************************

Description
===========

directSum(M,N,...) -- forms the direct sum of matrices or modules.

The components can be recovered later with components, or
with formation.

Projection and inclusion maps for direct sums:
  * Module ^ Array -- projection onto summand
  * Module _ Array -- inclusion from summand
  * Matrix ^ List -- select rows
  * Matrix _ List -- select columns

It sometimes happens that the user has indices for the components of a direct
sum preferable to the usual consecutive small integers.  In this case the
preferred indices can be specified with code like directSum(a=>M,b=>N,...), as
in the following example.
+---------------------------------------------+
|i1 : F = directSum(a=>ZZ^1, b=>ZZ^2, c=>ZZ^3)|
|                                             |
|       6                                     |
|o1 = ZZ                                      |
|                                             |
|o1 : ZZ-module, free                         |
+---------------------------------------------+
|i2 : F_[b]                                   |
|                                             |
|o2 = | 0 0 |                                 |
|     | 1 0 |                                 |
|     | 0 1 |                                 |
|     | 0 0 |                                 |
|     | 0 0 |                                 |
|     | 0 0 |                                 |
|                                             |
|              6       2                      |
|o2 : Matrix ZZ  <-- ZZ                       |
+---------------------------------------------+
|i3 : F^[c]                                   |
|                                             |
|o3 = | 0 0 0 1 0 0 |                         |
|     | 0 0 0 0 1 0 |                         |
|     | 0 0 0 0 0 1 |                         |
|                                             |
|              3       6                      |
|o3 : Matrix ZZ  <-- ZZ                       |
+---------------------------------------------+
Similar syntax works with ++.
+-----------------------------------+
|i4 : F = (a => ZZ^1) ++ (b => ZZ^2)|
|                                   |
|       3                           |
|o4 = ZZ                            |
|                                   |
|o4 : ZZ-module, free               |
+-----------------------------------+
|i5 : F_[b]                         |
|                                   |
|o5 = | 0 0 |                       |
|     | 1 0 |                       |
|     | 0 1 |                       |
|                                   |
|              3       2            |
|o5 : Matrix ZZ  <-- ZZ             |
+-----------------------------------+

See also
========

  * ++ -- a binary operator, usually used for direct sum
  * components -- list the components of a direct sum
  * indexComponents -- specify keys for components of a
    direct sum
  * indices -- indices of a polynomial; also components for a
    direct sum
  * formation -- recover the methods used to make a module

Ways to use directSum:
======================

  * "directSum(ChainComplex)"
  * "directSum(GradedModule)"
  * "directSum(List)"
  * "directSum(Matrix)"
  * "directSum(Module)"
  * "directSum(Option)"
  * "directSum(Sequence)"
  * directSum(CoherentSheaf) (missing documentation)
  * directSum(SheafMap) (missing documentation)

For the programmer
==================

The object directSum, is a method function with a single argument.

disassemble -- disassemble a pseudocode or function
***************************************************

Synopsis
========

  * Usage:
        disassemble c
  * Inputs:
      * c, a function, or an instance of the type
        Pseudocode,
  * Outputs:
      * a string, the disassembled form of c

Description
===========

+----------------------------------------------------------------------------+
|i1 : disassemble (() -> 1/(1-1))                                            |
|                                                                            |
|o1 = (function restargs: false numparms: 0 framesize: 0 frameID: 11672 (2-OP|
|     / 1 (2-OP - 1 1)))                                                     |
+----------------------------------------------------------------------------+
|i2 : disassemble functionBody (() -> 1/(1-1))                               |
|                                                                            |
|o2 = (2-OP / 1 (2-OP - 1 1))                                                |
+----------------------------------------------------------------------------+

It may be useful to disassemble code during debugging, as in the following
demonstration.

+-----------------------------------------------------------------------------+
|i3 : load "Macaulay2Doc/demo1.m2"                                            |
+-----------------------------------------------------------------------------+
|i4 : code g                                                                  |
|                                                                             |
|o4 = /usr/local/share/Macaulay2/Macaulay2Doc/                                |
|     demo1.m2:11:4-14:9: --source code:                                      |
|     g = y -> (                                                              |
|          c := f(y-1);                                                       |
|          d := f(y-2);                                                       |
|          c+d)                                                               |
+-----------------------------------------------------------------------------+
|i5 : g 2                                                                     |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|8:10-8:13: --source code:                                                    |
|     b := 1/x;                                                               |
|-----------------------------------------------------------------------------|
|error: division by zero                                                      |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
|ii6 : code current                                                           |
|                                                                             |
|oo6 = /usr/local/share/Macaulay2/Macaulay2Doc/                               |
|      demo1.m2:8:10-8:13: --source code:                                     |
|           b := 1/x;                                                         |
+-----------------------------------------------------------------------------+
|ii7 : disassemble current                                                    |
|                                                                             |
|oo7 = (2-OP / 1 (local-fetch 0 0))                                           |
+-----------------------------------------------------------------------------+
|ii8 : current                                                                |
|                                                                             |
|oo8 = 2-OP / 1                                                               |
|             local-fetch 0 0                                                 |
|                                                                             |
|oo8 : PseudocodeClosure                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * pseudocode -- produce the pseudocode for a function

Ways to use disassemble:
========================

  * disassemble(FunctionBody) (missing documentation)
  * disassemble(FunctionClosure) (missing documentation)
  * disassemble(Pseudocode) (missing documentation)
  * disassemble(PseudocodeClosure) (missing documentation)

For the programmer
==================

The object disassemble, is a compiled function.

Divide -- the class of all divide expressions
*********************************************

Description
===========

Divide is a type of Expression, representing a quotient.

Methods that use a divide expression:
=====================================

  * "denominator(Divide)" -- see denominator, -- denominator
    of a fraction
  * "numerator(Divide)" -- see numerator, -- numerator of a
    fraction
  * "reduceHilbert(Divide)" -- see reduceHilbert, --
    reduce a Hilbert series expression

For the programmer
==================

The object Divide, is a header type, with
ancestor classes Expression, < BasicList <
Thing.

divideByVariable -- divide all columns by a (power of a) variable
*****************************************************************

Description
===========

divideByVariable(m,v) -- divide each column of the matrix 'm' by as high a
power of the variable 'v' as possible.
divideByVariable(m,v,d) -- divide each column of the matrix 'm' by as high a
power of the variable 'v' as possible, but divide by no more than v^d.

+---------------------------------------------+
|i1 : R = ZZ/101[a..d]                        |
|                                             |
|o1 = R                                       |
|                                             |
|o1 : PolynomialRing                          |
+---------------------------------------------+
|i2 : m = matrix{{a*b, a^2*c}, {a*b^2, a^4*d}}|
|                                             |
|o2 = | ab  a2c |                             |
|     | ab2 a4d |                             |
|                                             |
|             2      2                        |
|o2 : Matrix R  <-- R                         |
+---------------------------------------------+
|i3 : divideByVariable(m,a)                   |
|                                             |
|o3 = (| b  c   |, 2)                         |
|      | b2 a2d |                             |
|                                             |
|o3 : Sequence                                |
+---------------------------------------------+
|i4 : divideByVariable(m,a,1)                 |
|                                             |
|o4 = (| b  ac  |, 1)                         |
|      | b2 a3d |                             |
|                                             |
|o4 : Sequence                                |
+---------------------------------------------+

We may eliminate this routine.

Caveat
======

You can only divide by a variable, not a monomial, and you have little control
on what power will be divided.  This routine is mostly used by the saturation
commands as a fast internal way of dividing.

Ways to use divideByVariable:
=============================

  * "divideByVariable(Matrix,RingElement)"
  * "divideByVariable(Matrix,RingElement,ZZ)"

For the programmer
==================

The object divideByVariable, is a method function.

division in polynomial rings with monomials less than 1
*******************************************************

Starting with version 1.2, a new division algorithm has been implemented in
rings with inverses, where the monomials can involve negative exponents, and
hence do not form a well-ordered set.  The ring should have a monomial ordering
whose first test involves at least one weight vector, explicitly, or perhaps
implicitly, as with GRevLex.  The algorithm will work when
dividing by a polynomial that is monic in the sense that its lead monomial has
coefficient 1, and all other terms have smaller weight, where the weight is
computed with respect to just the first weight vector.  When we say the
algorithm works, we mean: (1) that it terminates; and (2) that the remainder is
zero if and only if the denominator divides the numerator.

Define the length of a nonzero ring element to be the weight of the first term
minus the weight of the last term.  The length is greater than or equal to 0,
because the terms in a sorted polynomial are decreasing in weight.

We refuse to start dividing unless the denominator is monic in the sense
defined above. When dividing, we keep subtracting monomial multiples of the
denominator from the numerator to eliminate the lead term of the numerator,
which is always possible because the ring contains the reciprocals of its
variables.  We stop when we get a remainder whose length is strictly less than
the length of the denominator.

This algorithm works because, in an integral domain, the length of a product is
the sum of the lengths of the factors.  Thus the remainder, if it is not zero,
can not be a multiple of the denominator.

This will be good enough for applications to Hilbert series, because in our
degrees rings, the denominator of a Hilbert series will be a product of terms
1-T, where T is a monomial of strictly negative weight.  That's because the
weight vector is minus the heft vector of the original ring, and T is the
monomial constructed from the degree vector of one of the variables in the
original ring.  Note that any divisor of such a product will also be 1 plus
terms of negative weight.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y, Inverses => true, MonomialOrder => Lex, Weights => {1,2}]   |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : quotientRemainder(x^100 - x^89, x^5 - 1)                                |
|                                                                             |
|       95    90   90    89                                                   |
|o2 = (x   + x  , x   - x  )                                                  |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i3 : quotientRemainder(x^100 - y^61, x^5 - 1)                                |
|                                                                             |
|       95    90    85    80    75    70    65    60    55    50    45    40  |
|o3 = (x   + x   + x   + x   + x   + x   + x   + x   + x   + x   + x   + x   +|
|     ------------------------------------------------------------------------|
|      35    30    25    20    15    10    5         61                       |
|     x   + x   + x   + x   + x   + x   + x  + 1, - y   + 1)                  |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * heft vectors
  * polynomial rings
  * degreesRing -- the ring or monoid of degrees

do -- loop control
******************

Description
===========

do a keyword used with while, and for.

For the programmer
==================

The object do, is a keyword.

drop -- drop some elements from a list or sequence.
***************************************************

Synopsis
========

  * Usage:
        drop(L, i)
        drop(L, {j,k})
  * Inputs:
      * L, a basic list,
      * i, an integer,
      * j, an integer,
      * k, an integer,
  * Outputs:
      * L2, a basic list, the list or sequence obtained by
        dropping the first i elements of L, (if i positive), or the last i
        elements of L (if i negative), or, if given the pair j,k, the list or
        sequence obtained by dropping the elements of L with indices j through
        k

Description
===========

+---------------------------------+
|i1 : drop({a,b,c,d,e,f,g}, 3)    |
|                                 |
|o1 = {d, e, f, g}                |
|                                 |
|o1 : List                        |
+---------------------------------+
|i2 : drop({a,b,c,d,e,f,g}, -3)   |
|                                 |
|o2 = {a, b, c, d}                |
|                                 |
|o2 : List                        |
+---------------------------------+
|i3 : drop({a,b,c,d,e,f,g}, {1,3})|
|                                 |
|o3 = {a, e, f, g}                |
|                                 |
|o3 : List                        |
+---------------------------------+
|i4 : drop({a,b,c,d,e,f,g}, {2,2})|
|                                 |
|o4 = {a, b, d, e, f, g}          |
|                                 |
|o4 : List                        |
+---------------------------------+

The pair \{j,k\} must be given with both entries non-negative, and $j\le k$.
Otherwise the original list is returned.

+----------------------------------+
|i5 : drop({a,b,c,d,e,f,g}, {3,1}) |
|                                  |
|o5 = {a, b, c, d, e, f, g}        |
|                                  |
|o5 : List                         |
+----------------------------------+
|i6 : drop({a,b,c,d,e,f,g}, {4,-1})|
|                                  |
|o6 = {a, b, c, d, e, f, g}        |
|                                  |
|o6 : List                         |
+----------------------------------+

See also
========

  * take -- Take some elements from a list or sequence.
  * delete -- delete some elements of a list
  * position -- the first element of a list satisfying a
    condition
  * positions -- which elements of a list satisfy a condition
  * select -- select from a list, hash table, or string
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use drop:
=================

  * "drop(BasicList,List)"
  * "drop(BasicList,ZZ)"

For the programmer
==================

The object drop, is a compiled function.

dual -- dual module or map
**************************

Ways to use dual:
=================

  * "dual(BettiTally)" -- see BettiTally, -- the class of all
    Betti tallies
  * dual(ChainComplex) -- dual
  * dual(ChainComplexMap) -- dual of a chain
    complex
  * dual(CoherentSheaf) (Varieties) -- dual
    coherent sheaf
  * dual(Matrix) -- dual of a map
  * dual(Module) -- dual module
  * dual(MonomialIdeal) -- the Alexander dual
    of a monomial ideal
  * dual(MonomialIdeal,List) -- the
    Alexander dual
  * dual(MonomialIdeal,RingElement)
    -- the Alexander dual
  * dual(SheafMap) (missing documentation)

For the programmer
==================

The object dual, is a method function with options.

dual(ChainComplex) -- dual
**************************

Synopsis
========

  * Function: dual,

Description
===========

dual C -- the dual of a chain complex.

Ways to use this method:
========================

  * dual(ChainComplex) -- dual

dual(ChainComplexMap) -- dual of a chain complex
************************************************

Synopsis
========

  * Function: dual,
  * Usage:
        dual C
  * Inputs:
      * C
  * Outputs:
      * the dual of the chain complex C

Description
===========

+-------------------------------------+
|i1 : R = QQ[a..f]                    |
|                                     |
|o1 = R                               |
|                                     |
|o1 : PolynomialRing                  |
+-------------------------------------+
|i2 : M = coker genericMatrix(R,a,2,3)|
|                                     |
|o2 = cokernel | a c e |              |
|              | b d f |              |
|                                     |
|                            2        |
|o2 : R-module, quotient of R         |
+-------------------------------------+
|i3 : res M                           |
|                                     |
|      2      3      1                |
|o3 = R  <-- R  <-- R  <-- 0          |
|                                     |
|     0      1      2      3          |
|                                     |
|o3 : ChainComplex                    |
+-------------------------------------+
|i4 : dual oo                         |
|                                     |
|             1      3      2         |
|o4 = 0  <-- R  <-- R  <-- R          |
|                                     |
|     -3     -2     -1     0          |
|                                     |
|o4 : ChainComplex                    |
+-------------------------------------+

Ways to use this method:
========================

  * dual(ChainComplexMap) -- dual of a chain
    complex

dual(Matrix) -- dual of a map
*****************************

Synopsis
========

  * Function: dual,

Description
===========

dual f -- the dual (transpose) of a homomorphism.

Ways to use this method:
========================

  * dual(Matrix) -- dual of a map

dual(Module) -- dual module
***************************

Synopsis
========

  * Function: dual,

Description
===========

dual M -- the dual of a module.

Ways to use this method:
========================

  * dual(Module) -- dual module

dual(MonomialIdeal) -- the Alexander dual of a monomial ideal
*************************************************************

Synopsis
========

  * Function: dual,
  * Usage:
        dual I
  * Inputs:
      * I, a monomial ideal
  * Optional inputs,:
      * Strategy, => ...,
        default value 0,
  * Outputs:
      * the Alexander dual of I

Description
===========

If Iis a square free monomial ideal then I is the Stanley-Reisner ideal of a
simplicial complex.  In this case, dual I is the Stanley-Reisner ideal
associated to the dual complex. In particular, dual I is obtained by switching
the roles of minimal generators and prime components.
+-------------------------------------+
|i1 : QQ[a,b,c,d];                    |
+-------------------------------------+
|i2 : I = monomialIdeal(a*b, b*c, c*d)|
|                                     |
|o2 = monomialIdeal (a*b, b*c, c*d)   |
|                                     |
|o2 : MonomialIdeal of QQ[a..d]       |
+-------------------------------------+
|i3 : dual I                          |
|                                     |
|o3 = monomialIdeal (a*c, b*c, b*d)   |
|                                     |
|o3 : MonomialIdeal of QQ[a..d]       |
+-------------------------------------+
|i4 : intersect(monomialIdeal(a,b),   |
|               monomialIdeal(b,c),   |
|               monomialIdeal(c,d))   |
|                                     |
|o4 = monomialIdeal (a*c, b*c, b*d)   |
|                                     |
|o4 : MonomialIdeal of QQ[a..d]       |
+-------------------------------------+
|i5 : dual dual I                     |
|                                     |
|o5 = monomialIdeal (a*b, b*c, c*d)   |
|                                     |
|o5 : MonomialIdeal of QQ[a..d]       |
+-------------------------------------+

For a general monomial ideal, the Alexander dual defined as follows:  Given two
list of nonnegative integers a and bfor which a_i >= b_i for all i let a\b
denote the list whose i-th entry is a_i+1-b_iif b_i >= 1and 0otherwise.  The
Alexander dual with respect to a is the ideal generated by a monomial x^a\b for
each irreducible component (x_i^b_i) of I. If a is not provided, it is assumed
to be the least common multiple of the minimal generators of I.
+---------------------------------------+
|i6 : QQ[x,y,z];                        |
+---------------------------------------+
|i7 : I = monomialIdeal(x^3, x*y, y*z^2)|
|                                       |
|                     3          2      |
|o7 = monomialIdeal (x , x*y, y*z )     |
|                                       |
|o7 : MonomialIdeal of QQ[x..z]         |
+---------------------------------------+
|i8 : dual(I, {4,4,4})                  |
|                                       |
|                     2 4   4 3         |
|o8 = monomialIdeal (x y , x z )        |
|                                       |
|o8 : MonomialIdeal of QQ[x..z]         |
+---------------------------------------+
|i9 : intersect( monomialIdeal(x^2),    |
|               monomialIdeal(x^4, y^4),|
|               monomialIdeal(y^4, z^3))|
|                                       |
|                     2 4   4 3         |
|o9 = monomialIdeal (x y , x z )        |
|                                       |
|o9 : MonomialIdeal of QQ[x..z]         |
+---------------------------------------+

One always has dual( dual(I, a), a) == I however dual dual Imay not equal I.
+----------------------------------------------------+
|i10 : QQ[x,y,z];                                    |
+----------------------------------------------------+
|i11 : J = monomialIdeal( x^3*y^2, x*y^4, x*z, y^2*z)|
|                                                    |
|                      3 2     4        2            |
|o11 = monomialIdeal (x y , x*y , x*z, y z)          |
|                                                    |
|o11 : MonomialIdeal of QQ[x..z]                     |
+----------------------------------------------------+
|i12 : dual dual J                                   |
|                                                    |
|                      3      3                      |
|o12 = monomialIdeal (x y, x*y , x*z, y*z)           |
|                                                    |
|o12 : MonomialIdeal of QQ[x..z]                     |
+----------------------------------------------------+
|i13 : dual( dual(J, {3,4,1}), {3,4,1})              |
|                                                    |
|                      3 2     4        2            |
|o13 = monomialIdeal (x y , x*y , x*z, y z)          |
|                                                    |
|o13 : MonomialIdeal of QQ[x..z]                     |
+----------------------------------------------------+

See Ezra Miller's Ph.D. thesis 'Resolutions and Duality for Monomial Ideals'.

Implemented by Greg Smith.

The computation is done by calling the frobby, library, written
by B. H. Roune; setting gbTrace, to a positive value will cause
a message to be printed when it is called.

Ways to use this method:
========================

  * dual(MonomialIdeal) -- the Alexander dual
    of a monomial ideal

dual(MonomialIdeal,List) -- the Alexander dual
**********************************************

Synopsis
========

  * Function: dual,
  * Usage:
        dual(I,e)
  * Inputs:
      * I, a monomial ideal
      * e, a list of exponents
  * Optional inputs,:
      * Strategy, => ...,
        default value 0,
  * Outputs:
      * the Alexander dual of I formed with respect to the monomial whose
        exponents are listed in e

Description
===========

The monomial corresponding to e should be divisible by all of the minimal
generators of I.

The computation is done by calling the frobby, library, written
by B. H. Roune; setting gbTrace, to a positive value will cause
a message to be printed when it is called.

See also
========

  * dual(MonomialIdeal) -- the Alexander dual
    of a monomial ideal

Ways to use this method:
========================

  * dual(MonomialIdeal,List) -- the
    Alexander dual

dual(MonomialIdeal,RingElement) -- the Alexander dual
*****************************************************

Synopsis
========

  * Function: dual,
  * Usage:
        dual(I,m)
  * Inputs:
      * I, a monomial ideal
      * m, a monomial
  * Optional inputs,:
      * Strategy, => ...,
        default value 0,
  * Outputs:
      * the Alexander dual of I formed with respect to m.

Description
===========

The monomial m should be divisible by all of the minimal generators of I.

See also
========

  * dual(MonomialIdeal) -- the Alexander dual
    of a monomial ideal

Ways to use this method:
========================

  * dual(MonomialIdeal,RingElement)
    -- the Alexander dual

dual(MonomialIdeal,Strategy=>...)
*********************************

Description
===========

Specify Strategy => 1 to test an older strategy for performing the computation.

Further information
===================

  * Default value: 0
  * Method: dual(MonomialIdeal), -- the
    Alexander dual of a monomial ideal
  * Option key: Strategy, -- an optional argument

Functions with optional argument named Strategy:
================================================

  * "addHook(...,Strategy=>...)" -- see addHook, -- add a hook
    function to an object for later processing
  * adjoint(...,Strategy=>...) (missing documentation)
  * "annihilator(...,Strategy=>...)" -- see annihilator (Saturation),
    -- the annihilator ideal
  * "associatedPrimes(...,Strategy=>...)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "basis(...,Strategy=>...)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * canonicalBundle(...,Strategy=>...) (missing documentation)
  * "mingens(...,Strategy=>...)" -- see Complement, -- a
    Strategy option value
  * "trim(...,Strategy=>...)" -- see Complement, -- a
    Strategy option value
  * "compose(Module,Module,Module,Strategy=>...)" -- see compose,
    -- composition as a pairing on Hom-modules
  * cotangentSheaf(...,Strategy=>...) (missing documentation)
  * determinant(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * dual(ChainComplex,Strategy=>...) (missing documentation)
  * dual(Matrix,Strategy=>...) (missing documentation)
  * "dual(MonomialIdeal,List,Strategy=>...)"
  * "dual(MonomialIdeal,RingElement,Strategy=>...)"
  * dual(MonomialIdeal,Strategy=>...)
  * dual(SheafMap,Strategy=>...) (missing documentation)
  * "End(...,Strategy=>...)" -- see End, -- module of endomorphisms
  * exteriorPower(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * "gb(...,Strategy=>...)" -- see gb, -- compute a Gröbner basis
  * gcdLLL(...,Strategy=>...) (missing documentation)
  * "GF(...,Strategy=>...)" -- see GF, -- make a finite field
  * "groebnerBasis(...,Strategy=>...)" -- see groebnerBasis,
    -- Gröbner basis, as a matrix
  * hermite(...,Strategy=>...) (missing documentation)
  * "Hom(...,Strategy=>...)" -- see Hom, -- module of homomorphisms
  * "homomorphism'(...,Strategy=>...)" -- see homomorphism',
    -- get the element of Hom from a homomorphism
  * "hooks(...,Strategy=>...)" -- see hooks, -- list hooks
    attached to a key
  * "idealizer(...,Strategy=>...)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * integralClosure(...,Strategy=>...) (IntegralClosure),
    --
    control the algorithm used
  * "intersect(Ideal,Ideal,Strategy=>...)" -- see intersect(Ideal,Ideal),
    -- compute an intersection of a sequence of
    ideals or modules
  * "intersect(Module,Module,Strategy=>...)" -- see
    intersect(Ideal,Ideal), -- compute an
    intersection of a sequence of ideals or modules
  * "intersectInP(...,Strategy=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "isPrimary(...,Strategy=>...)" -- see isPrimary (PrimaryDecomposition),
    -- determine whether a submodule is
    primary
  * "isPrime(Ideal,Strategy=>...)" -- see isPrime(Ideal) (MinimalPrimes),
    -- whether an ideal is prime
  * LLL(...,Strategy=>...) (LLLBases)
    -- choose among
    different algorithms
  * "localize(...,Strategy=>...)" -- see localize (PrimaryDecomposition),
    -- localize an ideal at a prime ideal
  * "match(...,Strategy=>...)" -- see match, -- regular expression
    matching
  * "decompose(Ideal,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * minors(...,Strategy=>...)
    -- choose between Bareiss,
    Cofactor and Dynamic algorithms
  * "parallelApply(...,Strategy=>...)" -- see parallelApply,
    -- apply a function to each element in parallel
  * "primaryComponent(...,Strategy=>...)" -- see primaryComponent (PrimaryDecomposition),
    -- find a primary component
    corresponding to an associated prime
  * pushForward(...,Strategy=>...) (missing documentation)
  * quotient(...,Strategy=>...) (Saturation)
  * "radical(...,Strategy=>...)" -- see radical (MinimalPrimes),
    -- the radical of an ideal
  * "radicalContainment(...,Strategy=>...)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * "analyticSpread(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "associatedGradedRing(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "distinguished(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isLinearType(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isReduction(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "minimalReduction(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "multiplicity(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(Ideal,RingElement,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(Ideal,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "reesAlgebra(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * reesIdeal(...,Strategy=>...) (ReesAlgebra)
    -- Choose a
    strategy for the saturation step
  * "specialFiber(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "specialFiberIdeal(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "regSeqInIdeal(...,Strategy=>...)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * resolution(...,Strategy=>...)
  * saturate(...,Strategy=>...) (Saturation)
  * sheafHom(...,Strategy=>...) (missing documentation)
  * "primaryDecomposition(...,Strategy=>...)" -- see strategies for computing primary decomposition (PrimaryDecomposition),
  * "syz(...,Strategy=>...)" -- see syz(Matrix), --
    compute the syzygy matrix
  * "tangentCone(...,Strategy=>...)" -- see tangentCone(Ideal) (TangentCone),
  * tangentSheaf(...,Strategy=>...) (missing documentation)

Dynamic
*******

Description
===========

This symbol is used as one of the permissible values for the strategy option in
function dealing with determinants.

See also
========

  * exteriorPower(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * minors(...,Strategy=>...)
    -- choose between Bareiss,
    Cofactor and Dynamic algorithms
  * determinant(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms

For the programmer
==================

The object Dynamic, is a symbol.

eagonNorthcott(Matrix) -- Eagon-Northcott complex of a matrix of linear forms
*****************************************************************************

Synopsis
========

  * Function: eagonNorthcott,
  * Usage:
        eagonNorthcott f
  * Inputs:
      * f, a matrix of linear forms
  * Outputs:
      * C, the Eagon-Northcott complex of f

Description
===========

The Eagon-Northcott complex is an explicit chain complex that gives a minimal
projective resolution of the cokernel of the matrix maximal minors of a generic
matrix of linear forms.
+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..z]                                                            |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : f = genericMatrix(R,3,5)                                                |
|                                                                             |
|o2 = | a d g j m |                                                           |
|     | b e h k n |                                                           |
|     | c f i l o |                                                           |
|                                                                             |
|             3      5                                                        |
|o2 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i3 : M = coker gens minors_3 f                                               |
|                                                                             |
|o3 = cokernel | -ceg+bfg+cdh-afh-bdi+aei -cej+bfj+cdk-afk-bdl+ael            |
|                                                                             |
|                            1                                                |
|o3 : R-module, quotient of R                                                 |
|-----------------------------------------------------------------------------|
|-chj+bij+cgk-aik-bgl+ahl -fhj+eij+fgk-dik-egl+dhl -cem+bfm+cdn-afn-bdo+aeo   |
|-----------------------------------------------------------------------------|
|-chm+bim+cgn-ain-bgo+aho -fhm+eim+fgn-din-ego+dho -ckm+blm+cjn-aln-bjo+ako   |
|-----------------------------------------------------------------------------|
|-fkm+elm+fjn-dln-ejo+dko -ikm+hlm+ijn-gln-hjo+gko |                          |
+-----------------------------------------------------------------------------+
|i4 : C = res M                                                               |
|                                                                             |
|      1      10      15      6                                               |
|o4 = R  <-- R   <-- R   <-- R  <-- 0                                         |
|                                                                             |
|     0      1       2       3      4                                         |
|                                                                             |
|o4 : ChainComplex                                                            |
+-----------------------------------------------------------------------------+
|i5 : D = eagonNorthcott f                                                    |
|                                                                             |
|      1      10      15      6                                               |
|o5 = R  <-- R   <-- R   <-- R  <-- 0                                         |
|                                                                             |
|     0      1       2       3      4                                         |
|                                                                             |
|o5 : ChainComplex                                                            |
+-----------------------------------------------------------------------------+
|i6 : H = prune HH D                                                          |
|                                                                             |
|o6 = 0 : cokernel | ikm-hlm-ijn+gln+hjo-gko fkm-elm-fjn+dln+ejo-dko          |
|         ckm-blm-cjn+aln+bjo-ako fhm-eim-fgn+din+ego-dho                     |
|         chm-bim-cgn+ain+bgo-aho cem-bfm-cdn+afn+bdo-aeo                     |
|         fhj-eij-fgk+dik+egl-dhl chj-bij-cgk+aik+bgl-ahl                     |
|         cej-bfj-cdk+afk+bdl-ael ceg-bfg-cdh+afh+bdi-aei |                   |
|                                                                             |
|     1 : 0                                                                   |
|                                                                             |
|     2 : 0                                                                   |
|                                                                             |
|     3 : 0                                                                   |
|                                                                             |
|     4 : 0                                                                   |
|                                                                             |
|o6 : GradedModule                                                            |
+-----------------------------------------------------------------------------+
|i7 : assert( H_0 == M and H_1 == 0 and H_2 == 0 and H_3 == 0 )               |
+-----------------------------------------------------------------------------+
This function was written by Greg Smith.

Ways to use this method:
========================

  * eagonNorthcott(Matrix), --
    Eagon-Northcott complex of a matrix of linear forms

echoOff -- turn off echoing
***************************

Description
===========

echoOff f -- turns off echoing for the file f.

Ways to use echoOff:
====================

  * "echoOff(File)"

For the programmer
==================

The object echoOff, is a compiled function.

echoOn -- turn on echoing
*************************

Description
===========

echoOn f -- turns on echoing for the file f.

Ways to use echoOn:
===================

  * "echoOn(File)"

For the programmer
==================

The object echoOn, is a compiled function.

edit -- edit source code
************************

Description
===========

Synopsis
========

  * Usage:
        edit f
  * Inputs:
      * f, a function, or a command,
  * Outputs:
      * a net, the editor is started up, pointing at the source
        code of the function or commandf

Synopsis
========

  * Usage:
        edit(f,X)
  * Inputs:
      * f, a function, or a keyword,
      * X, a type,
  * Outputs:
      * a net, the editor is started up, pointing at the source
        code of method for applying f to an argument of type X

Synopsis
========

  * Usage:
        edit(f,X,Y)
  * Inputs:
      * f, a function, or a keyword,
      * X, a type,
      * Y, a type,
  * Outputs:
      * a net, the editor is started up, pointing at the source
        code of method for applying f to arguments of type X and Y

Synopsis
========

  * Usage:
        edit(f,X,Y,Z)
  * Inputs:
      * f, a function, or a keyword,
      * X, a type,
      * Y, a type,
      * Z, a type,
  * Outputs:
      * a net, the editor is started up, pointing at the source
        code of method for applying f to arguments of type X, Y, and Z

Synopsis
========

  * Usage:
        edit(f,X,Y,Z,T)
  * Inputs:
      * f, a function, or a keyword,
      * X, a type,
      * Y, a type,
      * Z, a type,
      * T, a type,
  * Outputs:
      * a net, the editor is started up, pointing at the source
        code of method for applying f to arguments of type X, Y, and Z, and T

The name of the user's preferred editor is take from the environment variable
EDITOR.  If X is running and the editor is not emacs, then the editor is
started in a new xterm window.

For an interactive example, try edit(dim,Module).

The value returned is the exit code returned by the editor, as with run,
usually zero.

For the programmer
==================

The object edit, is a command.

eigenvalues -- find eigenvalues of a matrix
*******************************************

Synopsis
========

  * Usage:
        eigenvalues M
  * Inputs:
      * M, a matrix,  or a MutableMatrix,
        over RR, or CC, which is a square n by n matrix
  * Optional inputs,:
      * Hermitian, =>
        ..., default value false, Hermitian=>true means assume the matrix is
        symmetric or Hermitian
  * Outputs:
      * a vertical list,  a list of the eigenvalues of M

Description
===========

In this example we compute the eigenvalues of a matrix and display their
classes.
+------------------------------+
|i1 : M = matrix {{1,2}, {5,7}}|
|                              |
|o1 = | 1 2 |                  |
|     | 5 7 |                  |
|                              |
|              2       2       |
|o1 : Matrix ZZ  <-- ZZ        |
+------------------------------+
|i2 : eigenvalues M            |
|                              |
|o2 = {-.358899}               |
|     {8.3589  }               |
|                              |
|o2 : VerticalList             |
+------------------------------+
|i3 : class \ oo               |
|                              |
|o3 = {CC}                     |
|     {CC}                     |
|                              |
|o3 : VerticalList             |
+------------------------------+
If the matrix is symmetric (over RR) or Hermitian (over CC),
this information may be provided as an optional argument Hermitian=>true,
so the resulting eigenvalues will be in RR, not CC.
+------------------------------------+
|i4 : M = matrix {{1,2}, {2,1}}      |
|                                    |
|o4 = | 1 2 |                        |
|     | 2 1 |                        |
|                                    |
|              2       2             |
|o4 : Matrix ZZ  <-- ZZ              |
+------------------------------------+
|i5 : eigenvalues(M, Hermitian=>true)|
|                                    |
|o5 = {-1}                           |
|     {3 }                           |
|                                    |
|o5 : VerticalList                   |
+------------------------------------+
|i6 : class \ oo                     |
|                                    |
|o6 = {RR}                           |
|     {RR}                           |
|                                    |
|o6 : VerticalList                   |
+------------------------------------+
The lapack and eigen libraries are used to compute eigenvectors of real and
complex matrices.

Caveat
======

The eigenvalues are approximate.

See also
========

  * eigenvectors -- find eigenvectors of a matrix over RR
    or CC
  * SVD -- singular value decomposition of a matrix

Ways to use eigenvalues:
========================

  * "eigenvalues(Matrix)"
  * "eigenvalues(MutableMatrix)"

For the programmer
==================

The object eigenvalues, is a method function with options.

eigenvalues(...,Hermitian=>...) -- Hermitian=>true means assume the matrix is symmetric or Hermitian
****************************************************************************************************

Synopsis
========

  * Usage:
        eigenvalues(M, Hermitian=>true)
  * Consequences:
      * The resulting matrix of eigenvalues is defined over RR, not CC.

Further information
===================

  * Default value: false,
  * Function: eigenvalues, -- find eigenvalues of a matrix
  * Option key: Hermitian, -- an optional argument

Caveat
======

The internal routine uses a different algorithm, only considering the upper
triangular elements.  So if the matrix is not symmetric or Hermitian, the
routine will give incorrect results.

See also
========

  * eigenvectors -- find eigenvectors of a matrix over RR
    or CC

Functions with optional argument named Hermitian:
=================================================

  * eigenvalues(...,Hermitian=>...)
    -- Hermitian=>true means
    assume the matrix is symmetric or Hermitian
  * eigenvectors(...,Hermitian=>...)
    -- Hermitian=>true
    means assume the matrix is symmetric or Hermitian

eigenvectors -- find eigenvectors of a matrix over RR or CC
***********************************************************

Synopsis
========

  * Usage:
        (eigvals, eigvecs) = eigenvectors M
  * Inputs:
      * M, a matrix, or a MutableMatrix,
        over RR, or CC, which is a square n by n matrix
  * Optional inputs,:
      * Hermitian, =>
        ..., default value false, Hermitian=>true means assume the matrix is
        symmetric or Hermitian
  * Outputs:
      * eigvals, a vertical list,  a list of the
        eigenvalues of M
      * eigvecs, a matrix,  or a mutable matrix,
        if M is one), whose columns are the corresponding
        eigenvectors of M

Description
===========

The resulting matrix is over CC, and contains the eigenvectors of M.
The lapack and eigen libraries are used to compute eigenvectors of real and
complex matrices.

Recall that if v is a non-zero vector such that Mv = av, for a scalar a, then v
is called an eigenvector corresponding to the eigenvalue a.
+----------------------------------------+
|i1 : M = matrix{{1, 2}, {5, 7}}         |
|                                        |
|o1 = | 1 2 |                            |
|     | 5 7 |                            |
|                                        |
|              2       2                 |
|o1 : Matrix ZZ  <-- ZZ                  |
+----------------------------------------+
|i2 : eigenvectors M                     |
|                                        |
|o2 = ({-.358899}, | -.827138 -.262266 |)|
|      {8.3589  }  | .561999  -.964996 | |
|                                        |
|o2 : Sequence                           |
+----------------------------------------+
If the matrix is symmetric (over RR) or Hermitian (over CC),
this information should be provided as an optional argument
Hermitian=>true.  In this case, the resulting eigenvalues will be returned as
real numbers, and if M is real, the matrix of eigenvectors will be real.
+---------------------------------------------+
|i3 : M = matrix {{1, 2}, {2, 1}}             |
|                                             |
|o3 = | 1 2 |                                 |
|     | 2 1 |                                 |
|                                             |
|              2       2                      |
|o3 : Matrix ZZ  <-- ZZ                       |
+---------------------------------------------+
|i4 : (e,v) = eigenvectors(M, Hermitian=>true)|
|                                             |
|o4 = ({-1}, | -.707107 .707107 |)            |
|      {3 }  | .707107  .707107 |             |
|                                             |
|o4 : Sequence                                |
+---------------------------------------------+
|i5 : class \ e                               |
|                                             |
|o5 = {RR}                                    |
|     {RR}                                    |
|                                             |
|o5 : VerticalList                            |
+---------------------------------------------+
|i6 : v                                       |
|                                             |
|o6 = | -.707107 .707107 |                    |
|     | .707107  .707107 |                    |
|                                             |
|                2         2                  |
|o6 : Matrix RR    <-- RR                     |
|              53        53                   |
+---------------------------------------------+

Caveat
======

The eigenvectors are approximate.

See also
========

  * eigenvalues -- find eigenvalues of a matrix
  * SVD -- singular value decomposition of a matrix

Ways to use eigenvectors:
=========================

  * "eigenvectors(Matrix)"
  * "eigenvectors(MutableMatrix)"

For the programmer
==================

The object eigenvectors, is a method function with options.

eigenvectors(...,Hermitian=>...) -- Hermitian=>true means assume the matrix is symmetric or Hermitian
*****************************************************************************************************

Synopsis
========

  * Usage:
        eigenvectors(M, Hermitian=>true)
  * Consequences:
      * The resulting matrix of eigenvalues is defined over RR, not CC, and, if
        the original matrix is defined over RR, the matrix of eigenvalues is
        too.

Further information
===================

  * Default value: false,
  * Function: eigenvectors, -- find eigenvectors of a
    matrix over RR or CC
  * Option key: Hermitian, -- an optional argument

Caveat
======

The internal routine uses a different algorithm, only considering the upper
triangular elements.  So if the matrix is not symmetric or Hermitian, the
routine will give incorrect results.

See also
========

  * eigenvectors -- find eigenvectors of a matrix over RR
    or CC

Functions with optional argument named Hermitian:
=================================================

  * eigenvalues(...,Hermitian=>...)
    -- Hermitian=>true means
    assume the matrix is symmetric or Hermitian
  * eigenvectors(...,Hermitian=>...)
    -- Hermitian=>true
    means assume the matrix is symmetric or Hermitian

eint -- exponential integral
****************************

Synopsis
========

  * Usage:
        eint x
  * Inputs:
      * x
  * Outputs:
      * a real number, the exponential integral of x

Description
===========

+-------------------------+
|i1 : eint 2              |
|                         |
|o1 = 4.95423435600189    |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See Exponential integral (see
https://en.wikipedia.org/wiki/Exponential_integral ).

Ways to use eint:
=================

  * "eint(CC)"
  * "eint(RR)"
  * "eint(RRi)"

For the programmer
==================

The object eint, is a method function.

elements -- list of elements
****************************

Synopsis
========

  * Usage:
        elements S
  * Inputs:
      * S, a set, or a tally,
  * Outputs:
      * a list,

Description
===========

+---------------------+
|i1 : set{1,2,3,1,2,4}|
|                     |
|o1 = set {1, 2, 3, 4}|
|                     |
|o1 : Set             |
+---------------------+
|i2 : elements oo     |
|                     |
|o2 = {1, 2, 3, 4}    |
|                     |
|o2 : List            |
+---------------------+
+-----------------------------------+
|i3 : tally apply(10, i -> random 5)|
|                                   |
|o3 = Tally{0 => 2}                 |
|           1 => 1                  |
|           2 => 1                  |
|           3 => 5                  |
|           4 => 1                  |
|                                   |
|o3 : Tally                         |
+-----------------------------------+
|i4 : elements oo                   |
|                                   |
|o4 = {0, 0, 1, 2, 3, 3, 3, 3, 3, 4}|
|                                   |
|o4 : List                          |
+-----------------------------------+

See also
========

  * tally -- tally the elements of a list, sequence, array, or
    string
  * set -- make a set

Ways to use elements:
=====================

  * "elements(Set)"
  * "elements(Tally)"

For the programmer
==================

The object elements, is a method function.

else -- condition testing
*************************

Description
===========

else a keyword used with if.
+---------------------------+
|i1 : if 4 > 5 then 8 else 7|
|                           |
|o1 = 7                     |
+---------------------------+

See also
========

  * if -- condition testing
  * then -- condition testing

For the programmer
==================

The object else, is a keyword.

End -- module of endomorphisms
******************************

Synopsis
========

  * Usage:
        End M
  * Inputs:
      * M, a ring, an ideal, a module,
        or a chain complex,
  * Optional inputs,:
      * DegreeLimit => an integer, or a list, default
        value null, see Hom(...,DegreeLimit=>...),
      * MinimalGenerators => a Boolean value, default value
        true, see Hom(...,MinimalGenerators=>...),
      * Strategy => a thing, default value null, see
        Hom(...,Strategy=>...),

Description
===========

Constructs the module of endomorphisms of $M$.

+--------------------------------------------------------+
|i1 : R = QQ[a,b,c];                                     |
+--------------------------------------------------------+
|i2 : M = coker koszul_2 vars R                          |
|                                                        |
|o2 = cokernel {1} | -b -c 0  |                          |
|              {1} | a  0  -c |                          |
|              {1} | 0  a  b  |                          |
|                                                        |
|                            3                           |
|o2 : R-module, quotient of R                            |
+--------------------------------------------------------+
|i3 : End M                                              |
|                                                        |
|o3 = subquotient (| 1 |, | -b 0  -c 0  0  0  0  0  0  |)|
|                  | 0 |  | a  -c 0  0  0  0  0  0  0  | |
|                  | 0 |  | 0  b  a  0  0  0  0  0  0  | |
|                  | 0 |  | 0  0  0  -b 0  -c 0  0  0  | |
|                  | 1 |  | 0  0  0  a  -c 0  0  0  0  | |
|                  | 0 |  | 0  0  0  0  b  a  0  0  0  | |
|                  | 0 |  | 0  0  0  0  0  0  -b 0  -c | |
|                  | 0 |  | 0  0  0  0  0  0  a  -c 0  | |
|                  | 1 |  | 0  0  0  0  0  0  0  b  a  | |
|                                                        |
|                               9                        |
|o3 : R-module, subquotient of R                         |
+--------------------------------------------------------+

Code
====

../../../../../Macaulay2/m2/option.m2:15:14-18:8: --source code:
  (opts,f) -> args -> (
       -- Common code for functions created with >> to process options and
       uncurry(f, override (opts,args))
       )
| symbol  class            value
| ------  -----            -----
| f       FunctionClosure  FunctionClosure[../../../../../Macaulay2/m2/Hom.
| opts    OptionTable      OptionTable{DegreeLimit => null      }
|                                      MinimalGenerators => true
|                                      Strategy => null
| -- function f:
| ../../../../../Macaulay2/m2/Hom.m2:15:21-15:43: --source code:
| End = options Hom >> o -> M -> Hom(M, M, o)
| -- option table opts:
| OptionTable{DegreeLimit => null      }
|             MinimalGenerators => true
|             Strategy => null
-------------------------------------------------------------------------------
arguments.

         location of symbol
         ------------------
m2:15:.  ../../../../../Macaulay2/m2/option.m2:15:8-15:9
         ../../../../../Macaulay2/m2/option.m2:15:3-15:7

For the programmer
==================

The object End, is a function closure.

endl -- end an output line
**************************

Description
===========

f << endl -- ends the line currently being put out to the file f.

It is an essential portable programming practice to use endl always, for
writing newline characters (see newline) to a file will not
terminate a line containing nets properly, and it will not flush the output
buffer.

Ways to use endl:
=================

  * "File << Manipulator" -- see File << Thing, -- print
    to a file
  * "Nothing << Manipulator" -- see File << Thing, --
    print to a file
  * "Manipulator Database" -- see Manipulator, -- the class
    of all file manipulators
  * "Manipulator File" -- see Manipulator, -- the class of
    all file manipulators
  * "Manipulator Nothing" -- see Manipulator, -- the class
    of all file manipulators
  * "new Manipulator from Function" -- see Manipulator, --
    the class of all file manipulators
  * "methods(Manipulator)" -- see methods, -- list methods
  * "Manipulator NetFile" -- see NetFile, -- the class of all
    net files
  * "NetFile << Manipulator" -- see NetFile, -- the class of all
    net files

For the programmer
==================

The object endl, is a manipulator.

Engine -- specify whether a ring is handled by the engine
*********************************************************

Description
===========

Engine -- a key for rings that yields the value true if this ring is supported
by the engine.

For the programmer
==================

The object Engine, is a symbol.

engineDebugLevel -- current engine debugging level
**************************************************

Description
===========

This variable is in place, but the corresponding code is not implemented yet.

For the programmer
==================

The object engineDebugLevel, is an integer.

EngineRing -- the class of rings handled by the engine
******************************************************

Description
===========

The engine, handles most of the types of rings in the system.

The command new Engine from x is not meant for general users, and provides the
developers with a way to create top-level rings corresponding to rings
implemented in the engine.  Here x may be:
  * commands for the engine, as a string, or a sequence or list of strings,
    which cause a ring to be placed on the top of the engine's stack.
  * a ring, in which case another top-level ring is formed as an interface to
    the same underlying engine ring.
  * the handle of on engine ring

Types of engine ring:
=====================

  * FractionField -- the class of all fraction fields
  * GaloisField -- the class of all Galois fields
  * InexactField -- the class of inexact fields
  * PolynomialRing -- the class of all ordered monoid
    rings
  * QuotientRing -- the class of all quotient rings

Methods that use an engine ring:
================================

  * "frac(EngineRing)" -- see frac, -- construct a fraction field
  * "isField(EngineRing)" -- see isField, -- whether something
    is a field
  * "numgens(EngineRing)" -- see numgens(Ring), --
    number of generators of a polynomial ring

For the programmer
==================

The object EngineRing, is a type, with ancestor
classes Ring, < Type < MutableHashTable
< HashTable < Thing.

entries -- lists the entries of a matrix
****************************************

Synopsis
========

  * Usage:
        entries M
  * Inputs:
      * M, a Matrix, or a MutableMatrix,
  * Outputs:
      * a doubly nested List, of the entries of M

Description
===========

+-----------------------------------------------+
|i1 : R = ZZ[x,y,z];                            |
+-----------------------------------------------+
|i2 : M = matrix{{x,z,x*y},{x^2+z,y*z,1}}       |
|                                               |
|o2 = | x    z  xy |                            |
|     | x2+z yz 1  |                            |
|                                               |
|             2      3                          |
|o2 : Matrix R  <-- R                           |
+-----------------------------------------------+
|i3 : entries M                                 |
|                                               |
|                     2                         |
|o3 = {{x, z, x*y}, {x  + z, y*z, 1}}           |
|                                               |
|o3 : List                                      |
+-----------------------------------------------+
|i4 : N = mutableMatrix{{x,z,x*y},{x^2+z,y*z,1}}|
|                                               |
|o4 = | x    z  xy |                            |
|     | x2+z yz 1  |                            |
|                                               |
|o4 : MutableMatrix                             |
+-----------------------------------------------+
|i5 : entries N                                 |
|                                               |
|                     2                         |
|o5 = {{x, z, x*y}, {x  + z, y*z, 1}}           |
|                                               |
|o5 : List                                      |
+-----------------------------------------------+

Ways to use entries:
====================

  * "entries(Matrix)"
  * "entries(MutableMatrix)"
  * entries(Vector) -- lists the entries of a
    vector

For the programmer
==================

The object entries, is a method function.

entries(Vector) -- lists the entries of a vector
************************************************

Synopsis
========

  * Function: entries,
  * Usage:
        entries v
  * Inputs:
      * v
  * Outputs:
      * a List, of the coordinates of v

Description
===========

+--------------------------+
|i1 : R = (ZZ[x,y])^3;     |
+--------------------------+
|i2 : v = vector {1,x,x*y};|
|                          |
|               3          |
|o2 : (ZZ[x..y])           |
+--------------------------+
|i3 : entries v            |
|                          |
|o3 = {1, x, x*y}          |
|                          |
|o3 : List                 |
+--------------------------+

Ways to use this method:
========================

  * entries(Vector) -- lists the entries of a
    vector

equality and containment of modules
***********************************

==, isSubset

Equation -- the class of all equation expressions
*************************************************

Description
===========

Equation is a type of Expression, representing an equation.

For the programmer
==================

The object Equation, is a header type, with
ancestor classes AssociativeExpression, <
Expression < BasicList < Thing.

erase -- remove a global symbol
*******************************

Description
===========

erase s removes the global symbol s from the symbol table.

For the programmer
==================

The object erase, is a compiled function.

erf -- error function
*********************

Synopsis
========

  * Usage:
        erf x
  * Inputs:
      * x, a real number,
  * Outputs:
      * a real number, the error function of x;

Description
===========

The error function (see https://en.wikipedia.org/wiki/error_function )
\(\operatorname{erf} x = \frac{2}{\sqrt\pi}\int_0^x e^{-t^2}\,dt\).

+-------------------------+
|i1 : erf 2               |
|                         |
|o1 = .9953222650189527   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See also
========

  * erfc -- complementary error function
  * inverseErf -- inverse error function

Ways to use erf:
================

  * "erf(CC)"
  * "erf(RR)"
  * "erf(RRi)"

For the programmer
==================

The object erf, is a method function.

erfc -- complementary error function
************************************

Synopsis
========

  * Usage:
        erfc x
  * Inputs:
      * x, a real number,
  * Outputs:
      * a real number, the complementary error function of x;

Description
===========

The complementary error function (see
https://en.wikipedia.org/wiki/error_function ) \(\operatorname{erfc} x =
\frac{2}{\sqrt\pi}\int_x^\infty e^{-t^2}\,dt\).

+-------------------------+
|i1 : erfc 2              |
|                         |
|o1 = .004677734981047266 |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See also
========

  * erf -- error function
  * inverseErf -- inverse error function

Ways to use erfc:
=================

  * "erfc(CC)"
  * "erfc(RR)"
  * "erfc(RRi)"

For the programmer
==================

The object erfc, is a method function.

errorDepth -- set the error printing depth
******************************************

Description
===========

errorDepth = i -- sets the error depth to i, which should be a small integer,
returning the old value.

During the backtrace after an error message, a position in interpreted code is
displayed and the debugger is entered only if the load depth was at least as
large at the time the code was parsed as the error depth is now. The default
value is 3, which shows only positions in the user's code and positions inside
loaded packages whose debugging mode is true.  Set it to 2 to also debug
statements inside loaded packages, except for the package Core.
Set it to 1 to also debug statements in the core, and set it to 0 to debug
statements in the bootstrap code.

See also
========

  * loadDepth -- the load depth

For the programmer
==================

The object errorDepth, is an integer.

EulerConstant -- the Euler-Mascheroni constant
**********************************************

Synopsis
========

  * Usage:
        EulerConstant
  * Outputs:
      * a real number, the Euler-Mascheroni constant, converted to a
        numeric value of the correct precision, when necessary.

Description
===========

+-------------------------------------+
|i1 : EulerConstant                   |
|                                     |
|o1 = EulerConstant                   |
|                                     |
|o1 : Constant                        |
+-------------------------------------+
|i2 : +EulerConstant                  |
|                                     |
|o2 = .5772156649015329               |
|                                     |
|o2 : RR (of precision 53)            |
+-------------------------------------+
|i3 : EulerConstant+100p100           |
|                                     |
|o3 = 100.5772156649015328606065120901|
|                                     |
|o3 : RR (of precision 100)           |
+-------------------------------------+

See Euler-Mascheroni constant (see
https://en.wikipedia.org/wiki/Euler-Mascheroni_constant ).

For the programmer
==================

The object EulerConstant, is an instance of the type
Constant.

even -- tell whether an integer is even
***************************************

Description
===========

even x -- returns true or false, tells whether x is an even integer.

See also odd.

For the programmer
==================

The object even, is a function closure.

exchange -- exchange the value of an atomic integer
***************************************************

Synopsis
========

  * Usage:
        exchange(x, y)
  * Inputs:
      * x, an atomic integer,
      * y, an integer,
  * Outputs:
      * an integer,

Description
===========

The value of y is stored in x and the original value of x is returned.  This
operation occurs atomically and is thread safe.

+----------------------+
|i1 : x = new AtomicInt|
|                      |
|o1 = 0                |
|                      |
|o1 : AtomicInt        |
+----------------------+
|i2 : exchange(x, 5)   |
|                      |
|o2 = 0                |
+----------------------+
|i3 : x                |
|                      |
|o3 = 5                |
|                      |
|o3 : AtomicInt        |
+----------------------+

Ways to use exchange:
=====================

  * "exchange(AtomicInt,ZZ)"

For the programmer
==================

The object exchange, is a method function.

exp -- exponential function
***************************

Synopsis
========

  * Usage:
        exp x
        exp I
  * Inputs:
      * x, a real number,
      * I, a real interval,
  * Outputs:
      * the exponential of x
      * a real interval, an interval containing the exponentials of
        points of I

Description
===========

+-----------------------------------------------------------------------------+
|i1 : exp 1p300                                                               |
|                                                                             |
|o1 = 2.7182818284590452353602874713526624977572470936999595749669676277240766|
|     30353547594571382179                                                    |
|                                                                             |
|o1 : RR (of precision 300)                                                   |
+-----------------------------------------------------------------------------+
|i2 : exp(pi*ii)                                                              |
|                                                                             |
|o2 = -1+1.224646799147353e-16*ii                                             |
|                                                                             |
|o2 : CC (of precision 53)                                                    |
+-----------------------------------------------------------------------------+

Ways to use exp:
================

  * "exp(CC)"
  * "exp(RR)"
  * "exp(RRi)"
  * exp(RingElement)

For the programmer
==================

The object exp, is a method function.

exp(RingElement)
****************

Synopsis
========

  * Function: exp,
  * Usage:
        exp x
  * Inputs:
      * x
  * Outputs:
      * the exponential of x, provided x is nilpotent, and the denominators
        required have reciprocals in the ring of x.

Description
===========

+-----------------------------------------------------+
|i1 : R = ZZ/11[x]/x^9                                |
|                                                     |
|o1 = R                                               |
|                                                     |
|o1 : QuotientRing                                    |
+-----------------------------------------------------+
|i2 : exp x                                           |
|                                                     |
|         8     7     6    5     4     3     2        |
|o2 = - 2x  - 5x  - 2x  - x  - 5x  + 2x  - 5x  + x + 1|
|                                                     |
|o2 : R                                               |
+-----------------------------------------------------+

Ways to use this method:
========================

  * exp(RingElement)

expm1 -- exponential minus 1
****************************

Synopsis
========

  * Usage:
        expm1 x
        expm1 I
  * Inputs:
      * x, a complex number, or a real number,
      * I, a real interval,
  * Outputs:
      * a real number, or a complex number, the quantity
        exp(x)-1
      * a real interval, an interval containing the exponential of
        the points of I minus one

Description
===========

+-----------------------------------------+
|i1 : expm1 1p100e-10                     |
|                                         |
|o1 = 1.000000000050000000001666666667e-10|
|                                         |
|o1 : RR (of precision 100)               |
+-----------------------------------------+
|i2 : exp(1p100e-10)-1                    |
|                                         |
|o2 = 1.000000000050000000009375867883e-10|
|                                         |
|o2 : RR (of precision 100)               |
+-----------------------------------------+

Ways to use expm1:
==================

  * "expm1(CC)"
  * "expm1(RR)"
  * "expm1(RRi)"
  * expm1(RingElement) (missing documentation)

For the programmer
==================

The object expm1, is a method function.

exponents -- the exponents of a polynomial
******************************************

Synopsis
========

  * Usage:
        exponents m
  * Inputs:
      * m, a ring element, or a monoid element,
        a monomial
  * Outputs:
      * a list, for a monomial, provides the list of exponents;
        for a polynomial, provides a list whose elements are the lists of
        exponents of the terms of f

Description
===========

+--------------------------------------------------+
|i1 : R = ZZ/101[x,y,z];                           |
+--------------------------------------------------+
|i2 : exponents (f = x^2 - 7 + x*y*z^11 + y)       |
|                                                  |
|o2 = {{1, 1, 11}, {2, 0, 0}, {0, 1, 0}, {0, 0, 0}}|
|                                                  |
|o2 : List                                         |
+--------------------------------------------------+
|i3 : leadMonomial f                               |
|                                                  |
|          11                                      |
|o3 = x*y*z                                        |
|                                                  |
|o3 : R                                            |
+--------------------------------------------------+
|i4 : exponents leadMonomial f                     |
|                                                  |
|o4 = {{1, 1, 11}}                                 |
|                                                  |
|o4 : List                                         |
+--------------------------------------------------+

Code
====

../../../../../Macaulay2/m2/monoids.m2:142:27-142:50: --source code:
exponents RingElement   := f -> first \ listForm f

See also
========

  * content -- the content of a polynomial
  * coefficients -- monomials and their coefficients
  * listForm -- convert to list form
  * standardForm -- convert to standard form
  * monomials -- matrix of monomials in a ring element or
    matrix

Ways to use exponents:
======================

  * "exponents(MonoidElement)"
  * "exponents(RingElement)"

For the programmer
==================

The object exponents, is a method function.

Expression -- the class of all expressions
******************************************

Description
===========

An expression is a symbolic representation of a mathematical expression.  It
retains some of the semantics of the mathematical expression, as well as enough
information to print the expression nicely.  In Macaulay2 expressions have two
main functions: they are an intermediate phase in the conversion of a
mathematical object to a net, that can be printed; and they are a
way of holding and displaying a mathematical expression in an unevaluated form
that can be both printed and evaluated.

Internally, each expression is a basic list whose elements may also be
expressions.  The elements that are not expressions are interpreted as
themselves, and may be strings, symbols, numbers, etc.  There are several types
of expression that correspond to various sorts of mathematical entities, such
as sums of class Sum, products, of class Product,
fractions of class Divide, etc.

Expressions are produced with the function expression.  The
various methods installed for it try to bring as much of the semantic structure
of the mathematical object to light.  The following examples illustrate that,
using peek, and peek', to display the internal
structure.
+-----------------------------------------------------------------------------+
|i1 : expression 4                                                            |
|                                                                             |
|o1 = 4                                                                       |
|                                                                             |
|o1 : Expression of class Holder                                              |
+-----------------------------------------------------------------------------+
|i2 : peek oo                                                                 |
|                                                                             |
|o2 = Holder{4}                                                               |
+-----------------------------------------------------------------------------+
|i3 : d = expression (-4)                                                     |
|                                                                             |
|o3 = -4                                                                      |
|                                                                             |
|o3 : Expression of class Minus                                               |
+-----------------------------------------------------------------------------+
|i4 : peek oo                                                                 |
|                                                                             |
|o4 = Minus{4}                                                                |
+-----------------------------------------------------------------------------+
|i5 : QQ[x];                                                                  |
+-----------------------------------------------------------------------------+
|i6 : f = (x+1)^5                                                             |
|                                                                             |
|      5     4      3      2                                                  |
|o6 = x  + 5x  + 10x  + 10x  + 5x + 1                                         |
|                                                                             |
|o6 : QQ[x]                                                                   |
+-----------------------------------------------------------------------------+
|i7 : peek f                                                                  |
|                                                                             |
|o7 = QQ[x]{x5+5x4+10x3+10x2+5x+1}                                            |
+-----------------------------------------------------------------------------+
|i8 : e = expression f                                                        |
|                                                                             |
|      5     4      3      2                                                  |
|o8 = x  + 5x  + 10x  + 10x  + 5x + 1                                         |
|                                                                             |
|o8 : Expression of class Sum                                                 |
+-----------------------------------------------------------------------------+
|i9 : peek e                                                                  |
|                                                                             |
|          5    4     3     2                                                 |
|o9 = Sum{x , 5x , 10x , 10x , 5x, 1}                                         |
+-----------------------------------------------------------------------------+
|i10 : peek'_2 e                                                              |
|                                                                             |
|                                   4                3                2       |
|o10 = Sum{Power{x, 5}, Product{5, x }, Product{10, x }, Product{10, x },     |
|      -----------------------------------------------------------------------|
|      Product{5, x}, OneExpression{1}}                                       |
+-----------------------------------------------------------------------------+
|i11 : peek'_11 e                                                             |
|                                                                             |
|o11 = Sum{Power{x, 5}, Product{5, Power{x, 4}}, Product{10, Power{x, 3}},    |
|      -----------------------------------------------------------------------|
|      Product{10, Power{x, 2}}, Product{5, x}, OneExpression{1}}             |
+-----------------------------------------------------------------------------+
The function factor, returns an expression.
+---------------------------------+
|i12 : c = factor f               |
|                                 |
|             5                   |
|o12 = (x + 1)                    |
|                                 |
|o12 : Expression of class Product|
+---------------------------------+
|i13 : peek'_2 c                  |
|                                 |
|o13 = Product{Power{x + 1, 5}}   |
+---------------------------------+
|i14 : factor 240012              |
|                                 |
|       2 2                       |
|o14 = 2 3 59*113                 |
|                                 |
|o14 : Expression of class Product|
+---------------------------------+
Expressions can be evaluated using value.
+-------------------------------------+
|i15 : value e                        |
|                                     |
|       5     4      3      2         |
|o15 = x  + 5x  + 10x  + 10x  + 5x + 1|
|                                     |
|o15 : QQ[x]                          |
+-------------------------------------+
|i16 : value e == f                   |
|                                     |
|o16 = true                           |
+-------------------------------------+
|i17 : value c                        |
|                                     |
|       5     4      3      2         |
|o17 = x  + 5x  + 10x  + 10x  + 5x + 1|
|                                     |
|o17 : QQ[x]                          |
+-------------------------------------+
The following operators can be applied to expressions: SPACE,
*, **, +, -, /,
==, ^, and _.  They are contagious, in the sense
that when applied to an expression and a non-expression, the non-expression
will be converted to an expression and the operator will be applied.  Only the
most trivial algebraic simplifications are applied.
+-------------------------------------------+
|i18 : d + e                                |
|                                           |
|             5     4      3      2         |
|o18 = - 4 + x  + 5x  + 10x  + 10x  + 5x + 1|
|                                           |
|o18 : Expression of class Sum              |
+-------------------------------------------+
|i19 : d + 4                                |
|                                           |
|o19 = - 4 + 4                              |
|                                           |
|o19 : Expression of class Sum              |
+-------------------------------------------+
|i20 : d / 4                                |
|                                           |
|      -4                                   |
|o20 = --                                   |
|       4                                   |
|                                           |
|o20 : Expression of class Divide           |
+-------------------------------------------+
|i21 : d / 1                                |
|                                           |
|o21 = -4                                   |
|                                           |
|o21 : Expression of class Minus            |
+-------------------------------------------+
|i22 : d == e                               |
|                                           |
|             5     4      3      2         |
|o22 = -4 == x  + 5x  + 10x  + 10x  + 5x + 1|
|                                           |
|o22 : Expression of class Equation         |
+-------------------------------------------+

Types of expression:
====================

  * Adjacent -- the class of all adjacent expression pairs
  * AssociativeExpression -- the class of
    associative expressions
  * BinaryOperation -- the class of all binary
    operation expressions
  * Divide -- the class of all divide expressions
  * FunctionApplication -- the class of all
    function application expressions
  * Holder -- the class of all holder expressions
  * MapExpression -- the class of map expressions
  * MatrixExpression -- the class of all matrix
    expressions
  * Minus -- the class of all minus expressions
  * Power -- the class of all power expressions
  * RowExpression -- the class of all matrix expressions
  * SheafExpression (Varieties) -- the class of sheaf
    expressions
  * SparseMonomialVectorExpression, --
    the class of all sparse monomial vector expressions
  * SparseVectorExpression -- the class of all
    sparse vector expressions
  * Subscript -- the class of all subscript expressions
  * Superscript -- the class of all superscript expressions
  * Table -- the class of all table expressions
  * VectorExpression -- the class of all vector
    expressions

Functions and methods returning an expression:
==============================================

  * expression -- convert to an expression
  * hold -- hold something in a holder expression

Methods that use an expression:
===============================

  * "assert(Expression)" -- see assert, -- check whether
    something is true, raise an error if not
  * "value(Expression)"

For the programmer
==================

The object Expression, is a type, with ancestor
classes BasicList, < Thing.

expression -- convert to an expression
**************************************

Synopsis
========

  * Usage:
        expression x
  * Inputs:
      * x
  * Outputs:
      * an expression,  constructed from x using the
        mathematical structure of x, if present

Description
===========

Here is example of a function that expresses small rational numbers as Egyptian
fractions using expression.
+------------------------------------------------+
|i1 : egyptian = method();                       |
+------------------------------------------------+
|i2 : egyptian QQ := x -> if x == 0 then 0 else (|
|          n := ceiling(1/x);                    |
|          expression(1/n) + egyptian(x - 1/n)); |
+------------------------------------------------+
|i3 : egyptian(30/31)                            |
|                                                |
|     1   1   1    1      1         1            |
|o3 = - + - + - + --- + ----- + ---------        |
|     2   3   8   107   15922   633759288        |
|                                                |
|o3 : Expression of class Sum                    |
+------------------------------------------------+

For the programmer
==================

The object expression, is a method function with a single argument.

Ext -- compute an Ext module
****************************

Ways to use Ext:
================

  * "Ext(Ideal,Ideal)" -- see Ext(Module,Module),
    -- total Ext module
  * "Ext(Ideal,Module)" -- see Ext(Module,Module),
    -- total Ext module
  * "Ext(Ideal,Ring)" -- see Ext(Module,Module),
    -- total Ext module
  * "Ext(Module,Ideal)" -- see Ext(Module,Module),
    -- total Ext module
  * Ext(Module,Module) -- total Ext module
  * "Ext(Module,Ring)" -- see Ext(Module,Module),
    -- total Ext module
  * Ext(Ring,Ideal) (missing documentation)
  * Ext(Ring,Module) (missing documentation)
  * Ext(Ring,Ring) (missing documentation)
  * Ext^ZZ(CoherentSheaf,CoherentSheaf) (Varieties)
    -- global Ext
  * "Ext^ZZ(CoherentSheaf,SheafOfRings)" -- see
    Ext^ZZ(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Ext
  * "Ext^ZZ(SheafOfRings,CoherentSheaf)" -- see
    Ext^ZZ(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Ext
  * "Ext^ZZ(SheafOfRings,SheafOfRings)" -- see
    Ext^ZZ(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Ext
  * Ext^ZZ(CoherentSheaf,SheafMap) (missing documentation)
  * Ext^ZZ(CoherentSheaf,SumOfTwists) (Varieties)
    -- global Ext
  * "Ext^ZZ(SheafOfRings,SumOfTwists)" -- see
    Ext^ZZ(CoherentSheaf,SumOfTwists) (Varieties),
    -- global Ext
  * "Ext^ZZ(Matrix,Ideal)" -- see Ext^ZZ(Matrix,Module),
    -- map between Ext modules
  * Ext^ZZ(Matrix,Module) -- map between
    Ext modules
  * "Ext^ZZ(Matrix,Ring)" -- see Ext^ZZ(Matrix,Module),
    -- map between Ext modules
  * "Ext^ZZ(Ideal,Matrix)" -- see Ext^ZZ(Module,Matrix),
    -- map between Ext modules
  * Ext^ZZ(Module,Matrix) -- map between
    Ext modules
  * "Ext^ZZ(Ideal,Ideal)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * "Ext^ZZ(Ideal,Module)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * "Ext^ZZ(Ideal,Ring)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * "Ext^ZZ(Module,Ideal)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * Ext^ZZ(Module,Module) -- Ext module
  * "Ext^ZZ(Module,Ring)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * Ext^ZZ(Ring,Ideal) (missing documentation)
  * Ext^ZZ(Ring,Matrix) (missing documentation)
  * Ext^ZZ(Ring,Module) (missing documentation)
  * Ext^ZZ(Ring,Ring) (missing documentation)

For the programmer
==================

The object Ext, is a scripted functor.

Ext(Module,Module) -- total Ext module
**************************************

Synopsis
========

  * Scripted functor: Ext,
  * Usage:
        Ext(M,N)
  * Inputs:
      * M, an ideal, or a ring,
      * N, an ideal, or a ring,
  * Outputs:
      * the $Ext$ module of $M$ and $N$, as a multigraded module, with the
        modules $Ext^i(M,N)$ for all values of $i$ appearing simultaneously.

Description
===========

The modules M and N should be graded (homogeneous) modules over the same ring.

If M or N is an ideal or ring, it is regarded as a module in the evident way.

The computation of the total Ext module is possible for modules over the ring
$R$ of a complete intersection, according the algorithm of
Shamash-Eisenbud-Avramov-Buchweitz.  The result is provided as a finitely
presented module over a new ring with one additional variable of degree {-2,-d}
for each equation of degree d defining $R$.  The variables in this new ring
have degree length 1 more than the degree length of the original ring, i.e., is
multigraded, with the degree d part of $Ext^n(M,N)$ appearing as the degree
prepend(-n,d) part of Ext(M,N).  We illustrate this in the following example.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y]/(x^3,y^2);                                                  |
+-----------------------------------------------------------------------------+
|i2 : N = cokernel matrix {{x^2, x*y}}                                        |
|                                                                             |
|o2 = cokernel | x2 xy |                                                      |
|                                                                             |
|                            1                                                |
|o2 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i3 : H = Ext(N,N);                                                           |
+-----------------------------------------------------------------------------+
|i4 : ring H                                                                  |
|                                                                             |
|o4 = QQ[X ..X , x..y]                                                        |
|         1   2                                                               |
|                                                                             |
|o4 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i5 : S = ring H;                                                             |
+-----------------------------------------------------------------------------+
|i6 : H                                                                       |
|                                                                             |
|o6 = cokernel {0, 0}   | y2 xy x2 0 0 0 0 0 0 0 0 X_1y X_1x 0   0   0 0 |    |
|              {-1, -1} | 0  0  0  y x 0 0 0 0 0 0 0    0    X_1 0   0 0 |    |
|              {-1, -1} | 0  0  0  0 0 y x 0 0 0 0 0    0    0   X_1 0 0 |    |
|              {-1, -1} | 0  0  0  0 0 0 0 y x 0 0 0    0    0   X_1 0 0 |    |
|              {-1, -1} | 0  0  0  0 0 0 0 0 0 y x 0    0    0   0   0 0 |    |
|              {-2, -2} | 0  0  0  0 0 0 0 0 0 0 0 0    0    0   0   y x |    |
|                                                                             |
|                            6                                                |
|o6 : S-module, quotient of S                                                 |
+-----------------------------------------------------------------------------+
|i7 : isHomogeneous H                                                         |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+
|i8 : rank source basis( { -2,-3 }, H)                                        |
|                                                                             |
|o8 = 1                                                                       |
+-----------------------------------------------------------------------------+
|i9 : rank source basis( { -3 }, Ext^2(N,N) )                                 |
|                                                                             |
|o9 = 1                                                                       |
+-----------------------------------------------------------------------------+
|i10 : rank source basis( { -4,-5 }, H)                                       |
|                                                                             |
|o10 = 4                                                                      |
+-----------------------------------------------------------------------------+
|i11 : rank source basis( { -5 }, Ext^4(N,N) )                                |
|                                                                             |
|o11 = 4                                                                      |
+-----------------------------------------------------------------------------+
|i12 : hilbertSeries H                                                        |
|                                                                             |
|            -1 -1     2     -1    -2 -2     3     -1       -2 -1     -3 -3   |
|      1 + 4T  T   - 3T  - 8T   + T  T   + 2T  + 4T  T  - 4T  T   - 2T  T   + |
|            0  1      1     0     0  1      1     0  1     0  1      0  1    |
|o12 = -----------------------------------------------------------------------|
|                                                -2 -2       -2 -3         2  |
|                                          (1 - T  T  )(1 - T  T  )(1 - T )   |
|                                                0  1        0  1        1    |
|                                                                             |
|o12 : Expression of class Divide                                             |
|-----------------------------------------------------------------------------|
|  -2     -3 -2     -2       -3 -1                                            |
|5T   + 4T  T   - 2T  T  - 2T  T                                              |
|  0      0  1      0  1     0  1                                             |
|---------------------------------                                            |
+-----------------------------------------------------------------------------+
|i13 : hilbertSeries(H,Order=>11)                                             |
|                                                                             |
|                  -1 -1    -2 -3     -2 -2     -3 -4    -4 -6     -3 -3      |
|o13 = 1 + 2T  + 4T  T   + T  T   + 4T  T   + 4T  T   + T  T   + 2T  T   +    |
|            1     0  1     0  1      0  1      0  1     0  1      0  1       |
|      -----------------------------------------------------------------------|
|        -4 -5     -5 -7    -6 -9     -4 -4     -5 -6     -6 -8     -7 -10    |
|      4T  T   + 4T  T   + T  T   + 2T  T   + 2T  T   + 4T  T   + 4T  T    +  |
|        0  1      0  1     0  1      0  1      0  1      0  1      0  1      |
|      -----------------------------------------------------------------------|
|       -8 -12     -5 -5     -6 -7     -7 -9     -8 -11     -9 -13    -10 -15 |
|      T  T    + 2T  T   + 2T  T   + 2T  T   + 4T  T    + 4T  T    + T   T    |
|       0  1       0  1      0  1      0  1      0  1       0  1      0   1   |
|      -----------------------------------------------------------------------|
|          -6 -6     -7 -8     -8 -10     -9 -12     -10 -14     -11 -16      |
|      + 2T  T   + 2T  T   + 2T  T    + 2T  T    + 4T   T    + 4T   T    +    |
|          0  1      0  1      0  1       0  1       0   1       0   1        |
|      -----------------------------------------------------------------------|
|       -12 -18     -7 -7     -8 -9     -9 -11     -10 -13     -11 -15        |
|      T   T    + 2T  T   + 2T  T   + 2T  T    + 2T   T    + 2T   T    +      |
|       0   1       0  1      0  1      0  1       0   1       0   1          |
|      -----------------------------------------------------------------------|
|        -12 -17     -13 -19    -14 -21     -8 -8     -9 -10     -10 -12      |
|      4T   T    + 4T   T    + T   T    + 2T  T   + 2T  T    + 2T   T    +    |
|        0   1       0   1      0   1       0  1      0  1       0   1        |
|      -----------------------------------------------------------------------|
|        -11 -14     -12 -16     -13 -18     -14 -20     -15 -22    -16 -24   |
|      2T   T    + 2T   T    + 2T   T    + 4T   T    + 4T   T    + T   T    + |
|        0   1       0   1       0   1       0   1       0   1      0   1     |
|      -----------------------------------------------------------------------|
|        -9 -9     -10 -11     -11 -13     -12 -15     -13 -17     -14 -19    |
|      2T  T   + 2T   T    + 2T   T    + 2T   T    + 2T   T    + 2T   T    +  |
|        0  1      0   1       0   1       0   1       0   1       0   1      |
|      -----------------------------------------------------------------------|
|        -15 -21     -16 -23     -17 -25    -18 -27     -10 -10     -11 -12   |
|      2T   T    + 4T   T    + 4T   T    + T   T    + 2T   T    + 2T   T    + |
|        0   1       0   1       0   1      0   1       0   1       0   1     |
|      -----------------------------------------------------------------------|
|        -12 -14     -13 -16     -14 -18     -15 -20     -16 -22     -17 -24  |
|      2T   T    + 2T   T    + 2T   T    + 2T   T    + 2T   T    + 2T   T    +|
|        0   1       0   1       0   1       0   1       0   1       0   1    |
|      -----------------------------------------------------------------------|
|        -18 -26     -19 -28    -20 -30                                       |
|      4T   T    + 4T   T    + T   T                                          |
|        0   1       0   1      0   1                                         |
|                                                                             |
|o13 : ZZ[T ..T ]                                                             |
|          0   1                                                              |
+-----------------------------------------------------------------------------+

The result of the computation is cached for future reference.

Ways to use this method:
========================

  * "Ext(Ideal,Ideal)"
  * "Ext(Ideal,Module)"
  * "Ext(Ideal,Ring)"
  * "Ext(Module,Ideal)"
  * Ext(Module,Module) -- total Ext module
  * "Ext(Module,Ring)"

Ext^ZZ(Matrix,Module) -- map between Ext modules
************************************************

Synopsis
========

  * Scripted functor: Ext,
  * Usage:
        Ext^i(f,N)
  * Inputs:
      * i
      * f, M1 --> M2
      * N
  * Outputs:
      * a matrix, the map $Ext^i(M2,N) \rightarrow{}
        Ext^i(M1,N)$

Description
===========

If N is an ideal or ring, it is regarded as a module in the evident way.
+-------------------------------------------------------+
|i1 : R = ZZ/32003[a..d];                               |
+-------------------------------------------------------+
|i2 : I = monomialCurveIdeal(R,{1,3,4})                 |
|                                                       |
|                        3      2     2    2    3    2  |
|o2 = ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c)|
|                                                       |
|o2 : Ideal of R                                        |
+-------------------------------------------------------+
|i3 : M1 = R^1/I                                        |
|                                                       |
|o3 = cokernel | bc-ad c3-bd2 ac2-b2d b3-a2c |          |
|                                                       |
|                            1                          |
|o3 : R-module, quotient of R                           |
+-------------------------------------------------------+
|i4 : M2 = R^1/ideal(I_0,I_1)                           |
|                                                       |
|o4 = cokernel | bc-ad c3-bd2 |                         |
|                                                       |
|                            1                          |
|o4 : R-module, quotient of R                           |
+-------------------------------------------------------+
|i5 : f = inducedMap(M1,M2)                             |
|                                                       |
|o5 = | 1 |                                             |
|                                                       |
|o5 : Matrix M1 <-- M2                                  |
+-------------------------------------------------------+
|i6 : Ext^1(f,R)                                        |
|                                                       |
|o6 = 0                                                 |
|                                                       |
|o6 : Matrix 0 <-- 0                                    |
+-------------------------------------------------------+
|i7 : g = Ext^2(f,R)                                    |
|                                                       |
|o7 = {-5} | -d2 -cd c2 |                               |
|                                                       |
|o7 : Matrix                                            |
+-------------------------------------------------------+
|i8 : source g == Ext^2(M1,R)                           |
|                                                       |
|o8 = false                                             |
+-------------------------------------------------------+
|i9 : target g == Ext^2(M2,R)                           |
|                                                       |
|o9 = true                                              |
+-------------------------------------------------------+
|i10 : Ext^3(f,R)                                       |
|                                                       |
|o10 = 0                                                |
|                                                       |
|o10 : Matrix                                           |
+-------------------------------------------------------+

See also
========

  * resolution -- projective resolution
  * Tor -- Tor module
  * Hom -- module of homomorphisms
  * Ext^ZZ(Module,Module) -- Ext module

Ways to use this method:
========================

  * "Ext^ZZ(Matrix,Ideal)"
  * Ext^ZZ(Matrix,Module) -- map between
    Ext modules
  * "Ext^ZZ(Matrix,Ring)"

Ext^ZZ(Module,Matrix) -- map between Ext modules
************************************************

Synopsis
========

  * Scripted functor: Ext,
  * Usage:
        Ext^i(M,f)
  * Inputs:
      * i
      * M
      * f, N1 --> N2
  * Outputs:
      * a matrix, the induced map $Ext^i(M,N1) \rightarrow{}
        Ext^i(M,N2)$

Description
===========

If M is an ideal, it is regarded as a module in the evident way.

See also
========

  * resolution -- projective resolution
  * Tor -- Tor module
  * Hom -- module of homomorphisms
  * Ext^ZZ(Module,Module) -- Ext module
  * Ext^ZZ(Matrix,Module) -- map between
    Ext modules

Ways to use this method:
========================

  * "Ext^ZZ(Ideal,Matrix)"
  * Ext^ZZ(Module,Matrix) -- map between
    Ext modules

Ext^ZZ(Module,Module) -- Ext module
***********************************

Synopsis
========

  * Scripted functor: Ext,
  * Usage:
        Ext^i(M,N)
  * Inputs:
      * i
      * M
      * N
  * Outputs:
      * the i-th Ext module of M and N

Description
===========

If M or N is an ideal or ring, it is regarded as a module in the evident way.
+---------------------------------------------------------------+
|i1 : R = ZZ/32003[a..d];                                       |
+---------------------------------------------------------------+
|i2 : I = monomialCurveIdeal(R,{1,3,4})                         |
|                                                               |
|                        3      2     2    2    3    2          |
|o2 = ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c)        |
|                                                               |
|o2 : Ideal of R                                                |
+---------------------------------------------------------------+
|i3 : M = R^1/I                                                 |
|                                                               |
|o3 = cokernel | bc-ad c3-bd2 ac2-b2d b3-a2c |                  |
|                                                               |
|                            1                                  |
|o3 : R-module, quotient of R                                   |
+---------------------------------------------------------------+
|i4 : Ext^1(M,R)                                                |
|                                                               |
|o4 = subquotient ({-2} | bc-ad   |, {-2} | bc-ad   |)          |
|                  {-3} | b3-a2c  |  {-3} | b3-a2c  |           |
|                  {-3} | ac2-b2d |  {-3} | ac2-b2d |           |
|                  {-3} | c3-bd2  |  {-3} | c3-bd2  |           |
|                                                               |
|                               4                               |
|o4 : R-module, subquotient of R                                |
+---------------------------------------------------------------+
|i5 : Ext^2(M,R)                                                |
|                                                               |
|o5 = subquotient ({-4} | c b 0  a  0 0 |, {-4} | -b2 c a  0 |) |
|                  {-4} | d 0 b  0  a 0 |  {-4} | -ac d b  0 |  |
|                  {-4} | 0 d -c 0  0 a |  {-4} | -bd 0 -c a |  |
|                  {-4} | 0 0 0  -d c b |  {-4} | -c2 0 -d b |  |
|                                                               |
|                               4                               |
|o5 : R-module, subquotient of R                                |
+---------------------------------------------------------------+
|i6 : Ext^3(M,R)                                                |
|                                                               |
|o6 = cokernel {-5} | d -c -b a |                               |
|                                                               |
|                            1                                  |
|o6 : R-module, quotient of R                                   |
+---------------------------------------------------------------+
|i7 : Ext^1(I,R)                                                |
|                                                               |
|o7 = subquotient ({-4} | c a  0 b 0  0 |, {-4} | b2 0  -a -c |)|
|                  {-4} | d 0  a 0 b  0 |  {-4} | ac 0  -b -d | |
|                  {-4} | 0 -d c 0 0  b |  {-4} | c2 -b d  0  | |
|                  {-4} | 0 0  0 d -c a |  {-4} | bd -a c  0  | |
|                                                               |
|                               4                               |
|o7 : R-module, subquotient of R                                |
+---------------------------------------------------------------+
As an efficiency consideration, it is generally much more efficient to compute
Ext^i(R^1/I,N) rather than Ext^(i-1)(I,N).  The latter first computes a
presentation of the ideal I, and then a free resolution of that.  For many
examples, the difference in time and space required can be very large.

See also
========

  * resolution -- projective resolution
  * Tor -- Tor module
  * Hom -- module of homomorphisms
  * monomialCurveIdeal -- make the ideal of a
    monomial curve
  * Ext^ZZ(Matrix,Module) -- map between
    Ext modules
  * Ext^ZZ(Module,Matrix) -- map between
    Ext modules

Ways to use this method:
========================

  * "Ext^ZZ(Ideal,Ideal)"
  * "Ext^ZZ(Ideal,Module)"
  * "Ext^ZZ(Ideal,Ring)"
  * "Ext^ZZ(Module,Ideal)"
  * Ext^ZZ(Module,Module) -- Ext module
  * "Ext^ZZ(Module,Ring)"

extend -- extend a module map to a chain map, if possible
*********************************************************

Ways to use extend:
===================

  * extend(ChainComplex,ChainComplex,Matrix)
    -- extend a module map to
    a chain map, if possible

For the programmer
==================

The object extend, is a method function with options.

extend(ChainComplex,ChainComplex,Matrix) -- extend a module map to a chain map, if possible
*******************************************************************************************

Synopsis
========

  * Function: extend,
  * Usage:
        extend(D,C,f0)
  * Inputs:
      * D
      * C
      * f0, a map from C_0 to D_0
  * Optional inputs,:
      * Verify => a Boolean value, default value true, whether
        to check that the map extends
  * Outputs:
      * a chain complex map f: D <--- C of degree 0 extending f0 in the sense
        that f_0==f0

Description
===========

+------------------------------------------------------------------+
|i1 : R = ZZ/101[a..c]                                             |
|                                                                  |
|o1 = R                                                            |
|                                                                  |
|o1 : PolynomialRing                                               |
+------------------------------------------------------------------+
|i2 : I = image vars R                                             |
|                                                                  |
|o2 = image | a b c |                                              |
|                                                                  |
|                             1                                    |
|o2 : R-module, submodule of R                                     |
+------------------------------------------------------------------+
|i3 : J = image symmetricPower (2,vars R)                          |
|                                                                  |
|o3 = image | a2 ab ac b2 bc c2 |                                  |
|                                                                  |
|                             1                                    |
|o3 : R-module, submodule of R                                     |
+------------------------------------------------------------------+
|i4 : g = extend( resolution (R^1/I), resolution (R^1/J), id_(R^1))|
|                                                                  |
|          1             1                                         |
|o4 = 0 : R  <--------- R  : 0                                     |
|               | 1 |                                              |
|                                                                  |
|          3                           6                           |
|     1 : R  <----------------------- R  : 1                       |
|               {1} | a b 0 0 0 0 |                                |
|               {1} | 0 0 b 0 0 0 |                                |
|               {1} | 0 0 0 a b c |                                |
|                                                                  |
|          3                               8                       |
|     2 : R  <--------------------------- R  : 2                   |
|               {2} | 0 b 0 0 0 0 0 0 |                            |
|               {2} | 0 0 a b 0 0 0 0 |                            |
|               {2} | 0 0 0 0 0 b 0 0 |                            |
|                                                                  |
|          1                     3                                 |
|     3 : R  <----------------- R  : 3                             |
|               {3} | 0 b 0 |                                      |
|                                                                  |
|     4 : 0 <----- 0 : 4                                           |
|              0                                                   |
|                                                                  |
|o4 : ChainComplexMap                                              |
+------------------------------------------------------------------+
|i5 : g_1                                                          |
|                                                                  |
|o5 = {1} | a b 0 0 0 0 |                                          |
|     {1} | 0 0 b 0 0 0 |                                          |
|     {1} | 0 0 0 a b c |                                          |
|                                                                  |
|             3      6                                             |
|o5 : Matrix R  <-- R                                              |
+------------------------------------------------------------------+
|i6 : g_2                                                          |
|                                                                  |
|o6 = {2} | 0 b 0 0 0 0 0 0 |                                      |
|     {2} | 0 0 a b 0 0 0 0 |                                      |
|     {2} | 0 0 0 0 0 b 0 0 |                                      |
|                                                                  |
|             3      8                                             |
|o6 : Matrix R  <-- R                                              |
+------------------------------------------------------------------+

See also
========

  * ChainComplex _ ZZ -- component
  * ChainComplexMap _ ZZ -- component map
  * cone(ChainComplexMap)

Ways to use this method:
========================

  * extend(ChainComplex,ChainComplex,Matrix)
    -- extend a module map to
    a chain map, if possible

exteriorPower -- exterior power
*******************************

See also
========

  * minors -- ideal generated by minors
  * determinant -- determinant of a matrix
  * wedgeProduct -- the exterior
    multiplication map

Ways to use exteriorPower:
==========================

  * exteriorPower(ZZ,CoherentSheaf) (Varieties)
  * exteriorPower(ZZ,Matrix) -- exterior
    power of a matrix
  * exteriorPower(ZZ,Module) -- exterior
    power of a module

For the programmer
==================

The object exteriorPower, is a method function with options.

exteriorPower(...,Strategy=>...) -- choose between Bareiss, Cofactor and Dynamic algorithms
*******************************************************************************************

Synopsis
========

  * Usage:
        exteriorPower(M, Strategy => s)
  * Inputs:
      * M, a matrix,
      * s, a symbol, either Bareiss, Cofactor, or Dynamic
  * Consequences:
      * If s is Bareiss, then the Bareiss algorithm is used; if
        s is Cofactor, then cofactor expansion is used; if s
        is Dynamic, then a dynamic programming algorithm is
        used.

Description
===========

The ring, of M determines the default strategy.  If the ring is a
polynomial ring, or a field (as identified by
isField) then the Bareiss, algorithm is used.  If the
ring is a quotient ring, (which has not been declared a
field by toField), then the Cofactor,
algorithm is used.The Dynamic, algorithm implements a variant of
cofactor expansion that caches intermediate results. This strategy introduces
some memory overhead, but can be faster than Cofactor,
especially with sparse matrices of low degree.

Further information
===================

  * Default value: null
  * Function: exteriorPower, -- exterior power
  * Option key: Strategy, -- an optional argument

Caveat
======

The Bareiss, algorithm returns a ring element that may differ
from the actual determinant by a zero divisor in the ring.  Thus, an incorrect
answer may be computed if the ring contains zero divisors.

See also
========

  * determinant -- determinant of a matrix
  * minors -- ideal generated by minors

Functions with optional argument named Strategy:
================================================

  * "addHook(...,Strategy=>...)" -- see addHook, -- add a hook
    function to an object for later processing
  * adjoint(...,Strategy=>...) (missing documentation)
  * "annihilator(...,Strategy=>...)" -- see annihilator (Saturation),
    -- the annihilator ideal
  * "associatedPrimes(...,Strategy=>...)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "basis(...,Strategy=>...)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * canonicalBundle(...,Strategy=>...) (missing documentation)
  * "mingens(...,Strategy=>...)" -- see Complement, -- a
    Strategy option value
  * "trim(...,Strategy=>...)" -- see Complement, -- a
    Strategy option value
  * "compose(Module,Module,Module,Strategy=>...)" -- see compose,
    -- composition as a pairing on Hom-modules
  * cotangentSheaf(...,Strategy=>...) (missing documentation)
  * determinant(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * dual(ChainComplex,Strategy=>...) (missing documentation)
  * dual(Matrix,Strategy=>...) (missing documentation)
  * "dual(MonomialIdeal,List,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...),
  * "dual(MonomialIdeal,RingElement,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...),
  * dual(MonomialIdeal,Strategy=>...)
  * dual(SheafMap,Strategy=>...) (missing documentation)
  * "End(...,Strategy=>...)" -- see End, -- module of endomorphisms
  * exteriorPower(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * "gb(...,Strategy=>...)" -- see gb, -- compute a Gröbner basis
  * gcdLLL(...,Strategy=>...) (missing documentation)
  * "GF(...,Strategy=>...)" -- see GF, -- make a finite field
  * "groebnerBasis(...,Strategy=>...)" -- see groebnerBasis,
    -- Gröbner basis, as a matrix
  * hermite(...,Strategy=>...) (missing documentation)
  * "Hom(...,Strategy=>...)" -- see Hom, -- module of homomorphisms
  * "homomorphism'(...,Strategy=>...)" -- see homomorphism',
    -- get the element of Hom from a homomorphism
  * "hooks(...,Strategy=>...)" -- see hooks, -- list hooks
    attached to a key
  * "idealizer(...,Strategy=>...)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * integralClosure(...,Strategy=>...) (IntegralClosure),
    --
    control the algorithm used
  * "intersect(Ideal,Ideal,Strategy=>...)" -- see intersect(Ideal,Ideal),
    -- compute an intersection of a sequence of
    ideals or modules
  * "intersect(Module,Module,Strategy=>...)" -- see
    intersect(Ideal,Ideal), -- compute an
    intersection of a sequence of ideals or modules
  * "intersectInP(...,Strategy=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "isPrimary(...,Strategy=>...)" -- see isPrimary (PrimaryDecomposition),
    -- determine whether a submodule is
    primary
  * "isPrime(Ideal,Strategy=>...)" -- see isPrime(Ideal) (MinimalPrimes),
    -- whether an ideal is prime
  * LLL(...,Strategy=>...) (LLLBases)
    -- choose among
    different algorithms
  * "localize(...,Strategy=>...)" -- see localize (PrimaryDecomposition),
    -- localize an ideal at a prime ideal
  * "match(...,Strategy=>...)" -- see match, -- regular expression
    matching
  * "decompose(Ideal,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * minors(...,Strategy=>...)
    -- choose between Bareiss,
    Cofactor and Dynamic algorithms
  * "parallelApply(...,Strategy=>...)" -- see parallelApply,
    -- apply a function to each element in parallel
  * "primaryComponent(...,Strategy=>...)" -- see primaryComponent (PrimaryDecomposition),
    -- find a primary component
    corresponding to an associated prime
  * pushForward(...,Strategy=>...) (missing documentation)
  * quotient(...,Strategy=>...) (Saturation)
  * "radical(...,Strategy=>...)" -- see radical (MinimalPrimes),
    -- the radical of an ideal
  * "radicalContainment(...,Strategy=>...)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * "analyticSpread(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "associatedGradedRing(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "distinguished(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isLinearType(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isReduction(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "minimalReduction(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "multiplicity(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(Ideal,RingElement,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(Ideal,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "reesAlgebra(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * reesIdeal(...,Strategy=>...) (ReesAlgebra)
    -- Choose a
    strategy for the saturation step
  * "specialFiber(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "specialFiberIdeal(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "regSeqInIdeal(...,Strategy=>...)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * resolution(...,Strategy=>...)
  * saturate(...,Strategy=>...) (Saturation)
  * sheafHom(...,Strategy=>...) (missing documentation)
  * "primaryDecomposition(...,Strategy=>...)" -- see strategies for computing primary decomposition (PrimaryDecomposition),
  * "syz(...,Strategy=>...)" -- see syz(Matrix), --
    compute the syzygy matrix
  * "tangentCone(...,Strategy=>...)" -- see tangentCone(Ideal) (TangentCone),
  * tangentSheaf(...,Strategy=>...) (missing documentation)

exteriorPower(ZZ,Matrix) -- exterior power of a matrix
******************************************************

Synopsis
========

  * Function: exteriorPower,
  * Usage:
        exteriorPower(i,f)
        exteriorPower_i f
  * Inputs:
      * i
      * f
  * Optional inputs,:
      * Strategy, =>
        ..., default value null, choose between Bareiss, Cofactor and Dynamic
        algorithms
  * Outputs:
      * the i-th exterior power of f.

Description
===========

+--------------------------------+
|i1 : R = ZZ/2[x,y];             |
+--------------------------------+
|i2 : f = random(R^3,R^{3:-1})   |
|                                |
|o2 = | x   y   y   |            |
|     | x+y y   x   |            |
|     | x   x+y x+y |            |
|                                |
|             3      3           |
|o2 : Matrix R  <-- R            |
+--------------------------------+
|i3 : exteriorPower_2 f          |
|                                |
|o3 = | y2       x2+xy+y2 xy+y2 ||
|     | x2       x2       0     ||
|     | x2+xy+y2 y2       x2+y2 ||
|                                |
|             3      3           |
|o3 : Matrix R  <-- R            |
+--------------------------------+
The matrix may be a more general homomorphism of modules.  For example,
+-------------------------------------------------------------+
|i4 : g = map(coker matrix {{x^2},{x*y},{y^2}}, R^3, id_(R^3))|
|                                                             |
|o4 = | 1 0 0 |                                               |
|     | 0 1 0 |                                               |
|     | 0 0 1 |                                               |
|                                                             |
|o4 : Matrix                                                  |
+-------------------------------------------------------------+
|i5 : g2 = exteriorPower(2,g)                                 |
|                                                             |
|o5 = | 1 0 0 |                                               |
|     | 0 1 0 |                                               |
|     | 0 0 1 |                                               |
|                                                             |
|o5 : Matrix                                                  |
+-------------------------------------------------------------+
|i6 : target g2                                               |
|                                                             |
|o6 = cokernel | xy x2 0  |                                   |
|              | y2 0  x2 |                                   |
|              | 0  y2 xy |                                   |
|                                                             |
|                            3                                |
|o6 : R-module, quotient of R                                 |
+-------------------------------------------------------------+

See also
========

  * exteriorPower(ZZ,Module) -- exterior
    power of a module

Ways to use this method:
========================

  * exteriorPower(ZZ,Matrix) -- exterior
    power of a matrix

exteriorPower(ZZ,Module) -- exterior power of a module
******************************************************

Synopsis
========

  * Function: exteriorPower,
  * Usage:
        exteriorPower(i,M)
        exteriorPower_i M
  * Inputs:
      * i
      * M
  * Optional inputs,:
      * Strategy, =>
        ..., default value null, choose between Bareiss, Cofactor and Dynamic
        algorithms
  * Outputs:
      * the i-th exterior power of M.

Description
===========

+-----------------------+
|i1 : M = ZZ^5          |
|                       |
|       5               |
|o1 = ZZ                |
|                       |
|o1 : ZZ-module, free   |
+-----------------------+
|i2 : exteriorPower(3,M)|
|                       |
|       10              |
|o2 = ZZ                |
|                       |
|o2 : ZZ-module, free   |
+-----------------------+
When i is 1, then the result is equal to M.  When M is not a free module, then
the generators used for the result will be wedges of the generators of M.  In
other words, the modules cover exteriorPower(i,M) and exteriorPower(i,cover M)
will be equal.

See also
========

  * exteriorPower(ZZ,Matrix) -- exterior
    power of a matrix

Ways to use this method:
========================

  * exteriorPower(ZZ,Module) -- exterior
    power of a module

extracting elements
*******************

If M is an R-module, the best way to think of an element v of M in Macaulay2 is
as a map of the ring into M, mapping 1 to v.

factor -- factor a ring element or a ZZ-module
**********************************************

Description
===========

(Disambiguation: for division of matrices, which can be thought of as factoring
one homomorphism through another, instead see Matrix // Matrix.
For lifting a map between modules to a map between their free
resolutions, see extend.)

Ways to use factor:
===================

  * factor(Module) -- factor a ZZ-module
  * "factor(QQ)" -- see factor(RingElement), --
    factor a ring element
  * factor(RingElement) -- factor a ring
    element
  * "factor(ZZ)" -- see factor(RingElement), --
    factor a ring element

For the programmer
==================

The object factor, is a method function with options.

factor(Module) -- factor a ZZ-module
************************************

Synopsis
========

  * Function: factor,
  * Usage:
        factor M
  * Inputs:
      * M
  * Outputs:
      * a symbolic expression describing the decomposition of M into a direct
        sum of principal modules

Description
===========

The ring of M must be ZZ.

In the following example we construct a module with a known (but disguised)
factorization.
+-----------------------------------------------------------------------------+
|i1 : f = random(ZZ^6, ZZ^4)                                                  |
|                                                                             |
|o1 = | 8 3 8 6 |                                                             |
|     | 1 7 5 8 |                                                             |
|     | 3 8 2 6 |                                                             |
|     | 7 8 3 9 |                                                             |
|     | 8 5 6 3 |                                                             |
|     | 3 7 3 7 |                                                             |
|                                                                             |
|              6       4                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i2 : M = subquotient ( f * diagonalMatrix{2,3,8,21}, f *                     |
|                                                                             |
|o2 = subquotient (| 16 9  64 126 |, | 176 585  0 630 |)                      |
|                  | 2  21 40 168 |  | 22  1365 0 840 |                       |
|                  | 6  24 16 126 |  | 66  1560 0 630 |                       |
|                  | 14 24 24 189 |  | 154 1560 0 945 |                       |
|                  | 16 15 48 63  |  | 176 975  0 315 |                       |
|                  | 6  21 24 147 |  | 66  1365 0 735 |                       |
|                                                                             |
|                                 6                                           |
|o2 : ZZ-module, subquotient of ZZ                                            |
|-----------------------------------------------------------------------------|
|diagonalMatrix{2*11,3*5*13,0,21*5} )                                         |
+-----------------------------------------------------------------------------+
|i3 : factor M                                                                |
|                                                                             |
|          ZZ   ZZ    ZZ                                                      |
|o3 = ZZ + -- + -- + ----                                                     |
|           5   11   5*13                                                     |
|                                                                             |
|o3 : Expression of class Sum                                                 |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * factor(Module) -- factor a ZZ-module

factor(RingElement) -- factor a ring element
********************************************

Synopsis
========

  * Function: factor,
  * Usage:
        factor x
  * Inputs:
      * x, or a rational number, or an integer,
  * Outputs:
      * a product expression, the factorization of x

Description
===========

The result is a Product, each of whose factors is a Power,
whose base is one of the factors found and whose exponent is an integer.

+------------------------------------------------------------------------+
|i1 : factor 124744878111332355674003415153753485211381849014286981744945|
|                                                                        |
|                7                                                       |
|o1 = 3*5*53*2819 10861*10212222054939737109085868749                    |
|                                                                        |
|o1 : Expression of class Product                                        |
+------------------------------------------------------------------------+
|i2 : y = (2^15-4)/(2^15-5)                                              |
|                                                                        |
|     32764                                                              |
|o2 = -----                                                              |
|     32763                                                              |
|                                                                        |
|o2 : QQ                                                                 |
+------------------------------------------------------------------------+
|i3 : x = factor y                                                       |
|                                                                        |
|       2                                                                |
|      2 8191                                                            |
|o3 = --------                                                           |
|     3*67*163                                                           |
|                                                                        |
|o3 : Expression of class Divide                                         |
+------------------------------------------------------------------------+
|i4 : value x                                                            |
|                                                                        |
|     32764                                                              |
|o4 = -----                                                              |
|     32763                                                              |
|                                                                        |
|o4 : QQ                                                                 |
+------------------------------------------------------------------------+

We may peek, inside x to a high depth to see its true structure as
Expression.

+-----------------------------------------------------------------------------+
|i5 : peek'(100,x)                                                            |
|                                                                             |
|o5 = Divide{Product{Power{2, 2}, Power{8191, 1}}, Product{Power{3, 1},       |
|     ------------------------------------------------------------------------|
|     Power{67, 1}, Power{163, 1}}}                                           |
+-----------------------------------------------------------------------------+

For integers, factorization is done by FLINT, and the factors $x$
are actually just probably prime, as described in the documentation of
isPseudoprime.

For multivariate polynomials the factorization is done with code of Michael
Messollen (see Singular-Factory).  For univariate
polynomials the factorization is in turn done with code of Gert-Martin Greuel
and Ruediger Stobbe (see Singular-Factory).

+--------------------------------+
|i6 : R = ZZ/101[u]              |
|                                |
|o6 = R                          |
|                                |
|o6 : PolynomialRing             |
+--------------------------------+
|i7 : factor (u^3-1)             |
|                                |
|              2                 |
|o7 = (u - 1)(u  + u + 1)        |
|                                |
|o7 : Expression of class Product|
+--------------------------------+
The constant term is provided as the last factor, if it's not equal to 1.
+-------------------------------+
|i8 : F = frac(ZZ/101[t])       |
|                               |
|o8 = F                         |
|                               |
|o8 : FractionField             |
+-------------------------------+
|i9 : factor ((t^3-1)/(t^3+1))  |
|                               |
|              2                |
|     (t - 1)(t  + t + 1)       |
|o9 = -------------------       |
|              2                |
|     (t + 1)(t  - t + 1)       |
|                               |
|o9 : Expression of class Divide|
+-------------------------------+

Ways to use this method:
========================

  * "factor(QQ)"
  * factor(RingElement) -- factor a ring
    element
  * "factor(ZZ)"

false
*****

Description
===========

false is a value indicating falsity.

For the programmer
==================

The object false, is a Boolean value.

Fano -- Fano scheme
*******************

Ways to use Fano:
=================

  * Fano(ZZ,Ideal) -- Fano scheme
  * Fano(ZZ,Ideal,Ring) -- Fano scheme

For the programmer
==================

The object Fano, is a method function.

Fano(ZZ,Ideal) -- Fano scheme
*****************************

Synopsis
========

  * Function: Fano,
  * Usage:
        Fano(k,I)
  * Inputs:
      * k, a positive integer less than r
      * I, an ideal representing a variety in projective r-space
  * Outputs:
      * the ideal of a Fano scheme in the Grassmannian

Description
===========

Given an ideal I representing a projective variety X in P^r, a positive integer
k<r, and optionally a ring GR with (exactly) r+1 choose k+1 variables,
representing the ambient space of the Grassmannian of k-planes in P^r, this
routine returns the ideal in GR of the Fano scheme that parametrizes the
k-planes lying on X.  If the optional third argument is not present, the
routine fabricates its own ring, and returns an ideal in it.

See also
========

  * Fano(ZZ,Ideal,Ring) -- Fano scheme

Ways to use this method:
========================

  * Fano(ZZ,Ideal) -- Fano scheme

Fano(ZZ,Ideal,Ring) -- Fano scheme
**********************************

Synopsis
========

  * Function: Fano,
  * Usage:
        Fano(k,I,GR)
  * Inputs:
      * k, a positive integer less than r
      * I, an ideal representing a variety in projective r-space
      * GR,
  * Outputs:
      * the ideal of a Fano scheme in the Grassmannian

Description
===========

Given an ideal I representing a projective variety X in P^r, a positive integer
k<r, and optionally a ring GR with (exactly) r+1 choose k+1 variables,
representing the ambient space of the Grassmannian of k-planes in P^r, this
routine returns the ideal in GR of the Fano scheme that parametrizes the
k-planes lying on X.  If the optional third argument is not present, the
routine fabricates its own ring, and returns an ideal in it.

See also
========

  * Fano(ZZ,Ideal) -- Fano scheme

Ways to use this method:
========================

  * Fano(ZZ,Ideal,Ring) -- Fano scheme

FastNonminimal -- compute a non-minimal graded free resolution
**************************************************************

Synopsis
========

  * Usage:
        C = res(I, FastNonminimal => true, ...)
  * Inputs:
      * I, an ideal, or a matrix, or a
        module, in a polynomial ring or skew commuting polynomial
        ring, over a finite prime field
  * Outputs:
      * C, a chain complex,

Description
===========

Given an inhomogeneous,  singly-graded, or multi-graded ideal or module, this
function computes a non-minimal free resolution.  If the input is an ideal $I
\subset S$, it computes a non-minimal resolution of $S^1/I$.

A key benefit of this function is that it allows a much faster method for
computing the betti numbers of the minimal free resolution. If that is your
only interest (i.e. you don't need the complex itself), instead use
minimalBetti.  However, see minimalBetti,
currently only works for single gradings, not multi-gradings.

+-----------------------------------------------------------------------------+
|i1 : I = Grassmannian(1,6, CoefficientRing => ZZ/101);                       |
|                                                                             |
|               ZZ                                                            |
|o1 : Ideal of ---[p   ..p   , p   , p   , p   , p   , p   , p   , p   , p   ,|
|              101  0,1   0,2   1,2   0,3   1,3   2,3   0,4   1,4   2,4   3,4 |
|-----------------------------------------------------------------------------|
|p   , p   , p   , p   , p   , p   , p   , p   , p   , p   , p   ]            |
| 0,5   1,5   2,5   3,5   4,5   0,6   1,6   2,6   3,6   4,6   5,6             |
+-----------------------------------------------------------------------------+
|i2 : S = ring I                                                              |
|                                                                             |
|o2 = S                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : elapsedTime C = res(I, FastNonminimal => true)                          |
| -- 2.00116s elapsed                                                         |
|                                                                             |
|      1      35      241      841      1781      2464      2294      1432    |
|o3 = S  <-- S   <-- S    <-- S    <-- S     <-- S     <-- S     <-- S     <--|
|                                                                             |
|     0      1       2        3        4         5         6         7        |
|                                                                             |
|o3 : ChainComplex                                                            |
|-----------------------------------------------------------------------------|
| 576      135      14                                                        |
|S    <-- S    <-- S   <-- 0                                                  |
|                                                                             |
|8        9        10      11                                                 |
+-----------------------------------------------------------------------------+
|i4 : elapsedTime C1 = res ideal(I_*)                                         |
| -- 1.10435s elapsed                                                         |
|                                                                             |
|      1      35      140      385      819      1080      819      385       |
|o4 = S  <-- S   <-- S    <-- S    <-- S    <-- S     <-- S    <-- S    <--   |
|                                                                             |
|     0      1       2        3        4        5         6        7          |
|                                                                             |
|o4 : ChainComplex                                                            |
|-----------------------------------------------------------------------------|
| 140      35      1                                                          |
|S    <-- S   <-- S  <-- 0                                                    |
|                                                                             |
|8        9       10     11                                                   |
+-----------------------------------------------------------------------------+
|i5 : betti(C, Minimize => true) == betti C1                                  |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+

For a non-minimal resolution, see betti, gives the actual Betti
numbers, and using the betti(...,Minimize=>...),
option gives the ranks in a minimal
resolution (which is itself not computed).

+-------------------------------------------------------+
|i6 : betti C                                           |
|                                                       |
|            0  1   2   3    4    5    6    7   8   9 10|
|o6 = total: 1 35 241 841 1781 2464 2294 1432 576 135 14|
|         0: 1  .   .   .    .    .    .    .   .   .  .|
|         1: . 35 140 290  402  402  293  152  53  11  1|
|         2: .  . 101 514 1174 1577 1365  780 287  62  6|
|         3: .  .   .  37  204  479  621  480 221  56  6|
|         4: .  .   .   .    1    6   15   20  15   6  1|
|                                                       |
|o6 : BettiTally                                        |
+-------------------------------------------------------+
|i7 : betti(C, Minimize => true)                        |
|                                                       |
|            0  1   2   3   4    5   6   7   8  9 10    |
|o7 = total: 1 35 140 385 819 1080 819 385 140 35  1    |
|         0: 1  .   .   .   .    .   .   .   .  .  .    |
|         1: . 35 140 189  84    .   .   .   .  .  .    |
|         2: .  .   . 196 735 1080 735 196   .  .  .    |
|         3: .  .   .   .   .    .  84 189 140 35  .    |
|         4: .  .   .   .   .    .   .   .   .  .  1    |
|                                                       |
|o7 : BettiTally                                        |
+-------------------------------------------------------+

As mentioned above, if you are just interested in the minimal betti numbers of
the ideal or module, then use minimalBetti, as it avoids
construction of the non-minimal free resolution.

+---------------------------------------------------+
|i8 : minimalBetti I                                |
|                                                   |
|            0  1   2   3   4    5   6   7   8  9 10|
|o8 = total: 1 35 140 385 819 1080 819 385 140 35  1|
|         0: 1  .   .   .   .    .   .   .   .  .  .|
|         1: . 35 140 189  84    .   .   .   .  .  .|
|         2: .  .   . 196 735 1080 735 196   .  .  .|
|         3: .  .   .   .   .    .  84 189 140 35  .|
|         4: .  .   .   .   .    .   .   .   .  .  1|
|                                                   |
|o8 : BettiTally                                    |
+---------------------------------------------------+

If the resolution is not large, this function can be slower than the usual
function resolution.  But for larger examples, if one is
only interested in the betti numbers, this function can be hundreds or
thousands of times faster.

If the input module is not graded, or is multi-graded, this function still
works. However, see minimalBetti, does not work in these cases.
In the inhomogeneous case, the returned free resolution is often highly non
minimal. Of course, there is no notion of minimal resolution in this case, but
one can use pruneComplex (PruneComplex), to clean up the
returned complex.

+--------------------------------------------------------+
|i9 : R = ZZ/101[a..f]                                   |
|                                                        |
|o9 = R                                                  |
|                                                        |
|o9 : PolynomialRing                                     |
+--------------------------------------------------------+
|i10 : I = ideal"a3-ab-c2,abc-d2-1, b3-b2-b"             |
|                                                        |
|              3          2           2       3    2     |
|o10 = ideal (a  - a*b - c , a*b*c - d  - 1, b  - b  - b)|
|                                                        |
|o10 : Ideal of R                                        |
+--------------------------------------------------------+
|i11 : C = res(I, FastNonminimal => true)                |
|                                                        |
|       1      12      28      24      7                 |
|o11 = R  <-- R   <-- R   <-- R   <-- R  <-- 0           |
|                                                        |
|      0      1       2       3       4      5           |
|                                                        |
|o11 : ChainComplex                                      |
+--------------------------------------------------------+
|i12 : needsPackage "PruneComplex"                       |
|                                                        |
|o12 = PruneComplex                                      |
|                                                        |
|o12 : Package                                           |
+--------------------------------------------------------+
|i13 : pruneComplex C                                    |
|                                                        |
|       1      3      3      1                           |
|o13 = R  <-- R  <-- R  <-- R                            |
|                                                        |
|      0      1      2      3                            |
|                                                        |
|o13 : ChainComplex                                      |
+--------------------------------------------------------+

If one has a specific Groebner basis on which one wants to base the Schreyer
resolution, use Strategy=>5.  This will not check that the input forms a
Groebner basis, but if it does not, then the function will either produce
non-sensical answers, or fail.

+-----------------------------------------------------------------------------+
|i14 : R = ZZ/101[a..c,x_1..x_9, MonomialOrder=>{3,9}]                        |
|                                                                             |
|o14 = R                                                                      |
|                                                                             |
|o14 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i15 : I = ideal(a^2 - b^2 - x_1 * a*c - x_2 * b*c - x_3 * c^2,               |
|                 a*b - x_4 * a*c - x_5 * b*c - x_6 *c^2,                     |
|                 b^2 - x_7 * a*c - x_8 * b*c - x_9 *c^2                      |
|                 )                                                           |
|                                                                             |
|              2    2                      2                             2    |
|o15 = ideal (a  - b  - a*c*x  - b*c*x  - c x , a*b - a*c*x  - b*c*x  - c x , |
|                            1        2      3             4        5      6  |
|      -----------------------------------------------------------------------|
|       2                      2                                              |
|      b  - a*c*x  - b*c*x  - c x )                                           |
|                7        8      9                                            |
|                                                                             |
|o15 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i16 : C = res(I, FastNonminimal => true, Strategy=>5)                        |
|                                                                             |
|       1      3      2                                                       |
|o16 = R  <-- R  <-- R  <-- 0                                                 |
|                                                                             |
|      0      1      2      3                                                 |
|                                                                             |
|o16 : ChainComplex                                                           |
+-----------------------------------------------------------------------------+
|i17 : C.dd                                                                   |
|                                                                             |
|           1                                                                 |
|o17 = 0 : R  <---------------------------------------------------------------|
|                | a2-b2-acx_1-bcx_2-c2x_3 ab-acx_4-bcx_5-c2x_6 b2-acx_7-bcx_8|
|                                                                             |
|           3                                              2                  |
|      1 : R  <------------------------------------------ R  : 2              |
|                {2} | -b+cx_4           cx_7         |                       |
|                {2} | a-cx_1+cx_5-cx_7  -b-cx_4+cx_8 |                       |
|                {2} | -b-cx_2+cx_4-cx_8 a-cx_5+cx_7  |                       |
|                                                                             |
|           2                                                                 |
|      2 : R  <----- 0 : 3                                                    |
|                0                                                            |
|                                                                             |
|o17 : ChainComplexMap                                                        |
|-----------------------------------------------------------------------------|
|            3                                                                |
|---------- R  : 1                                                            |
|-c2x_9 |                                                                     |
+-----------------------------------------------------------------------------+

Note that Strategy=>4 or Strategy=>5 implies FastNonminimal.

+-----------------------------------------------------------------------------+
|i18 : C1 = res(ideal I_*, Strategy=>5)                                       |
|                                                                             |
|       1      3      2                                                       |
|o18 = R  <-- R  <-- R  <-- 0                                                 |
|                                                                             |
|      0      1      2      3                                                 |
|                                                                             |
|o18 : ChainComplex                                                           |
+-----------------------------------------------------------------------------+
|i19 : C1.dd                                                                  |
|                                                                             |
|           1                                                                 |
|o19 = 0 : R  <---------------------------------------------------------------|
|                | a2-b2-acx_1-bcx_2-c2x_3 ab-acx_4-bcx_5-c2x_6 b2-acx_7-bcx_8|
|                                                                             |
|           3                                              2                  |
|      1 : R  <------------------------------------------ R  : 2              |
|                {2} | -b+cx_4           cx_7         |                       |
|                {2} | a-cx_1+cx_5-cx_7  -b-cx_4+cx_8 |                       |
|                {2} | -b-cx_2+cx_4-cx_8 a-cx_5+cx_7  |                       |
|                                                                             |
|           2                                                                 |
|      2 : R  <----- 0 : 3                                                    |
|                0                                                            |
|                                                                             |
|o19 : ChainComplexMap                                                        |
|-----------------------------------------------------------------------------|
|            3                                                                |
|---------- R  : 1                                                            |
|-c2x_9 |                                                                     |
+-----------------------------------------------------------------------------+

Caveat
======

Released in M2 1.9, still experimental.  Only works over finite prime fields.
Uses quite a lot of memory. For inhomogeneous ideals or modules, the monomial
order must be a degree order.  For multi-graded ideals or modules, see
minimalBetti, is not yet implemented.

See also
========

  * minimalBetti -- minimal betti numbers of (the minimal
    free resolution of) a homogeneous ideal or module
  * betti -- display or modify a Betti diagram
  * betti(...,Minimize=>...),
    -- minimal betti numbers of a non-minimal free resolution
  * resolution -- projective resolution
  * pruneComplex (PruneComplex) -- Prunes a chain complex
    or list of mutable matrices

Functions with optional argument named FastNonminimal:
======================================================

  * "resolution(...,FastNonminimal=>...)"

For the programmer
==================

The object FastNonminimal, is a symbol.

File -- the class of all files
******************************

Description
===========

Files may be input files, output files, pipes, or sockets. A list of currently
open files may be obtained with openFiles.

Functions operating on path names:
==================================

  * minimizeFilename -- minimize a file name
  * path -- list of directories to look in
  * relativizeFilename -- relativize a file name
  * searchPath -- search a path for a
    file
  * temporaryFileName -- make a temporary file name
  * toAbsolutePath -- the absolute path version of a
    file name

Functions and methods returning a file:
=======================================

  * "File << Manipulator" -- see File << Thing, -- print
    to a file
  * "File << Symbol" -- see File << Thing, -- print to a
    file
  * File << Thing -- print to a file
  * "Nothing << Thing" -- see File << Thing, -- print to a
    file
  * "String << Thing" -- see File << Thing, -- print to a
    file
  * "NetFile << Manipulator" -- see NetFile, -- the class of all
    net files
  * openIn(String) -- open an input file
  * "openInOut(File)" -- see openInOut, -- open an input
    output file
  * "openInOut(String)" -- see openInOut, -- open an input
    output file
  * openListener(String) -- open a port for
    listening
  * openOut(String) -- open an output file
  * openOutAppend(String) -- open an output
    file for appending

Methods that use a file:
========================

  * atEndOfFile(File) -- test for end of file
  * "echoOff(File)" -- see echoOff, -- turn off echoing
  * "echoOn(File)" -- see echoOn, -- turn on echoing
  * "File << Net" -- see File << Thing, -- print to a file
  * "File << String" -- see File << Thing, -- print to a
    file
  * fileMode(File) -- get file mode
  * fileMode(ZZ,File) -- set file mode
  * "get(File)" -- see get, -- get the contents of a file
  * "getc(File)" -- see getc, -- get a byte
  * height(File) -- get window height
  * isInputFile(File) -- whether a file is open
    for input
  * isListener(File) -- whether a file is open for
    listening
  * "isOpen(File)" -- see isOpen, -- whether a file or database
    is open
  * isOutputFile(File) -- whether a file is open
    for output
  * isReady(File) -- whether a file has data
    available for reading
  * "kill(File)" -- see kill, -- kill a process
  * "Manipulator File" -- see Manipulator, -- the class of
    all file manipulators
  * read(File) -- read from a file
  * read(File,ZZ) -- read from a file
  * width(File) -- get window width

Protected objects of class File:
================================

  * stderr -- the standard error output file
  * stdio -- the standard input output file

For the programmer
==================

The object File, is a type, with ancestor class
Thing.

File << Thing -- print to a file
********************************

Synopsis
========

  * Operator: <<,
  * Usage:
        f << x
        << x
  * Inputs:
      * f, a file, a string, or null,
      * x
  * Outputs:
      * the output file(s) used, a file,
  * Consequences:
      * The object x is prepared for printing (with net) and
        printed on the output file(s) f. If f is a string, then it is
        interpreted as a filename and an output file is opened, used, and
        returned, unless a single open file with the same name already exists,
        in which case it is used and returned. Filenames starting with ! or
        with $ are treated specially, see openInOut. If f is
        a list, then the output operation is performed on each one. If f is
        null, then the output is discarded; thus null,
        is useful as a dummy output file. If f is omitted, as in the second
        usage line, then the output is sent to stdio, and it will
        appear (usually) on the screen.

Description
===========

Parsing of <<, associates leftward, so that several objects  may be
displayed with an expression such as f<<x<<y<<z.

+-----------------------------------------------------------------------------+
|i1 : stderr << "-- hi there --" << endl                                      |
|-- hi there --                                                               |
|                                                                             |
|o1 = stderr                                                                  |
|                                                                             |
|o1 : File                                                                    |
+-----------------------------------------------------------------------------+
|i2 : << "-- ho there --" << endl                                             |
|-- ho there --                                                               |
|                                                                             |
|o2 = stdio                                                                   |
|                                                                             |
|o2 : File                                                                    |
+-----------------------------------------------------------------------------+
|i3 : fn = temporaryFileName()                                                |
|                                                                             |
|o3 = /tmp/M2-2534446-0/0                                                     |
+-----------------------------------------------------------------------------+
|i4 : fn << "hi there" << endl << close                                       |
|                                                                             |
|o4 = /tmp/M2-2534446-0/0                                                     |
|                                                                             |
|o4 : File                                                                    |
+-----------------------------------------------------------------------------+
|i5 : get fn                                                                  |
|                                                                             |
|o5 = hi there                                                                |
+-----------------------------------------------------------------------------+
|i6 : R = QQ[x]                                                               |
|                                                                             |
|o6 = R                                                                       |
|                                                                             |
|o6 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i7 : f = (x+1)^10                                                            |
|                                                                             |
|      10      9      8       7       6       5       4       3      2        |
|o7 = x   + 10x  + 45x  + 120x  + 210x  + 252x  + 210x  + 120x  + 45x  + 10x +|
|     ------------------------------------------------------------------------|
|     1                                                                       |
|                                                                             |
|o7 : R                                                                       |
+-----------------------------------------------------------------------------+
|i8 : << f                                                                    |
| 10      9      8       7       6       5       4       3      2             |
|x   + 10x  + 45x  + 120x  + 210x  + 252x  + 210x  + 120x  + 45x  + 10x + 1   |
|o8 = stdio                                                                   |
|                                                                             |
|o8 : File                                                                    |
+-----------------------------------------------------------------------------+
|i9 : fn << f << close                                                        |
|                                                                             |
|o9 = /tmp/M2-2534446-0/0                                                     |
|                                                                             |
|o9 : File                                                                    |
+-----------------------------------------------------------------------------+
|i10 : get fn                                                                 |
|                                                                             |
|o10 =  10      9      8       7       6       5       4       3      2       |
|      x   + 10x  + 45x  + 120x  + 210x  + 252x  + 210x  + 120x  + 45x  + 10x |
|      + 1                                                                    |
+-----------------------------------------------------------------------------+
|i11 : fn << toExternalString f << close                                      |
|                                                                             |
|o11 = /tmp/M2-2534446-0/0                                                    |
|                                                                             |
|o11 : File                                                                   |
+-----------------------------------------------------------------------------+
|i12 : get fn                                                                 |
|                                                                             |
|o12 = x^10+10*x^9+45*x^8+120*x^7+210*x^6+252*x^5+210*x^4+120*x^3+45*x^2+10*x+|
|      1                                                                      |
+-----------------------------------------------------------------------------+
|i13 : value get fn                                                           |
|                                                                             |
|       10      9      8       7       6       5       4       3      2       |
|o13 = x   + 10x  + 45x  + 120x  + 210x  + 252x  + 210x  + 120x  + 45x  + 10x |
|      -----------------------------------------------------------------------|
|      + 1                                                                    |
|                                                                             |
|o13 : R                                                                      |
+-----------------------------------------------------------------------------+
|i14 : removeFile fn                                                          |
+-----------------------------------------------------------------------------+

See also
========

  * stdio -- the standard input output file
  * stderr -- the standard error output file
  * endl -- end an output line
  * close -- close a file

Ways to use this method:
========================

  * "<< Thing"
  * "File << Manipulator"
  * "File << Net"
  * "File << String"
  * "File << Symbol"
  * File << Thing -- print to a file
  * "Nothing << Manipulator"
  * "Nothing << Thing"
  * "String << Thing"

fileDictionaries -- local dictionaries for loaded files
*******************************************************

Synopsis
========

  * Usage:
        fileDictionaries#fn
  * Inputs:
      * fn, a string,
  * Outputs:
      * the local dictionary in effect for the scope of the file loaded from
        the path fn

For the programmer
==================

The object fileDictionaries, is a mutable hash table.

fileExecutable
**************

Synopsis
========

  * Usage:
        fileExecutable n
  * Inputs:
      * n,
  * Outputs:
      * whether the file whose name is given by the string n is executable

Description
===========

+-----------------------+
|i1 : fileExecutable "."|
|                       |
|o1 = true              |
+-----------------------+

See also
========

  * fileWritable
  * fileReadable

Ways to use fileExecutable:
===========================

  * "fileExecutable(String)"

For the programmer
==================

The object fileExecutable, is a compiled function.

fileExitHooks -- a list of hooks (functions) to execute when the current file has been loaded
*********************************************************************************************

For the programmer
==================

The object fileExitHooks, is a list.

fileLength -- the length of a file
**********************************

Synopsis
========

  * Usage:
        fileLength f
  * Inputs:
      * f, a string, or a file,
  * Outputs:
      * an integer, the length of the file f or the file whose name
        is f

Description
===========

The length of an open output file is determined from the internal count of the
number of bytes written so far.

+------------------------------------------+
|i1 : f = temporaryFileName() << "hi there"|
|                                          |
|o1 = /tmp/M2-2535400-0/0                  |
|                                          |
|o1 : File                                 |
+------------------------------------------+
|i2 : fileLength f                         |
|                                          |
|o2 = 8                                    |
+------------------------------------------+
|i3 : close f                              |
|                                          |
|o3 = /tmp/M2-2535400-0/0                  |
|                                          |
|o3 : File                                 |
+------------------------------------------+
|i4 : filename = toString f                |
|                                          |
|o4 = /tmp/M2-2535400-0/0                  |
+------------------------------------------+
|i5 : fileLength filename                  |
|                                          |
|o5 = 8                                    |
+------------------------------------------+
|i6 : get filename                         |
|                                          |
|o6 = hi there                             |
+------------------------------------------+
|i7 : length oo                            |
|                                          |
|o7 = 8                                    |
+------------------------------------------+
|i8 : removeFile filename                  |
+------------------------------------------+

See also
========

  * fileTime -- get or set file modified time

For the programmer
==================

The object fileLength, is a compiled function.

fileMode -- set or get file mode
********************************

Ways to use fileMode:
=====================

  * fileMode(File) -- get file mode
  * fileMode(String) -- get file mode
  * fileMode(ZZ,File) -- set file mode
  * fileMode(ZZ,String) -- set file mode

For the programmer
==================

The object fileMode, is a compiled function.

fileMode(File) -- get file mode
*******************************

Synopsis
========

  * Function: fileMode,
  * Usage:
        fileMode f
  * Inputs:
      * f
  * Outputs:
      * the mode of the open file f

Description
===========

+-----------------------------+
|i1 : fn = temporaryFileName()|
|                             |
|o1 = /tmp/M2-2533744-0/0     |
+-----------------------------+
|i2 : f = fn << "hi there"    |
|                             |
|o2 = /tmp/M2-2533744-0/0     |
|                             |
|o2 : File                    |
+-----------------------------+
|i3 : fileMode f              |
|                             |
|o3 = 420                     |
+-----------------------------+
|i4 : close f                 |
|                             |
|o4 = /tmp/M2-2533744-0/0     |
|                             |
|o4 : File                    |
+-----------------------------+
|i5 : removeFile fn           |
+-----------------------------+

Ways to use this method:
========================

  * fileMode(File) -- get file mode

fileMode(String) -- get file mode
*********************************

Synopsis
========

  * Function: fileMode,
  * Usage:
        fileMode fn
  * Inputs:
      * fn
  * Outputs:
      * the mode of the file located at the filename or path fn

Description
===========

+------------------------------+
|i1 : fn = temporaryFileName() |
|                              |
|o1 = /tmp/M2-2533213-0/0      |
+------------------------------+
|i2 : fn << "hi there" << close|
|                              |
|o2 = /tmp/M2-2533213-0/0      |
|                              |
|o2 : File                     |
+------------------------------+
|i3 : fileMode fn              |
|                              |
|o3 = 420                      |
+------------------------------+
|i4 : removeFile fn            |
+------------------------------+

Ways to use this method:
========================

  * fileMode(String) -- get file mode

fileMode(ZZ,File) -- set file mode
**********************************

Synopsis
========

  * Function: fileMode,
  * Usage:
        fileMode(mo,f)
  * Inputs:
      * mo
      * f
  * Consequences:
      * the mode of the open file f is set to mo

Description
===========

+-----------------------------+
|i1 : fn = temporaryFileName()|
|                             |
|o1 = /tmp/M2-2533019-0/0     |
+-----------------------------+
|i2 : f = fn << "hi there"    |
|                             |
|o2 = /tmp/M2-2533019-0/0     |
|                             |
|o2 : File                    |
+-----------------------------+
|i3 : m = 7 + 7*8 + 7*64      |
|                             |
|o3 = 511                     |
+-----------------------------+
|i4 : fileMode(m,f)           |
+-----------------------------+
|i5 : fileMode f              |
|                             |
|o5 = 511                     |
+-----------------------------+
|i6 : close f                 |
|                             |
|o6 = /tmp/M2-2533019-0/0     |
|                             |
|o6 : File                    |
+-----------------------------+
|i7 : fileMode fn             |
|                             |
|o7 = 511                     |
+-----------------------------+
|i8 : removeFile fn           |
+-----------------------------+

Ways to use this method:
========================

  * fileMode(ZZ,File) -- set file mode

fileMode(ZZ,String) -- set file mode
************************************

Synopsis
========

  * Function: fileMode,
  * Usage:
        fileMode(mo,fn)
  * Inputs:
      * mo
      * fn
  * Consequences:
      * the mode of the file located at the filename or path fn is set to mo

Description
===========

+------------------------------+
|i1 : fn = temporaryFileName() |
|                              |
|o1 = /tmp/M2-2534993-0/0      |
+------------------------------+
|i2 : fn << "hi there" << close|
|                              |
|o2 = /tmp/M2-2534993-0/0      |
|                              |
|o2 : File                     |
+------------------------------+
|i3 : m = fileMode fn          |
|                              |
|o3 = 420                      |
+------------------------------+
|i4 : fileMode(m|7,fn)         |
+------------------------------+
|i5 : fileMode fn              |
|                              |
|o5 = 423                      |
+------------------------------+
|i6 : removeFile fn            |
+------------------------------+

Ways to use this method:
========================

  * fileMode(ZZ,String) -- set file mode

FilePosition -- the class of all file positions
***********************************************

Description
===========

FilePosition -- a type of list designed to represent a position in a file.

It's implemented as a list with 3, 5 or 7 elements. The first part is the file
name, then each pair is a row/column position. A single pair is a position, two
form a range. The last pair is the central point of interest in that range.

Functions and methods returning a file position:
================================================

  * locate -- locate source code
  * "locate(Function)" -- see locate, -- locate source code
  * "locate(FunctionBody)" -- see locate, -- locate source code
  * "locate(Nothing)" -- see locate, -- locate source code
  * "locate(Pseudocode)" -- see locate, -- locate source code
  * "locate(Sequence)" -- see locate, -- locate source code
  * "locate(Symbol)" -- see locate, -- locate source code
  * locate(Command) (missing documentation)

Methods that use a file position:
=================================

  * code(FilePosition) (missing documentation)

For the programmer
==================

The object FilePosition, is a type, with
ancestor classes BasicList, < Thing.

fileReadable
************

Synopsis
========

  * Usage:
        fileReadable n
  * Inputs:
      * n,
  * Outputs:
      * whether the file whose name is given by the string n is readable

Description
===========

+---------------------+
|i1 : fileReadable "."|
|                     |
|o1 = true            |
+---------------------+

See also
========

  * fileWritable
  * fileExecutable

Ways to use fileReadable:
=========================

  * "fileReadable(String)"

For the programmer
==================

The object fileReadable, is a compiled function.

fileWritable
************

Synopsis
========

  * Usage:
        fileWritable n
  * Inputs:
      * n,
  * Outputs:
      * whether the file whose name is given by the string n is writable

Description
===========

+---------------------+
|i1 : fileWritable "."|
|                     |
|o1 = true            |
+---------------------+

See also
========

  * fileReadable
  * fileExecutable

Ways to use fileWritable:
=========================

  * "fileWritable(String)"

For the programmer
==================

The object fileWritable, is a compiled function.

fillMatrix -- fill a mutable matrix with random numbers
*******************************************************

Synopsis
========

  * Function: fillMatrix,
  * Usage:
        fillMatrix M
        fillMatrix(M,n)
  * Inputs:
      * M, a mutable matrix,
      * n, an integer, if specified, the maximum number of entries
        to replace
  * Optional inputs,:
      * Density => a real number, default value 1, the fraction of
        entries of M to be replaced, if n is not specified
      * UpperTriangular => a Boolean value, default value
        false, whether to fill entries only above the diagonal
      * Height => an integer, default value 10, a bound on the
        absolute values of the generated random numbers
  * Outputs:
      * M
  * Consequences:
      * some entries of M are replaced with randomly generated numbers, whose
        size depends on the value of the option Height

Description
===========

+----------------------------------------------------------------------+
|i1 : printingPrecision = 2                                            |
|                                                                      |
|o1 = 2                                                                |
+----------------------------------------------------------------------+
|i2 : fillMatrix(mutableMatrix(RR,5,10))                               |
|                                                                      |
|o2 = | .89  .71 .91  .71 .35 .54 .19  .39 .28 .89  |                  |
|     | .67  .89 .31  .13 .56 .87 .4   .56 .61 .17  |                  |
|     | .29  .23 .074 .25 .25 .42 .62  .87 .97 .97  |                  |
|     | .63  .46 .81  .74 .15 .61 .015 .7  .68 .065 |                  |
|     | .026 .78 .36  .11 .83 .85 .22  .68 .91 .88  |                  |
|                                                                      |
|o2 : MutableMatrix                                                    |
+----------------------------------------------------------------------+
|i3 : fillMatrix(mutableMatrix(ZZ,5,10),UpperTriangular=>true)         |
|                                                                      |
|o3 = | 0 8 2 1 6 4 2 5 6 7 |                                          |
|     | 0 0 2 7 7 0 6 4 4 9 |                                          |
|     | 0 0 0 5 4 1 1 9 8 0 |                                          |
|     | 0 0 0 0 5 4 1 7 4 9 |                                          |
|     | 0 0 0 0 0 4 4 4 2 3 |                                          |
|                                                                      |
|o3 : MutableMatrix                                                    |
+----------------------------------------------------------------------+
|i4 : fillMatrix(mutableMatrix(QQ,5,10),Density=>.2,Height=>1000)      |
|                                                                      |
|o4 = | 0 0       243/835 89/26 0     76/169 0       0 473/389 2/9    ||
|     | 0 0       0       0     0     0      0       0 0       0      ||
|     | 0 250/159 519/809 0     79/74 0      701/437 0 377/614 0      ||
|     | 0 0       0       0     0     0      0       0 0       0      ||
|     | 0 0       0       0     0     0      0       0 31/951  38/707 ||
|                                                                      |
|o4 : MutableMatrix                                                    |
+----------------------------------------------------------------------+
|i5 : fillMatrix(mutableMatrix(ZZ,5,10),25,Height=>1000)               |
|                                                                      |
|o5 = | 0   0   0   0   693 0   0   0 0   0   |                        |
|     | 830 622 0   655 817 0   170 0 851 155 |                        |
|     | 948 0   520 0   0   897 0   0 591 0   |                        |
|     | 0   391 0   274 0   968 0   0 0   596 |                        |
|     | 12  0   0   366 0   625 181 0 0   0   |                        |
|                                                                      |
|o5 : MutableMatrix                                                    |
+----------------------------------------------------------------------+

See also
========

  * setRandomSeed -- set starting point for random number
    generator
  * random -- get a random object
  * mutableMatrix -- make a mutable matrix

Ways to use fillMatrix:
=======================

  * "fillMatrix(MutableMatrix)"
  * "fillMatrix(MutableMatrix,ZZ)"

For the programmer
==================

The object fillMatrix, is a method function with options.

finding your files under cygwin
*******************************

In Microsoft Windows, most people run programs by pulling down menus or by
clicking on icons that have been carefully placed there by install programs.
Thus the idea of a path along which to search for programs (such as a browser)
is no longer useful in Windows.

On my computer the browser program firefox.exe is in the following directory.
    C:/Program Files/Mozilla Firefox
But M2 is a Cygwin program, and it lives in a different world, where paths to
files don't ever start out with something like C:.  In that world, firefox's
directory is known instead as:
     /cygdrive/c/Program Files/Mozilla Firefox
Conversely, the root directory, known in the Cygwin world as /, could be
located anywhere in the Windows world.  On my machine it is at
     C:/cygwin
Use the df command or the mount command in a cygwin command shell window to
determine that path: it is the file system on which / is mounted.

FindOne -- find a primitive element
***********************************

Description
===========

FindOne -- a value for the option PrimitiveElement, to
GF, which specifies that GF, should search for a primitive
element.

For the programmer
==================

The object FindOne, is a symbol.

findProgram -- load external program
************************************

Synopsis
========

  * Usage:
        findProgram name
        findProgram(name, cmd)
        findProgram(name, cmds)
  * Inputs:
      * name, a string, the name of the program to load.  This
        should match the corresponding key in programPaths.
      * cmd, a string, a command to run that should return 0 if
        the program is present.
      * cmds, a list, a list of commands to run that should all
        return 0 if the program is present.
  * Optional inputs,:
      * RaiseError => a Boolean value, default value true,
        whether to raise an error if the program is not found.
      * Verbose => a Boolean value, default value false,
        whether to inform the user of each path that is checked.
      * Prefix => a list, default value {}, a list of sequences
        containing two strings identifying a prefix that is added to the
        executable binaries belonging to the program by some distributions.
        These sequences should be of the form (regex, prefix), where regex is a
        regular expression, that should match all
        binary executables that need the prefix and prefix is the prefix
        itself.
      * AdditionalPaths => a list, default value {}, a list of
        strings containing any paths to check for the program in addition to
        the default ones.
      * MinimumVersion => a sequence, default value null,
        containing two strings the form (minVersion, versionCommand) where
        minVersion is the minimum required version of the program and
        versionCommand is a shell command to obtain the version number of an
        installed program.
  * Outputs:
      * an instance of the type Program, the program that was
        loaded.  If the program is not found and RaiseError is set to
        false, then null, is returned.

Description
===========

This function checks for the existence of an external program by running cmd
(or every element of cmds), prepended with various paths in the following
order:

  * The user-defined path specified by programPaths#name, if it exists.
  * The path specified by prefixDirectory | currentLayout#"programs", where the
    programs shipped with Macaulay2 are installed.
  * Each path specified by the AdditionalPaths option.
  * Each path specified by the user's PATH environment variable.
  * The path to M2-binary.

For each path, any prefixes specified by the Prefix option are checked.

Once this is successful (i.e., cmd or each element of cmds returns a value of
0) then a Program, object is returned.  If it is unsuccessful,
then either an error is raised or null, is returned, depending on
the value of RaiseError.

Note that if a program consists of a single executable binary file, then name
should coincide with the name of this file.

+-----------------------------------------------------------------------------+
|i1 :                                                                         |
|     programPaths#"gfan" = "/path/to/gfan/"                                  |
|                                                                             |
|o1 = /path/to/gfan/                                                          |
+-----------------------------------------------------------------------------+
|i2 : gfan = findProgram("gfan", "gfan _version --help", Verbose => true)     |
| -- /path/to/gfan/gfan does not exist                                        |
| -- /usr/local/libexec/Macaulay2/bin/gfan does not exist                     |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/gfan does|
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/gfan does|
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/gfan does|
| -- /home/m2user/.local/bin/gfan does not exist                              |
| -- /usr/local/sbin/gfan does not exist                                      |
| -- /usr/local/bin/gfan does not exist                                       |
| -- /usr/sbin/gfan does not exist                                            |
| -- /usr/bin/gfan exists and is executable                                   |
| -- running "/usr/bin/gfan _version --help":                                 |
|This program writes out version information of the Gfan installation.        |
| -- return value: 0                                                          |
|                                                                             |
|o2 = gfan                                                                    |
|                                                                             |
|o2 : Program                                                                 |
|-----------------------------------------------------------------------------|
|not exist                                                                    |
|not exist                                                                    |
|not exist                                                                    |
+-----------------------------------------------------------------------------+
|i3 : findProgram "normaliz"                                                  |
|                                                                             |
|o3 = normaliz                                                                |
|                                                                             |
|o3 : Program                                                                 |
+-----------------------------------------------------------------------------+

If cmd is not provided, then cmd is run with the common --version command line
option.

+-----------------------------------------------------------------------------+
|i4 : findProgram("topcom", "cube 3", Verbose => true, Prefix => {            |
|       (".*", "topcom-"),                                                    |
|       ("^(cross|cube|cyclic|hypersimplex|lattice)$", "TOPCOM-"),            |
|       ("^cube$", "topcom_")})                                               |
| -- /usr/local/libexec/Macaulay2/bin/cube does not exist                     |
| -- /usr/local/libexec/Macaulay2/bin/topcom-cube does not exist              |
| -- /usr/local/libexec/Macaulay2/bin/TOPCOM-cube does not exist              |
| -- /usr/local/libexec/Macaulay2/bin/topcom_cube does not exist              |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/         |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/         |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/         |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/         |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/         |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/         |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/         |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/         |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/         |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/         |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/         |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/         |
| -- /home/m2user/.local/bin/cube does not exist                              |
| -- /home/m2user/.local/bin/topcom-cube does not exist                       |
| -- /home/m2user/.local/bin/TOPCOM-cube does not exist                       |
| -- /home/m2user/.local/bin/topcom_cube does not exist                       |
| -- /usr/local/sbin/cube does not exist                                      |
| -- /usr/local/sbin/topcom-cube does not exist                               |
| -- /usr/local/sbin/TOPCOM-cube does not exist                               |
| -- /usr/local/sbin/topcom_cube does not exist                               |
| -- /usr/local/bin/cube does not exist                                       |
| -- /usr/local/bin/topcom-cube does not exist                                |
| -- /usr/local/bin/TOPCOM-cube does not exist                                |
| -- /usr/local/bin/topcom_cube does not exist                                |
| -- /usr/sbin/cube does not exist                                            |
| -- /usr/sbin/topcom-cube does not exist                                     |
| -- /usr/sbin/TOPCOM-cube does not exist                                     |
| -- /usr/sbin/topcom_cube does not exist                                     |
| -- /usr/bin/cube does not exist                                             |
| -- /usr/bin/topcom-cube exists and is executable                            |
| -- running "/usr/bin/topcom-cube 3":                                        |
|[[0,0,0,1],[1,0,0,1],[0,1,0,1],[1,1,0,1],[0,0,1,1],[1,0,1,1],[0,1,1,         |
|[[7,6,5,4,3,2,1,0],[6,7,4,5,2,3,0,1],[4,6,5,7,0,2,1,3],[0,4,2,6,1,5,         |
| -- return value: 0                                                          |
|                                                                             |
|o4 = topcom                                                                  |
|                                                                             |
|o4 : Program                                                                 |
|-----------------------------------------------------------------------------|
|cube does not exist                                                          |
|topcom-cube does not exist                                                   |
|TOPCOM-cube does not exist                                                   |
|topcom_cube does not exist                                                   |
|cube does not exist                                                          |
|topcom-cube does not exist                                                   |
|TOPCOM-cube does not exist                                                   |
|topcom_cube does not exist                                                   |
|cube does not exist                                                          |
|topcom-cube does not exist                                                   |
|TOPCOM-cube does not exist                                                   |
|topcom_cube does not exist                                                   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|1],[1,1,1,1]]                                                                |
|3,7]]                                                                        |
+-----------------------------------------------------------------------------+

One program that is shipped with a variety of prefixes in different
distributions and for which the Prefix option is useful is TOPCOM:

+-----------------------------------------------------------------------------+
|i5 : findProgram("gfan", "gfan _version --help", Verbose => true,            |
|       MinimumVersion => ("0.5",                                             |
|      "gfan _version | head -2 | tail -1 | sed 's/gfan//'"))                 |
| -- /path/to/gfan/gfan does not exist                                        |
| -- /usr/local/libexec/Macaulay2/bin/gfan does not exist                     |
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/gfan does|
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/gfan does|
| -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/gfan does|
| -- /home/m2user/.local/bin/gfan does not exist                              |
| -- /usr/local/sbin/gfan does not exist                                      |
| -- /usr/local/bin/gfan does not exist                                       |
| -- /usr/sbin/gfan does not exist                                            |
| -- /usr/bin/gfan exists and is executable                                   |
| -- running "/usr/bin/gfan _version --help":                                 |
|This program writes out version information of the Gfan installation.        |
| -- return value: 0                                                          |
| -- found version 0.6.2 >= 0.5                                               |
|                                                                             |
|o5 = gfan                                                                    |
|                                                                             |
|o5 : Program                                                                 |
|-----------------------------------------------------------------------------|
|not exist                                                                    |
|not exist                                                                    |
|not exist                                                                    |
+-----------------------------------------------------------------------------+

Note that when using the MinimumVersion option, the command used to obtain the
current version number must remove everything except the version number itself
and any leading or trailing whitespace.  Piping with standard UNIX utilities
such as sed, head, tail, cut, and tr may be useful.

+-----+
|i6 : |
+-----+

See also
========

  * Program -- external program object
  * programPaths -- user-defined external program paths
  * runProgram -- run an external program

Ways to use findProgram:
========================

  * "findProgram(String)"
  * "findProgram(String,List)"
  * "findProgram(String,String)"

For the programmer
==================

The object findProgram, is a method function with options.

findSynonyms(Symbol) -- find synonyms of symbols
************************************************

Synopsis
========

  * Function: findSynonyms,
  * Usage:
        findSynonyms x
  * Inputs:
      * x
  * Outputs:
      * a list of all the names for the symbol appearing in global dictionaries
        in use

Description
===========

+-------------------------------------------------+
|i1 : findSynonyms symbol res                     |
|                                                 |
|o1 = {Core$res, Core$resolution, res, resolution}|
|                                                 |
|o1 : List                                        |
+-------------------------------------------------+
|i2 : symbol res === symbol resolution            |
|                                                 |
|o2 = true                                        |
+-------------------------------------------------+
|i3 : res === resolution                          |
|                                                 |
|o3 = true                                        |
+-------------------------------------------------+
|i4 : res                                         |
|                                                 |
|o4 = resolution                                  |
|                                                 |
|o4 : MethodFunctionWithOptions                   |
+-------------------------------------------------+

Code
====

../../../../../Macaulay2/m2/document.m2:822:23-826:23: --source code:
findSynonyms Symbol := x -> (
    result := {};
    scan(dictionaryPath, dict -> scan(pairs dict, (name, symb) ->
            if x === symb and getGlobalSymbol name === symb then result =
    sort unique result)
-------------------------------------------------------------------------------
append(result, name)));

See also
========

  * dictionaryPath

Ways to use this method:
========================

  * findSynonyms(Symbol) -- find synonyms of
    symbols

fine control of a Groebner basis computation
********************************************

Sometimes a Groebner basis computation doesn't finish quickly enough.  If so
then this section might be of use. THIS PAGE IS UNDER CONSTRUCTION.

Partially computed Groebner bases
=================================

Suppose that you have computed part of a Groebner basis.  For example, you may
have interrupted the computation using CTRL-C (typing 'c' while holding the
CTRL key down, in emacs, you have to type CTRL-C twice), or you may have given
options requesting only partial computation.
+-----------------------------------------------------------------------------+
|i1 : R = ZZ/32003[a..e];                                                     |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(random(3,R),random(3,R),random(3,R))                          |
|                                                                             |
|                3        2           2        3        2                     |
|o2 = ideal (107a  + 4376a b - 5307a*b  - 6203b  - 5570a c + 8570a*b*c +      |
|     ------------------------------------------------------------------------|
|           2            2           2        3        2                      |
|     12365b c - 10480a*c  - 11950b*c  + 9534c  + 3187a d - 15344a*b*d -      |
|     ------------------------------------------------------------------------|
|           2                                  2           2          2       |
|     13508b d + 10359a*c*d + 8231b*c*d - 7216c d - 8251a*d  + 5026b*d  +     |
|     ------------------------------------------------------------------------|
|            2        3        2                     2                        |
|     7256c*d  + 9033d  + 3783a e + 8444a*b*e - 9480b e - 7464a*c*e +         |
|     ------------------------------------------------------------------------|
|                       2                                              2      |
|     5864b*c*e - 10125c e + 2653a*d*e + 10259b*d*e - 5321c*d*e + 5107d e +   |
|     ------------------------------------------------------------------------|
|            2          2          2          2        3        3         2   |
|     5071a*e  - 7501b*e  + 6230c*e  - 3996d*e  + 9398e , 13177a  + 13990a b +|
|     ------------------------------------------------------------------------|
|             2        3         2                     2           2          |
|     10866a*b  + 1031b  - 11521a c + 5398a*b*c - 2036b c + 2627a*c  -        |
|     ------------------------------------------------------------------------|
|            2        3        2                     2                        |
|     6922b*c  - 3589c  - 1309a d + 5549a*b*d - 6325b d - 5326a*c*d -         |
|     ------------------------------------------------------------------------|
|                      2           2          2           2        3        2 |
|     5080b*c*d - 5599c d + 5679a*d  + 8922b*d  + 13707c*d  + 8971d  - 1779a e|
|     ------------------------------------------------------------------------|
|                         2                                 2                 |
|     - 7061a*b*e - 11740b e + 2998a*c*e + 1236b*c*e + 4259c e - 7152a*d*e -  |
|     ------------------------------------------------------------------------|
|                                    2            2          2         2      |
|     5006b*d*e - 13892c*d*e - 14165d e + 15317a*e  + 8880b*e  - 994c*e  -    |
|     ------------------------------------------------------------------------|
|            2        3          3        2            2         3        2   |
|     3002d*e  + 2177e , - 10521a  - 1946a b - 11045a*b  - 15333b  - 7021a c +|
|     ------------------------------------------------------------------------|
|                       2           2          2        3        2            |
|     10370a*b*c - 7600b c - 7028a*c  - 3560b*c  + 5969c  + 1206a d -         |
|     ------------------------------------------------------------------------|
|                      2                               2           2          |
|     9702a*b*d - 6040b d - 15a*c*d - 7194b*c*d - 5483c d + 6377a*d  -        |
|     ------------------------------------------------------------------------|
|            2          2         3        2                     2            |
|     6627b*d  + 9074c*d  - 11726d  - 6453a e + 8886a*b*e - 3164b e -         |
|     ------------------------------------------------------------------------|
|                                  2                                          |
|     6723a*c*e - 7092b*c*e + 5874c e - 11435a*d*e + 4700b*d*e - 15250c*d*e + |
|     ------------------------------------------------------------------------|
|          2           2          2           2         2        3            |
|     8022d e - 1192a*e  + 9797b*e  + 10567c*e  + 295d*e  + 2292e )           |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : gens gb(I,PairLimit=>7);                                                |
|                                                                             |
|             1      7                                                        |
|o3 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
Get the Groebner basis object:
+---------------------------------------------+
|i4 : g = gb(I,StopBeforeComputation => true);|
+---------------------------------------------+
|i5 : leadTerm gens g                         |
|                                             |
|o5 = | ab2 a2b a3 b3c b4 abc3 a2c3 |         |
|                                             |
|             1      7                        |
|o5 : Matrix R  <-- R                         |
+---------------------------------------------+
We can make a Groebner basis snapshot by using StopBeforeComputation, or
gbSnapshot,:
+-----------------------------------------------------------------------------+
|i6 : gens gb(I,StopBeforeComputation => true)                                |
|                                                                             |
|o6 = | ab2-11391b3-5320a2c-13396abc-13493b2c-1240ac2+7608bc2-3232c3-1589a2d- |
|     ------------------------------------------------------------------------|
|     10031abd+4261b2d-8339acd+11672bcd-8273c2d+9919ad2+2784bd2-9469cd2-467d3+|
|     ------------------------------------------------------------------------|
|     10443a2e-8047abe-804b2e-8732ace-4103bce-11320c2e+15116ade+8081bde+      |
|     ------------------------------------------------------------------------|
|     13170cde+8155d2e+14681ae2+6840be2-4060ce2+4697de2-10579e3               |
|     ------------------------------------------------------------------------|
|     a2b-1245b3-6307a2c-11752abc+4739b2c-7117ac2+4604bc2-2102c3-1103a2d+     |
|     ------------------------------------------------------------------------|
|     14036abd+12312b2d+4931acd+10339bcd-8058c2d+11980ad2+8057bd2+13937cd2-   |
|     ------------------------------------------------------------------------|
|     85d3+14455a2e+8260abe+2037b2e+9647ace-15410bce+921c2e+9551ade-3204bde-  |
|     ------------------------------------------------------------------------|
|     8696cde+6879d2e+12651ae2-7056be2+10714ce2-1787de2+14941e3               |
|     ------------------------------------------------------------------------|
|     a3+8403b3-1190a2c-15323abc+13420b2c+6342ac2+15466bc2-3361c3-7950a2d-    |
|     ------------------------------------------------------------------------|
|     1838abd+14555b2d+12332acd+5108bcd+2903c2d-5539ad2-10429bd2-2305cd2-     |
|     ------------------------------------------------------------------------|
|     7937d3-1697a2e+9091abe+14609b2e-8778ace+9245bce+4957c2e-5753ade+10314bde|
|     ------------------------------------------------------------------------|
|     +1752cde+12225d2e+15200ae2-1840be2+2970ce2+7214de2-6578e3               |
|     ------------------------------------------------------------------------|
|     b3c+5081a2c2-8259abc2-14376b2c2+3188ac3-769bc3+9944c4-7494b3d+7852a2cd+ |
|     ------------------------------------------------------------------------|
|     10219abcd+4847b2cd+1132ac2d-7248bc2d-1825c3d-5344a2d2-6809abd2+11727b2d2|
|     ------------------------------------------------------------------------|
|     -3821acd2-12167bcd2-7415c2d2-5912ad3+8110bd3+4202cd3+1057d4-2905b3e+    |
|     ------------------------------------------------------------------------|
|     5014a2ce+6780abce+15730b2ce-14498ac2e+8288bc2e+8027c3e+4400a2de-2006abde|
|     ------------------------------------------------------------------------|
|     -11279b2de-12106acde+85bcde+4702c2de-6507ad2e+375bd2e+1276cd2e-75d3e+   |
|     ------------------------------------------------------------------------|
|     8509a2e2+11161abe2-1461b2e2-13786ace2+13233bce2-13146c2e2-4294ade2+     |
|     ------------------------------------------------------------------------|
|     2115bde2-8341cde2+6748d2e2-3680ae3-9994be3+13199ce3+9404de3-7442e4      |
|     ------------------------------------------------------------------------|
|     b4+8597a2c2+2008abc2+10927b2c2+11183ac3-2334bc3+2651c4-11800b3d-2247a2cd|
|     ------------------------------------------------------------------------|
|     -3514abcd-10663b2cd-4703ac2d+3223bc2d-31c3d-8220a2d2-14532abd2+9140b2d2-|
|     ------------------------------------------------------------------------|
|     15426acd2-8204bcd2+4041c2d2+1695ad3-12050bd3-9450cd3-1043d4-13002b3e+   |
|     ------------------------------------------------------------------------|
|     7568a2ce-8466abce+2203b2ce-520ac2e-10283bc2e+15655c3e-4914a2de+14891abde|
|     ------------------------------------------------------------------------|
|     +7008b2de+4316acde+5553bcde+13770c2de+14595ad2e-3748bd2e-3132cd2e-      |
|     ------------------------------------------------------------------------|
|     4247d3e+5929a2e2-223abe2-13618b2e2-4800ace2-14221bce2-10331c2e2+        |
|     ------------------------------------------------------------------------|
|     15289ade2+11676bde2+13221cde2+10864d2e2-3953ae3-12193be3-3354ce3-9362de3|
|     ------------------------------------------------------------------------|
|     +5003e4 abc3+14563b2c3+7076ac4-3805bc4-998c5-11331a2c2d+14001abc2d-     |
|     ------------------------------------------------------------------------|
|     9559b2c2d+13974ac3d+1972bc3d+7522c4d-15602b3d2-5593a2cd2-14073abcd2-    |
|     ------------------------------------------------------------------------|
|     9437b2cd2-3338ac2d2+3652bc2d2-7670c3d2+2680a2d3+8342abd3-14061b2d3+     |
|     ------------------------------------------------------------------------|
|     1909acd3+10705bcd3+6541c2d3+1512ad4-6422bd4+6813cd4+12171d5+849a2c2e-   |
|     ------------------------------------------------------------------------|
|     4307abc2e-11850b2c2e-11391ac3e-13420bc3e-15487c4e-959b3de-64a2cde+      |
|     ------------------------------------------------------------------------|
|     3520abcde+11428b2cde+6361ac2de-9883bc2de-8624c3de+2129a2d2e+15459abd2e- |
|     ------------------------------------------------------------------------|
|     9432b2d2e-11415acd2e-14940bcd2e+1863c2d2e-14855ad3e-14014bd3e-2661cd3e- |
|     ------------------------------------------------------------------------|
|     4619d4e-950b3e2+10361a2ce2-5000abce2+15729b2ce2+2961ac2e2-1806bc2e2-    |
|     ------------------------------------------------------------------------|
|     15236c3e2-4319a2de2-1113abde2+3734b2de2+7689acde2-1337bcde2-12800c2de2+ |
|     ------------------------------------------------------------------------|
|     13550ad2e2-312bd2e2+3671cd2e2-7034d3e2-14914a2e3-9352abe3-7633b2e3-     |
|     ------------------------------------------------------------------------|
|     8892ace3-5755bce3+7215c2e3-13530ade3-4610bde3-338cde3+8929d2e3-6303ae4- |
|     ------------------------------------------------------------------------|
|     9672be4-8826ce4-5872de4-14853e5                                         |
|     ------------------------------------------------------------------------|
|     a2c3+12817b2c3+4227ac4-1643bc4+11820c5+13424a2c2d+421abc2d-9343b2c2d-   |
|     ------------------------------------------------------------------------|
|     8104ac3d-208bc3d-2264c4d-4618b3d2-9256a2cd2-13197abcd2+12517b2cd2+      |
|     ------------------------------------------------------------------------|
|     8613ac2d2-10602bc2d2+8080c3d2-12173a2d3+7845abd3+11470b2d3-15645acd3+   |
|     ------------------------------------------------------------------------|
|     14068bcd3+1614c2d3-2477ad4+14757bd4-10489cd4+8593d5-8625a2c2e+547abc2e+ |
|     ------------------------------------------------------------------------|
|     9666b2c2e-7182ac3e+4055bc3e-2460c4e+11055b3de+15233a2cde-2278abcde+     |
|     ------------------------------------------------------------------------|
|     14497b2cde-8061ac2de+9802bc2de+14712c3de-8847a2d2e-2836abd2e+7338b2d2e+ |
|     ------------------------------------------------------------------------|
|     9402acd2e+10024bcd2e+15998c2d2e-3436ad3e+12062bd3e+7886cd3e+7886d4e+    |
|     ------------------------------------------------------------------------|
|     9628b3e2-6744a2ce2-1535abce2-1802b2ce2+10769ac2e2+269bc2e2-8136c3e2+    |
|     ------------------------------------------------------------------------|
|     1243a2de2-763abde2-6341b2de2-2584acde2+11620bcde2+10174c2de2+10935ad2e2+|
|     ------------------------------------------------------------------------|
|     6495bd2e2+4855cd2e2-12580d3e2+8827a2e3+15208abe3+11344b2e3+3458ace3-    |
|     ------------------------------------------------------------------------|
|     69bce3-4243c2e3+3442ade3-7654bde3-15312cde3+11297d2e3+14040ae4+10946be4+|
|     ------------------------------------------------------------------------|
|     15202ce4+14150de4+3493e5 |                                              |
|                                                                             |
|             1      7                                                        |
|o6 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i7 : leadTerm gbSnapshot(I)                                                  |
|                                                                             |
|o7 = | ab2 a2b a3 b3c b4 abc3 a2c3 |                                         |
|                                                                             |
|             1      7                                                        |
|o7 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+

first -- first element of a list
********************************

Synopsis
========

  * Usage:
        first L
  * Inputs:
      * L, a list, or Sequence,
  * Outputs:
      * f, a thing, the first element of L

Description
===========

+--------------------------+
|i1 : first {a,b,c,d,e}    |
|                          |
|o1 = a                    |
|                          |
|o1 : Symbol               |
+--------------------------+
|i2 : first gens(QQ[x,y,z])|
|                          |
|o2 = x                    |
|                          |
|o2 : QQ[x..z]             |
+--------------------------+

See also
========

  * last -- last element of a list
  * take -- Take some elements from a list or sequence.
  * select -- select from a list, hash table, or string
  * position -- the first element of a list satisfying a
    condition
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

For the programmer
==================

The object first, is a function closure.

firstkey -- get the first key
*****************************

Description
===========

firstkey f -- return the first key available in the database file f.

Returns null, if none.

See also
========

  * Database -- the class of all database files

For the programmer
==================

The object firstkey, is a compiled function.

fittingIdeal -- Fitting ideal of a module
*****************************************

Description
===========

fittingIdeal(i,M) -- the i-th Fitting ideal of the module M

+-----------------------------+
|i1 : R = ZZ/101[x];          |
+-----------------------------+
|i2 : k = coker vars R        |
|                             |
|o2 = cokernel | x |          |
|                             |
|                            1|
|o2 : R-module, quotient of R |
+-----------------------------+
|i3 : M = R^3 ++ k^5;         |
+-----------------------------+
|i4 : fittingIdeal(3,M)       |
|                             |
|            5                |
|o4 = ideal x                 |
|                             |
|o4 : Ideal of R              |
+-----------------------------+
|i5 : fittingIdeal(8,M)       |
|                             |
|o5 = ideal 1                 |
|                             |
|o5 : Ideal of R              |
+-----------------------------+

Ways to use fittingIdeal:
=========================

  * "fittingIdeal(ZZ,Module)"
  * fittingIdeal(ZZ,Matrix) (missing documentation)

For the programmer
==================

The object fittingIdeal, is a method function.

flagLookup -- flag a symbol
***************************

Synopsis
========

  * Usage:
        flagLookup x
  * Inputs:
      * x, a symbol,
  * Outputs:
      * a Boolean value, whether each subsequent reference to
        the symbol x will result in an error message
  * Consequences:
      * The first use arranges for each subsequent reference to the symbol x to
        result in an error message. The second use cancels the arrangement.
        Each subsequent use toggles the state.

Description
===========

To get access to a flagged symbol without signalling an error, use
getGlobalSymbol.

For the programmer
==================

The object flagLookup, is a compiled function.

FlatMonoid
**********

Synopsis
========

  * Usage:
        R.FlatMonoid
  * Inputs:
      * R, a polynomial ring,
  * Outputs:
      * a general ordered monoid, the flattened
        monoid in terms of which the polynomials are expressed when the
        coefficient ring of R is itself a polynomial ring

Description
===========

+-----------------------------------------------------------------------------+
|i1 : R = QQ[a,b][x]                                                          |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : R.FlatMonoid                                                            |
|                                                                             |
|o2 = monoid[x, a..b, Degrees => {{1}, 2:{0}}, Heft => {2:1}, MonomialOrder =>|
|                                 {0}    {1}                                  |
|                                                                             |
|                                                                             |
|                                                                             |
|o2 : GeneralOrderedMonoid                                                    |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32}]                                                        |
|{GRevLex => {1}    }                                                         |
|{Position => Up    }                                                         |
|{GRevLex => {2:1}  }                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * flattenRing -- write a ring as a (quotient of a)
    polynomial ring

For the programmer
==================

The object FlatMonoid, is a symbol.

flatten -- flatten a nested list or a matrix
********************************************

Synopsis
========

  * Usage:
        flatten x
  * Inputs:
      * x, a list, or Matrix,
  * Outputs:
      * a list, or matrix obtained by removing braces one level in

Description
===========

If x is a list, then flatten x effectively removes the braces surrounding any
elements of x that happen to be lists.

+-----------------------------------+
|i1 : flatten {{2,3,4}, {{5}, 6}, 7}|
|                                   |
|o1 = {2, 3, 4, {5}, 6, 7}          |
|                                   |
|o1 : List                          |
+-----------------------------------+

If x is a matrix, then flatten x puts the elements of x in a single row,
ordered by column. If x is an $m\times n$ matrix, then flatten x is a $1\times
mn$ matrix.

+-------------------------------------------+
|i2 : R = ZZ/101[a,b,c];                    |
+-------------------------------------------+
|i3 : m = matrix {{2, a},{b^2, 23},{c, c^3}}|
|                                           |
|o3 = | 2  a  |                             |
|     | b2 23 |                             |
|     | c  c3 |                             |
|                                           |
|             3      2                      |
|o3 : Matrix R  <-- R                       |
+-------------------------------------------+
|i4 : flatten m                             |
|                                           |
|o4 = | 2 b2 c a 23 c3 |                    |
|                                           |
|             1      6                      |
|o4 : Matrix R  <-- R                       |
+-------------------------------------------+

Caveat
======

The matrix produced by flatten m is not the same as the matrix given by
unnesting the list used to define the matrix.

See also
========

  * deepSplice -- remove all levels of subsequences from a
    sequence or list
  * splice -- remove subsequences from a sequence or list
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use flatten:
====================

  * "flatten(Matrix)"
  * "flatten(VisibleList)"

For the programmer
==================

The object flatten, is a method function with a single argument.

flattenRing -- write a ring as a (quotient of a) polynomial ring
****************************************************************

Synopsis
========

  * Usage:
        flattenRing R
        flattenRing I
        flattenRing G
  * Inputs:
      * R, a ring, OR
      * I, an ideal, OR
      * G, a Galois field,
  * Optional inputs,:
      * CoefficientRing,
        => ...,
        default value null, optionally specify the desired coefficient ring of
        the flattened ring
      * Result, => ...,
        default value (Thing,RingMap), optionally specify which output(s) to
        return (see Description for details)
  * Outputs:
      * S, a ring, a ring isomorphic to R, but represented as a
        (quotient of a) polynomial ring, or
      * J, an ideal, the ideal of S corresponding to (isomorphic
        to) I
      * F, a ring map, the isomorphism from R to S
      * G, a ring map, the isomorphism from S to R

Description
===========

Use flattenRing to get an isomorphic representation of a ring over a different
coefficient ring.

For instance the following ring $R$ is defined to have indeterminates $y,z$,
and coefficients in the quotient ring $\mathbb{Z}[x]/(x^2-3)$.

+---------------------------------------------------------+
|i1 : A = ZZ[x] / (x^2-3);  R = A[y,z] / (x*y^2-z^2, y^3);|
+---------------------------------------------------------+
|i3 : describe R                                          |
|                                                         |
|         A[y..z]                                         |
|o3 = ---------------                                     |
|         2    2   3                                      |
|     (x*y  - z , y )                                     |
+---------------------------------------------------------+

To work with the isomorphic ring $S = \mathbb{Z}[x,y,z]/(x^2-3,x*y^2-z^2,y^3)$
instead, use flattenRing.

+-------------------------------------------------------------------------+
|i4 : flattenRing R                                                       |
|                                                                         |
|            ZZ[y..z, x]                  ZZ[y..z, x]                     |
|o4 = (----------------------, map (----------------------, R, {y, z, x}))|
|        2       2     2   3          2       2     2   3                 |
|      (x  - 3, y x - z , y )       (x  - 3, y x - z , y )                |
|                                                                         |
|o4 : Sequence                                                            |
+-------------------------------------------------------------------------+

The default output is the sequence $(S, F)$, where $S$ is the flattened ring,
and $F$ is the RingMap, from $R$ to $S$. Here we demonstrate how
to store and use the map $F$.

+----------------------------+
|i5 : I = ideal(y^2 - 3*x*z) |
|                            |
|            2               |
|o5 = ideal(y  - 3x*z)       |
|                            |
|o5 : Ideal of R             |
+----------------------------+
|i6 : (S, F) = flattenRing R;|
+----------------------------+
|i7 : F(I)                   |
|                            |
|            2               |
|o7 = ideal(y  - 3z*x)       |
|                            |
|o7 : Ideal of S             |
+----------------------------+

Flattening an ideal instead of a quotient ring can save a lot of time spent
computing the Gröbner basis of the resulting ideal, if the flattened quotient
is not needed. Notice that the ring map in the following example is not the
same as the previous example; the following ring map is from $R$ to
$\mathbb{Z}[x,y,z]$, while the previous map was from $R$ to
$\mathbb{Z}[x,y,z]/(x^2-3,x*y^2-z^2,y^3)$.

+-----------------------------------------------------------------------------+
|i8 : A = ZZ[x] / (x^2-3);  R = A[y,z] / (x*y^2-z^2, y^3);                    |
+-----------------------------------------------------------------------------+
|i10 : I = ideal(y^2 - 3*x*z);                                                |
|                                                                             |
|o10 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i11 : (J, F) = flattenRing I                                                 |
|                                                                             |
|               2       2     2   3   2                                       |
|o11 = (ideal (x  - 3, y x - z , y , y  - 3z*x), map (ZZ[y..z, x], R, {y, z,  |
|      -----------------------------------------------------------------------|
|      x}))                                                                   |
|                                                                             |
|o11 : Sequence                                                               |
+-----------------------------------------------------------------------------+

flattenRing can also be used to represent GaloisField,s as
quotients of polynomial rings. If $K$ is the Galois field of order $p^n$,
flattenRing(K) will represent $K$ as a quotient of $\mathbb{Z}_p[a]$.

+----------------------------------------------+
|i12 : K = GF(5^3)                             |
|                                              |
|o12 = K                                       |
|                                              |
|o12 : GaloisField                             |
+----------------------------------------------+
|i13 : flattenRing K                           |
|                                              |
|          ZZ                ZZ                |
|          --[a]             --[a]             |
|           5                 5                |
|o13 = (-----------, map (-----------, K, {a}))|
|        3                 3                   |
|       a  - 2a - 2       a  - 2a - 2          |
|                                              |
|o13 : Sequence                                |
+----------------------------------------------+

Or, if a different variable was specified in the construction of $K$,
flattenRing K will follow suit.

+--------------------------------------------+
|i14 : L = GF(7, 5, Variable => z);          |
+--------------------------------------------+
|i15 : flattenRing L                         |
|                                            |
|          ZZ               ZZ               |
|          --[z]            --[z]            |
|           7                7               |
|o15 = (----------, map (----------, L, {z}))|
|        5                5                  |
|       z  + z - 3       z  + z - 3          |
|                                            |
|o15 : Sequence                              |
+--------------------------------------------+

Use Result => 1 to return the ring only. The default behavior is equivalent to
Return => 2. Use Result => 3 to return the ring, the isomorphism $F:R\to S$,
and the inverse map $F^{-1}:R\to S$.

+-----------------------------------------------------------------------------+
|i16 : flattenRing(R, Result => 1)                                            |
|                                                                             |
|            ZZ[y..z, x]                                                      |
|o16 = ----------------------                                                 |
|        2       2     2   3                                                  |
|      (x  - 3, y x - z , y )                                                 |
|                                                                             |
|o16 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i17 : flattenRing(R, Result => 2)                                            |
|                                                                             |
|             ZZ[y..z, x]                  ZZ[y..z, x]                        |
|o17 = (----------------------, map (----------------------, R, {y, z, x}))   |
|         2       2     2   3          2       2     2   3                    |
|       (x  - 3, y x - z , y )       (x  - 3, y x - z , y )                   |
|                                                                             |
|o17 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i18 : flattenRing(R, Result => 3)                                            |
|                                                                             |
|             ZZ[y..z, x]                  ZZ[y..z, x]                        |
|o18 = (----------------------, map (----------------------, R, {y, z, x}),   |
|         2       2     2   3          2       2     2   3                    |
|       (x  - 3, y x - z , y )       (x  - 3, y x - z , y )                   |
|      -----------------------------------------------------------------------|
|                    ZZ[y..z, x]                                              |
|      map (R, ----------------------, {y, z, x}))                            |
|                2       2     2   3                                          |
|              (x  - 3, y x - z , y )                                         |
|                                                                             |
|o18 : Sequence                                                               |
+-----------------------------------------------------------------------------+

These are the only numeric options for Result. However, we can also specify the
output(s) desired with a sequence of length 1, 2, or 3. The elements of the
sequence correspond to the Result => 1, Result => 2, and Result => 3 output
sequences, respectively. Any element of the sequence can be suppressed by
asking for Nothing instead. For example, to return the map $F$ only, we ask for
the sequence of length 2, $(S, F)$, but suppress $S$:

+--------------------------------------------------+
|i19 : flattenRing(R, Result => (Nothing, RingMap))|
|                                                  |
|o19 = (, map (ZZ[y..z, x], R, {y, z, x}))         |
|                                                  |
|o19 : Sequence                                    |
+--------------------------------------------------+

Note that Result => RingMap is NOT a valid way to return $F$ only, because an
output of length 1 can only have a ring or an ideal.

Similarly, to return $S$ and $F^{-1}$ only:

+----------------------------------------------------------------------------+
|i20 : flattenRing(R, Result => (Ring, Nothing, RingMap))                    |
|                                                                            |
|             ZZ[y..z, x]                       ZZ[y..z, x]                  |
|o20 = (----------------------, , map (R, ----------------------, {y, z, x}))|
|         2       2     2   3               2       2     2   3              |
|       (x  - 3, y x - z , y )            (x  - 3, y x - z , y )             |
|                                                                            |
|o20 : Sequence                                                              |
+----------------------------------------------------------------------------+

Omitting an element of the sequence is equivalent to asking for it to be
returned.

+----------------------------------------------------------------------------+
|i21 : flattenRing(R, Result => (Nothing, ))                                 |
|                                                                            |
|o21 = (, map (ZZ[y..z, x], R, {y, z, x}))                                   |
|                                                                            |
|o21 : Sequence                                                              |
+----------------------------------------------------------------------------+
|i22 : flattenRing(R, Result => ( , Nothing, ) )                             |
|                                                                            |
|             ZZ[y..z, x]                       ZZ[y..z, x]                  |
|o22 = (----------------------, , map (R, ----------------------, {y, z, x}))|
|         2       2     2   3               2       2     2   3              |
|       (x  - 3, y x - z , y )            (x  - 3, y x - z , y )             |
|                                                                            |
|o22 : Sequence                                                              |
+----------------------------------------------------------------------------+

When running flattenRing(Ideal), there are additional choices for the Result
option: the first element of the sequence, which is always the ring in the
flattenRing(Ring) case, can now be either the new ring or the corresponding new
ideal. The default is to return the ideal, including when using numeric options
for Result or omitting an object type in the sequence.

+-----------------------------------------------------------------------------+
|i23 : flattenRing(I, Result => 1)                                            |
|                                                                             |
|              2       2     2   3   2                                        |
|o23 = ideal (x  - 3, y x - z , y , y  - 3z*x)                                |
|                                                                             |
|o23 : Ideal of ZZ[y..z, x]                                                   |
+-----------------------------------------------------------------------------+
|i24 : flattenRing(I, Result => 3)                                            |
|                                                                             |
|               2       2     2   3   2                                       |
|o24 = (ideal (x  - 3, y x - z , y , y  - 3z*x), map (ZZ[y..z, x], R, {y, z,  |
|      -----------------------------------------------------------------------|
|      x}), map (R, ZZ[y..z, x], {y, z, x}))                                  |
|                                                                             |
|o24 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i25 : flattenRing(R, Result => ( , Nothing, ) )                              |
|                                                                             |
|             ZZ[y..z, x]                       ZZ[y..z, x]                   |
|o25 = (----------------------, , map (R, ----------------------, {y, z, x})) |
|         2       2     2   3               2       2     2   3               |
|       (x  - 3, y x - z , y )            (x  - 3, y x - z , y )              |
|                                                                             |
|o25 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i26 : flattenRing(I, Result => (Ring, Nothing, RingMap))                     |
|                                                                             |
|                  ZZ[y..z, x]                                                |
|o26 = (---------------------------------, , map (R,                          |
|         2       2     2   3   2                                             |
|       (x  - 3, y x - z , y , y  - 3z*x)                                     |
|      -----------------------------------------------------------------------|
|                 ZZ[y..z, x]                                                 |
|      ---------------------------------, {y, z, x}))                         |
|        2       2     2   3   2                                              |
|      (x  - 3, y x - z , y , y  - 3z*x)                                      |
|                                                                             |
|o26 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i27 : flattenRing(I, Result => (Ring, RingMap))                              |
|                                                                             |
|                  ZZ[y..z, x]                                                |
|o27 = (---------------------------------, map                                |
|         2       2     2   3   2                                             |
|       (x  - 3, y x - z , y , y  - 3z*x)                                     |
|      -----------------------------------------------------------------------|
|                  ZZ[y..z, x]                                                |
|      (---------------------------------, R, {y, z, x}))                     |
|         2       2     2   3   2                                             |
|       (x  - 3, y x - z , y , y  - 3z*x)                                     |
|                                                                             |
|o27 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i28 : flattenRing(I, Result => Ideal)                                        |
|                                                                             |
|              2       2     2   3   2                                        |
|o28 = ideal (x  - 3, y x - z , y , y  - 3z*x)                                |
|                                                                             |
|o28 : Ideal of ZZ[y..z, x]                                                   |
+-----------------------------------------------------------------------------+

By default flattenRing attempts to define a new ring over either ZZ or a base
field.

In the following example, the coefficient ring of the result is the fraction
field $K$.

+--------------------------------------------+
|i29 : K = frac(ZZ[a])                       |
|                                            |
|o29 = K                                     |
|                                            |
|o29 : FractionField                         |
+--------------------------------------------+
|i30 : B = K[x,y,z]/(a*x^2-y^2-z^2, y^3, z^3)|
|                                            |
|o30 = B                                     |
|                                            |
|o30 : QuotientRing                          |
+--------------------------------------------+
|i31 : (D, F) = flattenRing B                |
|                                            |
|o31 = (B, map (B, B, {x, y, z, a}))         |
|                                            |
|o31 : Sequence                              |
+--------------------------------------------+
|i32 : describe D                            |
|                                            |
|               K[x..z]                      |
|o32 = ------------------------              |
|          2    2    2   3   3               |
|      (a*x  - y  - z , y , z )              |
+--------------------------------------------+

Once a ring has been declared to be a field with toField,
then it will be used as the coefficient ring.

+-----------------------------------------------+
|i33 : A = QQ[a]/(a^2-3);                       |
+-----------------------------------------------+
|i34 : L = toField A                            |
|                                               |
|o34 = L                                        |
|                                               |
|o34 : PolynomialRing                           |
+-----------------------------------------------+
|i35 : B = L[x,y,z]/(a*x^2-y^2-z^2, y^3, z^3)   |
|                                               |
|o35 = B                                        |
|                                               |
|o35 : QuotientRing                             |
+-----------------------------------------------+
|i36 : (D, F) = flattenRing(B[s,t])             |
|                                               |
|o36 = (D, map (D, B[s..t], {s, t, x, y, z, a}))|
|                                               |
|o36 : Sequence                                 |
+-----------------------------------------------+
|i37 : describe D                               |
|                                               |
|            L[s..t, x..z]                      |
|o37 = ------------------------                 |
|          2    2    2   3   3                  |
|      (a*x  - y  - z , y , z )                 |
+-----------------------------------------------+

Use the CoefficientRing option to specify a different base field or ring.

+---------------------------------------------------------+
|i38 : (D, F) = flattenRing(B[s,t], CoefficientRing => QQ)|
|                                                         |
|o38 = (D, map (D, B[s..t], {s, t, x, y, z, a}))          |
|                                                         |
|o38 : Sequence                                           |
+---------------------------------------------------------+
|i39 : describe D                                         |
|                                                         |
|             QQ[s..t, x..z, a]                           |
|o39 = -------------------------------                    |
|        2       2     2    2   3   3                     |
|      (a  - 3, x a - y  - z , y , z )                    |
+---------------------------------------------------------+

Here is a more complicated example.

+--------------------------------------------------------+
|i40 : use L                                             |
|                                                        |
|o40 = L                                                 |
|                                                        |
|o40 : PolynomialRing                                    |
+--------------------------------------------------------+
|i41 : C1 = L[s,t];                                      |
+--------------------------------------------------------+
|i42 : C2 = C1/(a*s-t^2);                                |
+--------------------------------------------------------+
|i43 : C3 = C2[p_0..p_4]/(a*s*p_0)[q]/(q^2-a*p_1);       |
+--------------------------------------------------------+
|i44 : (D, F) = flattenRing(C3, CoefficientRing=>C2)     |
|                                                        |
|o44 = (D, map (D, C3, {q, p , p , p , p , p , s, t, a}))|
|                           0   1   2   3   4            |
|                                                        |
|o44 : Sequence                                          |
+--------------------------------------------------------+
|i45 : describe D                                        |
|                                                        |
|         C2[q, p ..p ]                                  |
|                0   4                                   |
|o45 = -------------------                               |
|                2                                       |
|      (a*s*p , q  - a*p )                               |
|            0          1                                |
+--------------------------------------------------------+
|i46 : (D, F) = flattenRing(C3, CoefficientRing=>QQ)     |
|                                                        |
|o46 = (D, map (D, C3, {q, p , p , p , p , p , s, t, a}))|
|                           0   1   2   3   4            |
|                                                        |
|o46 : Sequence                                          |
+--------------------------------------------------------+
|i47 : describe D                                        |
|                                                        |
|              QQ[q, p ..p , s..t, a]                    |
|                     0   4                              |
|o47 = -------------------------------------             |
|        2         2                2                    |
|      (a  - 3, - t  + s*a, p s*a, q  - p a)             |
|                            0           1               |
+--------------------------------------------------------+

Multiple calls to flattenRing may result in defining multiple rings that are
regarded as different objects by Macaulay2. (See rings, or
working with multiple rings, for more
information.)

+-------------------------------------------------+
|i48 : flattenRing(B[s,t]) === flattenRing(B[s,t])|
|                                                 |
|o48 = false                                      |
+-------------------------------------------------+

See also
========

  * coefficientRing -- get the coefficient ring
  * describe -- real description
  * GF -- make a finite field
  * lift -- lift to another ring
  * presentation -- presentation of a module or ring
  * promote -- promote to another ring
  * toField -- declare that a ring is a field
  * trim -- minimize generators and relations
  * finite fields
  * rings
  * working with multiple rings

Ways to use flattenRing:
========================

  * "flattenRing(GaloisField)"
  * "flattenRing(Ideal)"
  * "flattenRing(PolynomialRing)"
  * "flattenRing(QuotientRing)"
  * "flattenRing(Ring)"

For the programmer
==================

The object flattenRing, is a method function with options.

flattenRing(...,CoefficientRing=>...) -- optionally specify the desired coefficient ring of the flattened ring
**************************************************************************************************************

Description
===========

Use this option to change the default behavior of flattenRing,
by setting the option to the desired coefficientRing,
of the output ring.

+------------------------------------------------------------------+
|i1 : k = toField (QQ[x]/(x^2+x+1));                               |
+------------------------------------------------------------------+
|i2 : R = k[y]/(x-y+2);                                            |
+------------------------------------------------------------------+
|i3 : (S, f) = flattenRing(R); describe S                          |
|                                                                  |
|         k[y]                                                     |
|o4 = -----------                                                  |
|     - y + x + 2                                                  |
+------------------------------------------------------------------+
|i5 : (S2, f2) = flattenRing(R, CoefficientRing => QQ); describe S2|
|                                                                  |
|              QQ[y, x]                                            |
|o6 = -------------------------                                    |
|       2                                                          |
|     (x  + x + 1, - y + x + 2)                                    |
+------------------------------------------------------------------+

See flattenRing, documentation for more examples and
details.

Further information
===================

  * Default value: null
  * Function: flattenRing, -- write a ring as a (quotient of
    a) polynomial ring
  * Option key: CoefficientRing, -- an optional argument

See also
========

  * flattenRing -- write a ring as a (quotient of a)
    polynomial ring

Functions with optional argument named CoefficientRing:
=======================================================

  * flattenRing(...,CoefficientRing=>...)
    -- optionally
    specify the desired coefficient ring of the flattened ring
  * "generators(...,CoefficientRing=>...)" -- see generators(Ring),
    -- the list of generators of a ring
  * "Grassmannian(...,CoefficientRing=>...)" -- see Grassmannian(ZZ,ZZ),
    -- the Grassmannian of linear subspaces of a
    vector space
  * "Schubert(...,CoefficientRing=>...)" -- see
    Schubert(ZZ,ZZ,VisibleList), -- find
    the Plücker ideal of a Schubert variety

flattenRing(...,Result=>...) -- optionally specify which output(s) to return (see Description for details)
**********************************************************************************************************

Description
===========

The flattenRing, documentation goes into much greater detail
about the Result option. This node has some examples only.

+-----------------------------------------------------------------------------+
|i1 : k = toField (QQ[x]/(x^2+x+1));                                          |
+-----------------------------------------------------------------------------+
|i2 : R = k[y]/(x-y+2);                                                       |
+-----------------------------------------------------------------------------+
|i3 : flattenRing(R, Result => 1)                                             |
|                                                                             |
|o3 = R                                                                       |
|                                                                             |
|o3 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i4 : flattenRing(R, Result => 2)                                             |
|                                                                             |
|o4 = (R, map (R, R, {x + 2, x}))                                             |
|                                                                             |
|o4 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i5 : flattenRing(R, Result => 3)                                             |
|                                                                             |
|o5 = (R, map (R, R, {x + 2, x}), map (R, R, {x + 2, x}))                     |
|                                                                             |
|o5 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i6 : flattenRing(R, Result => (Nothing, RingMap))                            |
|                                                                             |
|o6 = (, map (k[y], R, {x + 2, x}))                                           |
|                                                                             |
|o6 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i7 : flattenRing(R, Result => (Ring, Nothing, RingMap))                      |
|                                                                             |
|o7 = (R, , map (R, R, {x + 2, x}))                                           |
|                                                                             |
|o7 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i8 : flattenRing(R, Result => (Nothing, ))                                   |
|                                                                             |
|o8 = (, map (k[y], R, {x + 2, x}))                                           |
|                                                                             |
|o8 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i9 : flattenRing(R, Result => ( , Nothing, ) )                               |
|                                                                             |
|o9 = (R, , map (R, R, {x + 2, x}))                                           |
|                                                                             |
|o9 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i10 : I = ideal(x*y+y^2-5);                                                  |
|                                                                             |
|o10 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i11 : flattenRing(I, Result => 1)                                            |
|                                                                             |
|o11 = ideal (- y + x + 2, 4x - 3)                                            |
|                                                                             |
|o11 : Ideal of k[y]                                                          |
+-----------------------------------------------------------------------------+
|i12 : flattenRing(I, Result => 3)                                            |
|                                                                             |
|o12 = (ideal (- y + x + 2, 4x - 3), map (k[y], R, {x + 2, x}), map (R, k[y], |
|      -----------------------------------------------------------------------|
|      {x + 2, x}))                                                           |
|                                                                             |
|o12 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i13 : flattenRing(I, Result => (Ring, Nothing, RingMap))                     |
|                                                                             |
|                k[y]                             k[y]                        |
|o13 = (---------------------, , map (R, ---------------------, {x + 2, x}))  |
|       (- y + x + 2, 4x - 3)            (- y + x + 2, 4x - 3)                |
|                                                                             |
|o13 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i14 : flattenRing(I, Result => (Ideal, Nothing, RingMap))                    |
|                                                                             |
|o14 = (ideal (- y + x + 2, 4x - 3), , map (R, k[y], {x + 2, x}))             |
|                                                                             |
|o14 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i15 : flattenRing(I, Result => (Ring, RingMap))                              |
|                                                                             |
|                k[y]                        k[y]                             |
|o15 = (---------------------, map (---------------------, R, {0, 0}))        |
|       (- y + x + 2, 4x - 3)       (- y + x + 2, 4x - 3)                     |
|                                                                             |
|o15 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i16 : flattenRing(I, Result => Ideal)                                        |
|                                                                             |
|o16 = ideal (- y + x + 2, 4x - 3)                                            |
|                                                                             |
|o16 : Ideal of k[y]                                                          |
+-----------------------------------------------------------------------------+

Further information
===================

  * Default value: (Thing,RingMap)
  * Function: flattenRing, -- write a ring as a (quotient of
    a) polynomial ring
  * Option key: Result, -- an optional argument

See also
========

  * flattenRing -- write a ring as a (quotient of a)
    polynomial ring

Functions with optional argument named Result:
==============================================

  * flattenRing(...,Result=>...)
    -- optionally specify which
    output(s) to return (see Description for details)

flip -- isomorphism map of commutativity of tensor product
**********************************************************

Synopsis
========

  * Usage:
        flip(F, G)
  * Inputs:
      * F, a module,
      * G, a module,
  * Outputs:
      * a matrix, the matrix representing the natural
        isomorphism $F \otimes G \to G \otimes F$

Description
===========

+--------------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                         |
+--------------------------------------------------------------------------+
|i2 : F = R^{1,2,3}                                                        |
|                                                                          |
|      3                                                                   |
|o2 = R                                                                    |
|                                                                          |
|o2 : R-module, free, degrees {-1, -2, -3}                                 |
+--------------------------------------------------------------------------+
|i3 : G = R^{10,20,30}                                                     |
|                                                                          |
|      3                                                                   |
|o3 = R                                                                    |
|                                                                          |
|o3 : R-module, free, degrees {-10, -20, -30}                              |
+--------------------------------------------------------------------------+
|i4 : f = flip(F,G)                                                        |
|                                                                          |
|o4 = {-11} | 1 0 0 0 0 0 0 0 0 |                                          |
|     {-12} | 0 0 0 1 0 0 0 0 0 |                                          |
|     {-13} | 0 0 0 0 0 0 1 0 0 |                                          |
|     {-21} | 0 1 0 0 0 0 0 0 0 |                                          |
|     {-22} | 0 0 0 0 1 0 0 0 0 |                                          |
|     {-23} | 0 0 0 0 0 0 0 1 0 |                                          |
|     {-31} | 0 0 1 0 0 0 0 0 0 |                                          |
|     {-32} | 0 0 0 0 0 1 0 0 0 |                                          |
|     {-33} | 0 0 0 0 0 0 0 0 1 |                                          |
|                                                                          |
|             9      9                                                     |
|o4 : Matrix R  <-- R                                                      |
+--------------------------------------------------------------------------+
|i5 : isHomogeneous f                                                      |
|                                                                          |
|o5 = true                                                                 |
+--------------------------------------------------------------------------+
|i6 : target f                                                             |
|                                                                          |
|      9                                                                   |
|o6 = R                                                                    |
|                                                                          |
|o6 : R-module, free, degrees {-11, -12, -13, -21, -22, -23, -31, -32, -33}|
+--------------------------------------------------------------------------+
|i7 : source f                                                             |
|                                                                          |
|      9                                                                   |
|o7 = R                                                                    |
|                                                                          |
|o7 : R-module, free, degrees {-11, -21, -31, -12, -22, -32, -13, -23, -33}|
+--------------------------------------------------------------------------+
|i8 : target f === G**F                                                    |
|                                                                          |
|o8 = true                                                                 |
+--------------------------------------------------------------------------+
|i9 : source f === F**G                                                    |
|                                                                          |
|o9 = true                                                                 |
+--------------------------------------------------------------------------+
|i10 : u = x * F_0                                                         |
|                                                                          |
|o10 = | x |                                                               |
|      | 0 |                                                               |
|      | 0 |                                                               |
|                                                                          |
|       3                                                                  |
|o10 : R                                                                   |
+--------------------------------------------------------------------------+
|i11 : v = y * G_1                                                         |
|                                                                          |
|o11 = | 0 |                                                               |
|      | y |                                                               |
|      | 0 |                                                               |
|                                                                          |
|       3                                                                  |
|o11 : R                                                                   |
+--------------------------------------------------------------------------+
|i12 : u ** v                                                              |
|                                                                          |
|o12 = |  0 |                                                              |
|      | xy |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|                                                                          |
|       9                                                                  |
|o12 : R                                                                   |
+--------------------------------------------------------------------------+
|i13 : v ** u                                                              |
|                                                                          |
|o13 = |  0 |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|      | xy |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|                                                                          |
|       9                                                                  |
|o13 : R                                                                   |
+--------------------------------------------------------------------------+
|i14 : f * (u ** v)                                                        |
|                                                                          |
|o14 = |  0 |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|      | xy |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|      |  0 |                                                              |
|                                                                          |
|       9                                                                  |
|o14 : R                                                                   |
+--------------------------------------------------------------------------+
|i15 : f * (u ** v) === v ** u                                             |
|                                                                          |
|o15 = true                                                                |
+--------------------------------------------------------------------------+

Ways to use flip:
=================

  * "flip(Module,Module)"

For the programmer
==================

The object flip, is a method function.

floor -- floor function
***********************

See also
========

  * ceiling -- ceiling function

Ways to use floor:
==================

  * "floor(Constant)" -- see floor(Number), -- floor
    function
  * floor(Number) -- floor function

For the programmer
==================

The object floor, is a method function.

floor(Number) -- floor function
*******************************

Synopsis
========

  * Function: floor,
  * Usage:
        floor x
  * Inputs:
      * x
  * Outputs:
      * the greatest integer less than or equal to the number x.  The imaginary
        part of a complex number is ignored.

Description
===========

+--------------------------------+
|i1 : floor (7.234232131231*10^6)|
|                                |
|o1 = 7234232                    |
+--------------------------------+

See also
========

  * ceiling(Number) -- ceiling function
  * truncate(Number) -- round a number toward zero

Ways to use this method:
========================

  * "floor(Constant)"
  * floor(Number) -- floor function

flush -- flush output to file
*****************************

Description
===========

f << flush -- writes out any buffered output for the output file f.

Ways to use flush:
==================

  * "File << Manipulator" -- see File << Thing, -- print
    to a file
  * "Nothing << Manipulator" -- see File << Thing, --
    print to a file
  * "Manipulator Database" -- see Manipulator, -- the class
    of all file manipulators
  * "Manipulator File" -- see Manipulator, -- the class of
    all file manipulators
  * "Manipulator Nothing" -- see Manipulator, -- the class
    of all file manipulators
  * "new Manipulator from Function" -- see Manipulator, --
    the class of all file manipulators
  * "methods(Manipulator)" -- see methods, -- list methods
  * "Manipulator NetFile" -- see NetFile, -- the class of all
    net files
  * "NetFile << Manipulator" -- see NetFile, -- the class of all
    net files

For the programmer
==================

The object flush, is a manipulator.

fold -- apply a binary operator repeatedly
******************************************

Synopsis
========

  * Usage:
        fold(f, x, L)
        fold(f, L)
        fold(L, x, f)
        fold(L, f)
  * Inputs:
      * f, a function,
      * x, a thing,
      * L, a visible list, or an instance of a class with
        the iterator, method installed
  * Outputs:
      * M, a list,

Description
===========

Suppose L=\{x0, x1, ..., xn\}. Then for any binary operator f, fold(f, L)
computes f(...f(f(x0, x1), x2), ...). In other words, the binary operator is
applied to the first two elements of L, then to that result along with the next
unused element of L, and so forth.

+------------------------------------------------+
|i1 : fold(plus, {0,1,2,3,4,5})                  |
|                                                |
|o1 = 15                                         |
+------------------------------------------------+
|i2 : fold(identity, {a,b,c,d,e})                |
|                                                |
|o2 = ((((a, b), c), d), e)                      |
|                                                |
|o2 : Sequence                                   |
+------------------------------------------------+
|i3 : fold((i,j) -> i|j|i, {"a","b","c","d","e"})|
|                                                |
|o3 = abacabadabacabaeabacabadabacaba            |
+------------------------------------------------+

If fold(f, x, L) is called, the element x is used as the first argument of the
binary function f. In other words, fold(f, \{x0, x1, \ldots, xn\}) is
equivalent to fold(f, x0, \{x1, \ldots, xn\}).

+--------------------------------------+
|i4 : fold(plus, 0, {1,2,3,4,5})       |
|                                      |
|o4 = 15                               |
+--------------------------------------+
|i5 : fold((x, y) -> x^y, 2, {3,2,1,2})|
|                                      |
|o5 = 4096                             |
+--------------------------------------+

The function fold(\{x_0, x_1, \ldots, x_n\}, f) returns f...f(f(x_{n-2},
f(x_{n-1}, x_n))). That is, f is applied to the last two elements of the list
first, then the repeated calls to f proceed backwards through the list. The
optional argument x in fold(L, x, f) is used as the second argument in the
first evaluation of f. So fold(\{x_0, x_1, \ldots, x_{n-1}\}, x_n, f) is
equivalent to fold(\{x_0, x_1, \ldots, x_n\}, f).

+--------------------------------------+
|i6 : fold({a,b,c,d,e}, identity)      |
|                                      |
|o6 = (a, (b, (c, (d, e))))            |
|                                      |
|o6 : Sequence                         |
+--------------------------------------+
|i7 : fold({a,b,c,d}, e, identity)     |
|                                      |
|o7 = (a, (b, (c, (d, e))))            |
|                                      |
|o7 : Sequence                         |
+--------------------------------------+
|i8 : fold({2,3,2,1}, 2, (x, y) -> x^y)|
|                                      |
|o8 = 512                              |
+--------------------------------------+

If L is an instance of class the the iterator, method
installed, e.g., a string, then it may also be used with fold, but only the
versions with f as the first argument.

+---------------------------------+
|i9 : fold(identity, "abcde")     |
|                                 |
|o9 = ((((a, b), c), d), e)       |
|                                 |
|o9 : Sequence                    |
+---------------------------------+
|i10 : fold(identity, "a", "bcde")|
|                                 |
|o10 = ((((a, b), c), d), e)      |
|                                 |
|o10 : Sequence                   |
+---------------------------------+

The difference between fold, and accumulate is that fold returns
the final result of all the nested evaluations of f, while accumulate lists all
the intermediate values as well.

+---------------------------------------------+
|i11 : accumulate({2,3,2,1}, 2, (x, y) -> x^y)|
|                                             |
|o11 = {512, 9, 2, 1}                         |
|                                             |
|o11 : List                                   |
+---------------------------------------------+

See also
========

  * apply -- apply a function to each element
  * accumulate -- apply a binary operator repeatedly
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use fold:
=================

  * "fold(Function,Thing)"
  * "fold(Function,Thing,Thing)"
  * "fold(Function,VisibleList)"
  * "fold(VisibleList,Function)"
  * "fold(VisibleList,Thing,Function)"

For the programmer
==================

The object fold, is a method function.

forceGB -- declare that the columns of a matrix are a Gröbner basis
*******************************************************************

Synopsis
========

  * Usage:
        forceGB f
  * Inputs:
      * f, a matrix,
  * Optional inputs,:
      * ChangeMatrix,
        => ..., default value null, inform Macaulay2 about the change of basis
        matrix from GB to generators
      * MinimalMatrix,
        => ..., default value null, specify the minimal generator matrix
      * SyzygyMatrix,
        => ..., default value null, specify the syzygy matrix
  * Outputs:
      * a Gröbner basis,

Description
===========

Declares that the columns of the matrix f constitute a Gröbner basis,
autoreduces it, minimizes it, sorts it, and returns a Gröbner basis object
declaring itself complete, without computing any S-pairs.

Sometimes one knows that a set of polynomials (or columns of such) form a
Gröbner basis, but Macaulay2 doesn't.  This is the way to inform the system of
this fact.
+--------------------------------------------------------------------+
|i1 : gbTrace = 3;                                                   |
+--------------------------------------------------------------------+
|i2 : R = ZZ[x,y,z];                                                 |
+--------------------------------------------------------------------+
|i3 : f = matrix{{x^2-3, y^3-1, z^4-2}};                             |
|                                                                    |
|             1      3                                               |
|o3 : Matrix R  <-- R                                                |
+--------------------------------------------------------------------+
|i4 : g = forceGB f                                                  |
|                                                                    |
|o4 = GroebnerBasis[status: done; S-pairs encountered up to degree 0]|
|                                                                    |
|o4 : GroebnerBasis                                                  |
+--------------------------------------------------------------------+
This Gröbner basis object is stored with the matrix and can be obtained as
usual:
+---------------------------------------------+
|i5 : g === gb(f, StopBeforeComputation=>true)|
|                                             |
|o5 = true                                    |
+---------------------------------------------+
Requesting a Gröbner basis for f requires no computation.
+-----------------------+
|i6 : gens gb f         |
|                       |
|o6 = | x2-3 y3-1 z4-2 ||
|                       |
|             1      3  |
|o6 : Matrix R  <-- R   |
+-----------------------+

If an autoreduced Gröbner basis is desired, replace f by gens forceGB f first.

Caveat
======

If the columns do not form a Gröbner basis, nonsensical answers may result

See also
========

  * Gröbner bases

Ways to use forceGB:
====================

  * "forceGB(Matrix)"

For the programmer
==================

The object forceGB, is a method function with options.

forceGB(...,ChangeMatrix=>...) -- inform Macaulay2 about the change of basis matrix from GB to generators
*********************************************************************************************************

Synopsis
========

  * Usage:
        forceGB(...,ChangeMatrix=>m)
  * Inputs:
      * m, a matrix,
  * Consequences:
      * Set the change of basis matrix from the Gröbner basis to the original
        generators

Description
===========

The matrix m should have size a by b, where a is the number of columns of the
original matrix, and b is the number of columns of f.
+-------------------------------------------------+
|i1 : gbTrace = 3                                 |
|                                                 |
|o1 = 3                                           |
+-------------------------------------------------+
|i2 : R = ZZ[x,y,z];                              |
+-------------------------------------------------+
|i3 : f = matrix{{x^2-3, y^3-1, z^4-2}};          |
|                                                 |
|             1      3                            |
|o3 : Matrix R  <-- R                             |
+-------------------------------------------------+
|i4 : g = forceGB(f, ChangeMatrix=>id_(source f));|
+-------------------------------------------------+
|i5 : x^2*y^3 // g                                |
|                                                 |
|o5 = {2} | y3 |                                  |
|     {3} | 3  |                                  |
|     {4} | 0  |                                  |
|                                                 |
|             3      1                            |
|o5 : Matrix R  <-- R                             |
+-------------------------------------------------+

Further information
===================

  * Default value: null
  * Function: forceGB, -- declare that the columns of a matrix
    are a Gröbner basis
  * Option key: ChangeMatrix, -- an optional argument

Functions with optional argument named ChangeMatrix:
====================================================

  * forceGB(...,ChangeMatrix=>...)
    -- inform Macaulay2 about
    the change of basis matrix from GB to generators
  * "gb(...,ChangeMatrix=>...)" -- see gb, -- compute a Gröbner basis
  * hermite(...,ChangeMatrix=>...) (missing documentation)
  * LLL(...,ChangeMatrix=>...) (LLLBases)
    -- also find change
    of basis matrix
  * "markedGB(...,ChangeMatrix=>...)" -- see markedGB(Matrix,Matrix),
    -- make a marked Gröbner basis
  * "smithNormalForm(...,ChangeMatrix=>...)" -- see
    smithNormalForm(Matrix), -- smith normal form
    for a matrix over ZZ or a PID

forceGB(...,MinimalMatrix=>...) -- specify the minimal generator matrix
***********************************************************************

Further information
===================

  * Default value: null
  * Function: forceGB, -- declare that the columns of a matrix
    are a Gröbner basis
  * Option key: MinimalMatrix, -- an optional argument

Functions with optional argument named MinimalMatrix:
=====================================================

  * forceGB(...,MinimalMatrix=>...)
    -- specify the minimal
    generator matrix
  * "markedGB(...,MinimalMatrix=>...)" -- see markedGB(Matrix,Matrix),
    -- make a marked Gröbner basis

forceGB(...,SyzygyMatrix=>...) -- specify the syzygy matrix
***********************************************************

Synopsis
========

  * Usage:
        forceGB(f,SyzygyMatrix=>z,...)
  * Inputs:
      * z, a matrix,
  * Consequences:
      * A request for the syzygy matrix of f will return z

Description
===========

In the following example, the only computation being performed when asked to
compute the kernel, or syz, of f is the minimal
generator matrix of z.
+-----------------------------------------------------------------------------+
|i1 : gbTrace = 3                                                             |
|                                                                             |
|o1 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i2 : R = ZZ[x,y,z];                                                          |
+-----------------------------------------------------------------------------+
|i3 : f = matrix{{x^2-3, y^3-1, z^4-2}};                                      |
|                                                                             |
|             1      3                                                        |
|o3 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i4 : z = koszul(2,f)                                                         |
|                                                                             |
|o4 = {2} | -y3+1 -z4+2 0     |                                               |
|     {3} | x2-3  0     -z4+2 |                                               |
|     {4} | 0     x2-3  y3-1  |                                               |
|                                                                             |
|             3      3                                                        |
|o4 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i5 : g = forceGB(f, SyzygyMatrix=>z);                                        |
+-----------------------------------------------------------------------------+
|i6 : syz g -- no extra computation                                           |
|                                                                             |
|o6 = {2} | -y3+1 -z4+2 0     |                                               |
|     {3} | x2-3  0     -z4+2 |                                               |
|     {4} | 0     x2-3  y3-1  |                                               |
|                                                                             |
|             3      3                                                        |
|o6 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i7 : syz f                                                                   |
|                                                                             |
|   -- registering gb 0 at 0x78b91a4b9000                                     |
|                                                                             |
|   -- [gb]{2}(1)m{3}(1)m{4}(1)m{5}(1)z{6}(1)z{7}(1)znumber of (nonminimal) gb|
|   -- number of monomials                = 9                                 |
|   -- #reduction steps = 6                                                   |
|   -- #spairs done = 6                                                       |
|   -- ncalls = 0                                                             |
|   -- nloop = 0                                                              |
|   -- nsaved = 0                                                             |
|   --                                                                        |
|o7 = {2} | -y3+1 -z4+2 0     |                                               |
|     {3} | x2-3  0     -z4+2 |                                               |
|     {4} | 0     x2-3  y3-1  |                                               |
|                                                                             |
|             3      3                                                        |
|o7 : Matrix R  <-- R                                                         |
|-----------------------------------------------------------------------------|
|elements = 3                                                                 |
+-----------------------------------------------------------------------------+
|i8 : kernel f                                                                |
|                                                                             |
|o8 = image {2} | -y3+1 -z4+2 0     |                                         |
|           {3} | x2-3  0     -z4+2 |                                         |
|           {4} | 0     x2-3  y3-1  |                                         |
|                                                                             |
|                             3                                               |
|o8 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+
If you know that the columns of z already form a set of minimal generators,
then one may use forceGB, once again.

Further information
===================

  * Default value: null
  * Function: forceGB, -- declare that the columns of a matrix
    are a Gröbner basis
  * Option key: SyzygyMatrix, -- an optional argument

Caveat
======

If the columns of z do not generate the syzygy module of f, nonsensical answers
may result

See also
========

  * Gröbner bases

Functions with optional argument named SyzygyMatrix:
====================================================

  * forceGB(...,SyzygyMatrix=>...)
    -- specify the syzygy
    matrix
  * "markedGB(...,SyzygyMatrix=>...)" -- see markedGB(Matrix,Matrix),
    -- make a marked Gröbner basis

formation -- recover the methods used to make a module
******************************************************

Synopsis
========

  * Usage:
        formation M
  * Inputs:
      * M, a module, a module
  * Outputs:
      * an expression, an expression,
        whose value is the module itself

Description
===========

If the module was created as a direct sum, tensor product, of Hom-module, then
the expression will reflect that. In each case, the result is a function
application, and the sequence of arguments is easily obtained.

+-----------------------------------------------+
|i1 : M = ZZ^2 ++ ZZ^3                          |
|                                               |
|       5                                       |
|o1 = ZZ                                        |
|                                               |
|o1 : ZZ-module, free                           |
+-----------------------------------------------+
|i2 : t = formation M                           |
|                                               |
|                  2    3                       |
|o2 = directSum (ZZ , ZZ )                      |
|                                               |
|o2 : Expression of class FunctionApplication   |
+-----------------------------------------------+
|i3 : peek t                                    |
|                                               |
|                                       2    3  |
|o3 = FunctionApplication{directSum, (ZZ , ZZ )}|
+-----------------------------------------------+
|i4 : t#1                                       |
|                                               |
|        2    3                                 |
|o4 = (ZZ , ZZ )                                |
|                                               |
|o4 : Sequence                                  |
+-----------------------------------------------+
|i5 : value t                                   |
|                                               |
|       5                                       |
|o5 = ZZ                                        |
|                                               |
|o5 : ZZ-module, free                           |
+-----------------------------------------------+
|i6 : M = directSum(ZZ^2, ZZ^3, ZZ^4)           |
|                                               |
|       9                                       |
|o6 = ZZ                                        |
|                                               |
|o6 : ZZ-module, free                           |
+-----------------------------------------------+
|i7 : t = formation M                           |
|                                               |
|                  2    3    4                  |
|o7 = directSum (ZZ , ZZ , ZZ )                 |
|                                               |
|o7 : Expression of class FunctionApplication   |
+-----------------------------------------------+
|i8 : t#1                                       |
|                                               |
|        2    3    4                            |
|o8 = (ZZ , ZZ , ZZ )                           |
|                                               |
|o8 : Sequence                                  |
+-----------------------------------------------+
|i9 : M = ZZ^2 ** ZZ^3                          |
|                                               |
|       6                                       |
|o9 = ZZ                                        |
|                                               |
|o9 : ZZ-module, free                           |
+-----------------------------------------------+
|i10 : t = formation M                          |
|                                               |
|                2    3                         |
|o10 = tensor (ZZ , ZZ )                        |
|                                               |
|o10 : Expression of class FunctionApplication  |
+-----------------------------------------------+
|i11 : t#1                                      |
|                                               |
|         2    3                                |
|o11 = (ZZ , ZZ )                               |
|                                               |
|o11 : Sequence                                 |
+-----------------------------------------------+

If the module was not obtained that way, then null, is returned.

+--------------------+
|i12 : formation ZZ^6|
+--------------------+

The same remarks apply to certain other types of objects, such as chain
complexes.

+----------------------------------------------------------------+
|i13 : R = QQ[x,y];                                              |
+----------------------------------------------------------------+
|i14 : C = res coker vars R;                                     |
+----------------------------------------------------------------+
|i15 : D = C ++ C                                                |
|                                                                |
|       2      4      2                                          |
|o15 = R  <-- R  <-- R  <-- 0                                    |
|                                                                |
|      0      1      2      3                                    |
|                                                                |
|o15 : ChainComplex                                              |
+----------------------------------------------------------------+
|i16 : formation D                                               |
|                                                                |
|                  1      2      1         1      2      1       |
|o16 = directSum (R  <-- R  <-- R  <-- 0, R  <-- R  <-- R  <-- 0)|
|                                                                |
|                 0      1      2      3  0      1      2      3 |
|                                                                |
|o16 : Expression of class FunctionApplication                   |
+----------------------------------------------------------------+

See also
========

  * directSum -- direct sum of modules or maps
  * Module ++ Module -- direct sum of modules
  * Module ** Module -- tensor product of
    modules
  * Hom(Module,Module) -- module of homomorphisms
  * Expression -- the class of all expressions
  * FunctionApplication -- the class of all
    function application expressions

Ways to use formation:
======================

  * "formation(ChainComplex)"
  * "formation(ChainComplexMap)"
  * "formation(GradedModule)"
  * "formation(GradedModuleMap)"
  * "formation(Module)"

For the programmer
==================

The object formation, is a method function.

frac -- construct a fraction field
**********************************

Synopsis
========

  * Usage:
        frac R
  * Inputs:
      * R, a ring, an integral domain
  * Outputs:
      * a fraction field, the field of fractions of R

Description
===========

+-----------------------+
|i1 : F = frac ZZ       |
|                       |
|o1 = QQ                |
|                       |
|o1 : Ring              |
+-----------------------+
|i2 : F = frac (ZZ[a,b])|
|                       |
|o2 = F                 |
|                       |
|o2 : FractionField     |
+-----------------------+
After invoking the frac command, the elements of the ring are treated as
elements of the fraction field:
+-------------------------------+
|i3 : R = ZZ/101[x,y];          |
+-------------------------------+
|i4 : gens gb ideal(x^2*y - y^3)|
|                               |
|o4 = | x2y-y3 |                |
|                               |
|             1      1          |
|o4 : Matrix R  <-- R           |
+-------------------------------+
|i5 : K = frac R;               |
+-------------------------------+
|i6 : gens gb ideal(x^2*y - y^3)|
|                               |
|o6 = | 1 |                     |
|                               |
|             1      1          |
|o6 : Matrix K  <-- K           |
+-------------------------------+
Another way to obtain frac R is with x/,y where x, y are elements of
R:
+------------+
|i7 : a*b/b^4|
|            |
|      a     |
|o7 = --     |
|      3     |
|     b      |
|            |
|o7 : F      |
+------------+
Fractions are reduced to the extent possible.
+---------------------------------------+
|i8 : f = (x-y)/(x^6-y^6)               |
|                                       |
|                      1                |
|o8 = ----------------------------------|
|      5    4     3 2    2 3      4    5|
|     x  + x y + x y  + x y  + x*y  + y |
|                                       |
|o8 : K                                 |
+---------------------------------------+
|i9 : (x^3 - y^3) * f                   |
|                                       |
|      x - y                            |
|o9 = -------                           |
|      3    3                           |
|     x  + y                            |
|                                       |
|o9 : K                                 |
+---------------------------------------+
The parts of a fraction may be extracted.
+----------------------------------------+
|i10 : numerator f                       |
|                                        |
|o10 = 1                                 |
|                                        |
|o10 : R                                 |
+----------------------------------------+
|i11 : denominator f                     |
|                                        |
|       5    4     3 2    2 3      4    5|
|o11 = x  + x y + x y  + x y  + x*y  + y |
|                                        |
|o11 : R                                 |
+----------------------------------------+
Alternatively, the functions lift, and liftable,
can be used.
+----------------------------------------+
|i12 : liftable(1/f,R)                   |
|                                        |
|o12 = true                              |
+----------------------------------------+
|i13 : liftable(f,R)                     |
|                                        |
|o13 = false                             |
+----------------------------------------+
|i14 : lift(1/f,R)                       |
|                                        |
|       5    4     3 2    2 3      4    5|
|o14 = x  + x y + x y  + x y  + x*y  + y |
|                                        |
|o14 : R                                 |
+----------------------------------------+
One can form resolutions and Gröbner bases of ideals in polynomial rings over
fraction fields, as in the following example. Note that computations over
fraction fields can be quite slow.
+---------------------------------------------+
|i15 : S = K[u,v];                            |
+---------------------------------------------+
|i16 : I = ideal(y^2*u^3 + x*v^3, u^2*v, u^4);|
|                                             |
|o16 : Ideal of S                             |
+---------------------------------------------+
|i17 : gens gb I                              |
|                                             |
|o17 = | u2v u3+x/y2v3 v4 uv3 |               |
|                                             |
|              1      4                       |
|o17 : Matrix S  <-- S                        |
+---------------------------------------------+
|i18 : Ires = res I                           |
|                                             |
|       1      3      2                       |
|o18 = S  <-- S  <-- S  <-- 0                 |
|                                             |
|      0      1      2      3                 |
|                                             |
|o18 : ChainComplex                           |
+---------------------------------------------+
|i19 : Ires.dd_2                              |
|                                             |
|o19 = {3} | 0   y2/xuv    |                  |
|      {3} | -v2 (-y2)/xu2 |                  |
|      {4} | u   -v        |                  |
|                                             |
|              3      2                       |
|o19 : Matrix S  <-- S                        |
+---------------------------------------------+
One way to compute a blowup of an ideal I in R, is to compute the kernel of a
map of a new polynomial ring into a fraction field of R, as shown below.
+-------------------------------------------------------+
|i20 : A = ZZ/101[a,b,c];                               |
+-------------------------------------------------------+
|i21 : f = map(K, A, {x^3/y^4, x^2/y^2, (x^2+y^2)/y^4});|
|                                                       |
|o21 : RingMap K <-- A                                  |
+-------------------------------------------------------+
|i22 : kernel f                                         |
|                                                       |
|              3     2     2     3 2    3       3       |
|o22 = ideal (b c - a b - a , a*b c  - a b*c - a c)     |
|                                                       |
|o22 : Ideal of A                                       |
+-------------------------------------------------------+

Caveat
======

The input ring should be an integral domain.

Currently, for S as above, one cannot define frac S or fractions u/v.  One can
get around that by defining B = ZZ/101[x,y,u,v] and identify frac S with frac
B.

Note that expressions such as frac QQ[x] are parsed as (frac QQ)[x]. To obtain
the fraction field of QQ[x] use instead frac (QQ[x]).

See also
========

  * numerator -- numerator of a fraction
  * denominator -- denominator of a fraction
  * liftable -- whether lifting to another ring is possible
  * lift -- lift to another ring

Ways to use frac:
=================

  * "frac(EngineRing)"
  * "frac(FractionField)"
  * "frac(Ring)"

For the programmer
==================

The object frac, is a method function.

fraction
********

Synopsis
========

  * Usage:
        fraction(f, g)
  * Outputs:
      * a ring element, the fraction f/g

Description
===========

The output will be in the fraction field of the ring containing f and g,
without reducing it to lowest terms.

See also
========

  * frac -- construct a fraction field

Ways to use fraction:
=====================

  * "fraction(RingElement,RingElement)"

For the programmer
==================

The object fraction, is a method function.

FractionField -- the class of all fraction fields
*************************************************

Description
===========

Macaulay2 provides for fraction fields of integral domains.

In some cases, normal forms of fractions makes sense, but in general for
fraction fieldss of quotient rings, there is no notion of normal form for a
fraction. In other words, fractions may be equal without displaying the same
numerator and denominator.

Computations over fraction fields, or polynomial rings over fraction fields,
especially Gröbner basis computations, are much slower than over prime fields.
Still, an attempt is made to speed up these computations as much as possible,
and more is planned in the future.

For an overview, see fraction fields, and  frac.

Useful functions for use with fractions and fraction fields include:

  * frac -- construct a fraction field
  * numerator -- numerator of a fraction
  * denominator -- denominator of a fraction
  * liftable -- whether lifting to another ring is possible
  * lift -- lift to another ring

Functions and methods returning a fraction field:
=================================================

  * frac -- construct a fraction field

Methods that use a fraction field:
==================================

  * degreeGroup(FractionField) (missing documentation)
  * "degrees(FractionField)" -- see degrees(Ring), --
    degrees of generators
  * "describe(FractionField)" -- see describe, -- real
    description
  * "dim(FractionField)" -- see dim(Ring), -- compute the
    Krull dimension
  * "frac(FractionField)" -- see frac, -- construct a fraction
    field
  * "numgens(FractionField)" -- see numgens(Ring), --
    number of generators of a polynomial ring
  * "precision(FractionField)" -- see precision,

For the programmer
==================

The object FractionField, is a type, with
ancestor classes EngineRing, < Ring <
Type < MutableHashTable < HashTable
< Thing.

frames -- get the frames associated to a closure
************************************************

Synopsis
========

  * Usage:
        frames f
  * Inputs:
      * f, () or a symbol, a function, or an
        instance of the type PseudocodeClosure,
  * Outputs:
      * a list of mutable lists, the frames attached to the closure f or, if f
        is (), then the frames attached to the current lexical scope

Description
===========

This function is occasionally useful as a debugging tool.
+------------------------------------------+
|i1 : f = (x,y,z) -> t -> t                |
|                                          |
|o1 = f                                    |
|                                          |
|o1 : FunctionClosure                      |
+------------------------------------------+
|i2 : g = f(111,222,"hi there")            |
|                                          |
|o2 = g                                    |
|                                          |
|o2 : FunctionClosure                      |
+------------------------------------------+
|i3 : frames g                             |
|                                          |
|o3 = {MutableList{...3...}, MutableList{}}|
|                                          |
|o3 : List                                 |
+------------------------------------------+
|i4 : peek first oo                        |
|                                          |
|o4 = MutableList{111, 222, hi there}      |
+------------------------------------------+

Ways to use frames:
===================

  * "frames(FunctionClosure)"
  * "frames(PseudocodeClosure)"
  * "frames(Sequence)"
  * "frames(Symbol)"
  * frames(CompiledFunction) (missing documentation)
  * frames(CompiledFunctionClosure) (missing documentation)

For the programmer
==================

The object frames, is a compiled function.

from -- loop control
********************

Description
===========

from a keyword used with for, and new.

For the programmer
==================

The object from, is a keyword.

Function @@ Function -- composition of functions
************************************************

Synopsis
========

  * Operator: @@,
  * Usage:
        f @@ g
  * Inputs:
      * f
      * g
  * Outputs:
      * the composite function of f and g.

Description
===========

+------------------------------------------------+
|i1 : f = i -> i+1                               |
|                                                |
|o1 = f                                          |
|                                                |
|o1 : FunctionClosure                            |
+------------------------------------------------+
|i2 : g = i -> i^2                               |
|                                                |
|o2 = g                                          |
|                                                |
|o2 : FunctionClosure                            |
+------------------------------------------------+
|i3 : apply(0 .. 10, f @@ g)                     |
|                                                |
|o3 = (1, 2, 5, 10, 17, 26, 37, 50, 65, 82, 101) |
|                                                |
|o3 : Sequence                                   |
+------------------------------------------------+
|i4 : apply(0 .. 10, g @@ f)                     |
|                                                |
|o4 = (1, 4, 9, 16, 25, 36, 49, 64, 81, 100, 121)|
|                                                |
|o4 : Sequence                                   |
+------------------------------------------------+

Ways to use this method:
========================

  * Function @@ Function -- composition of
    functions

Function _ Thing -- attach the first argument to a function of two or more arguments
************************************************************************************

Synopsis
========

  * Operator: _,
  * Usage:
        g = f_x
  * Inputs:
      * f, a function, a function of two or more arguments
      * x, a thing,
  * Outputs:
      * g, a function, a new function with the property that
        g(y) returns the value of  f(x,y), that g(y,z) returns the value of
        f(x,y,z), and so on.  If x is itself a sequence, its members will be
        spliced into the sequence of arguments of f.

Description
===========

This abbreviation allows us to save a bit of typing, and in some cases, agrees
with standard mathematical notation.

We use the identity function in the following examples, so we can exactly what
sequence of arguments is constructed.

+-------------------------+
|i1 : identity_a x        |
|                         |
|o1 = (a, x)              |
|                         |
|o1 : Sequence            |
+-------------------------+
|i2 : identity_a (x,y)    |
|                         |
|o2 = (a, x, y)           |
|                         |
|o2 : Sequence            |
+-------------------------+
|i3 : identity_(a,b) x    |
|                         |
|o3 = (a, b, x)           |
|                         |
|o3 : Sequence            |
+-------------------------+
|i4 : identity_(a,b) (x,y)|
|                         |
|o4 = (a, b, x, y)        |
|                         |
|o4 : Sequence            |
+-------------------------+

In the following examples, we show more typical uses of this notation.

+-------------------------------+
|i5 : R = ZZ[a .. i];           |
+-------------------------------+
|i6 : f = genericMatrix(R,a,3,3)|
|                               |
|o6 = | a d g |                 |
|     | b e h |                 |
|     | c f i |                 |
|                               |
|             3      3          |
|o6 : Matrix R  <-- R           |
+-------------------------------+
|i7 : exteriorPower(2,f)        |
|                               |
|o7 = | -bd+ae -bg+ah -eg+dh |  |
|     | -cd+af -cg+ai -fg+di |  |
|     | -ce+bf -ch+bi -fh+ei |  |
|                               |
|             3      3          |
|o7 : Matrix R  <-- R           |
+-------------------------------+
|i8 : exteriorPower_2 f         |
|                               |
|o8 = | -bd+ae -bg+ah -eg+dh |  |
|     | -cd+af -cg+ai -fg+di |  |
|     | -ce+bf -ch+bi -fh+ei |  |
|                               |
|             3      3          |
|o8 : Matrix R  <-- R           |
+-------------------------------+
|i9 : p = prepend_7             |
|                               |
|o9 = p                         |
|                               |
|o9 : FunctionClosure           |
+-------------------------------+
|i10 : p {8,9,10}               |
|                               |
|o10 = {7, 8, 9, 10}            |
|                               |
|o10 : List                     |
+-------------------------------+

Ways to use this method:
========================

  * Function _ Thing -- attach the first argument to
    a function of two or more arguments

Function Thing -- function application
**************************************

Synopsis
========

  * Operator: SPACE,

Description
===========

f x -- yields the result of applying the function f to x.

Ways to use this method:
========================

  * Function Thing -- function application

FunctionApplication -- the class of all function application expressions
************************************************************************

Description
===========

FunctionApplication is a type of Expression, representing an
application of a function.

For the programmer
==================

The object FunctionApplication, is a header type,
with ancestor classes Expression, <
BasicList < Thing.

FunctionBody -- the class of function bodies
********************************************

See also
========

  * functionBody -- get the body of a function

Types of function body:
=======================

  * CompiledFunctionBody -- the class of all
    compiled function bodies

Methods that use a function body:
=================================

  * disassemble(FunctionBody) (missing documentation)
  * "locate(FunctionBody)" -- see locate, -- locate source code
  * pseudocode(FunctionBody) (missing documentation)

For the programmer
==================

The object FunctionBody, is a type, with
ancestor class Thing.

functionBody -- get the body of a function
******************************************

Synopsis
========

  * Usage:
        functionBody f
  * Inputs:
      * f, a function,
  * Outputs:
      * a function body, the body of the function f

Description
===========

The body of f is essentially just the source code of f, with no frames
providing bindings for the local variables in scopes enclosing the scope of f.
Function bodies cannot act as functions, but they can be tested for equality
(see ===), and they can be used as keys in hash tables.

+------------------------------------------+
|i1 : f = a -> b -> a+b+a*b                |
|                                          |
|o1 = f                                    |
|                                          |
|o1 : FunctionClosure                      |
+------------------------------------------+
|i2 : functionBody f 1                     |
|                                          |
|o2 = FunctionBody[currentString:1:14-1:21]|
|                                          |
|o2 : FunctionBody                         |
+------------------------------------------+
|i3 : f 1 === f 2                          |
|                                          |
|o3 = false                                |
+------------------------------------------+
|i4 : functionBody f 1 === functionBody f 2|
|                                          |
|o4 = true                                 |
+------------------------------------------+

See also
========

  * FunctionBody -- the class of function bodies

For the programmer
==================

The object functionBody, is a compiled function.

FunctionClosure -- the class of all function closures
*****************************************************

Description
===========

Functions created by the operator ->, are function closures.
+--------------------+
|i1 : class (x->x)   |
|                    |
|o1 = FunctionClosure|
|                    |
|o1 : Type           |
+--------------------+

Types of function closure:
==========================

  * CacheFunction -- the class of cache functions
  * Iterator -- class for iterators
  * MethodFunctionBinary -- a type of method
    function
  * MethodFunctionSingle -- a type of method
    function
  * MethodFunctionWithOptions -- a type of
    method function

Methods that use a function closure:
====================================

  * disassemble(FunctionClosure) (missing documentation)
  * "frames(FunctionClosure)" -- see frames, -- get the frames
    associated to a closure
  * "localDictionaries(FunctionClosure)" -- see localDictionaries,
    -- get local dictionaries
  * pseudocode(FunctionClosure) (missing documentation)

Protected objects of class FunctionClosure:
===========================================

  * addEndFunction -- add an ending function
  * ancestors -- the ancestors of something
  * applicationDirectory -- the path to the user's
    application directory
  * applyTable -- apply a function to each element of a
    table
  * baseFilename -- the base part of a filename or path
  * beginDocumentation -- start documentation
    section of a package
  * benchmark -- accurate timing of execution
  * cacheValue -- cache values of functions in their
    arguments
  * centerString -- center a string or net
  * columnate -- arrange strings in columns
  * currentPosition -- the current position in the
    current source file
  * demark -- insert a string between elements of a list of
    strings
  * End -- module of endomorphisms
  * error -- deliver error message
  * even -- tell whether an integer is even
  * first -- first element of a list
  * getNonUnit -- retrieve a previously discovered non-unit
  * getSymbol -- make a global user symbol from a string
  * globalAssign -- global assignment, in function form
  * globalAssignFunction -- the standard method
    for the global assignment hook
  * globalAssignment -- install standard global
    assignment method
  * globalReleaseFunction -- the standard method
    for the global variable release hook
  * input -- read Macaulay2 commands and echo
  * installedPackages
  * inversePermutation -- inverse permutation
  * isFinitePrimeField -- whether a ring is a finite
    prime field
  * isPrimitive -- whether an element is a primitive
    element of a finite field
  * isTable -- whether something is a list of lists of equal
    length
  * last -- last element of a list
  * lines -- split a string into lines
  * load -- read Macaulay2 commands
  * "memoizeClear" -- see memoize, -- record results of function
    evaluation for future use
  * "memoizeValues" -- see memoize, -- record results of
    function evaluation for future use
  * method -- make a new method function
  * mod -- reduce modulo an integer
  * monomialCurveIdeal -- make the ideal of a
    monomial curve
  * needs -- read Macaulay2 commands if necessary
  * notImplemented -- print an 'not implemented' error
    message
  * number -- count how many elements of a list satisfy a
    condition
  * odd -- tell whether an integer is odd
  * on -- trace a function each time it's run
  * pager -- display with paging
  * peek -- examine contents of an object
  * print -- print something
  * printerr -- print something to stderr
  * same -- whether everything in a list is the same
  * seeParsing -- display parsing precedence table for
    Macaulay2 operators
  * "showHtml" -- see show, -- display various objects in an
    external viewer
  * "showTex" -- see show, -- display various objects in an
    external viewer
  * stashValue -- stash values of functions in their
    arguments
  * subtable -- extract a subtable from a table
  * synonym -- synonym for members of a class
  * syzygyScheme -- construct a syzygy scheme
  * table -- make a table from a binary function
  * temporaryFileName -- make a temporary file name
  * toAbsolutePath -- the absolute path version of a
    file name
  * toLower -- convert to lower case
  * toUpper -- convert to upper case
  * tutorial -- convert documentation from tutorial format
  * uniform -- whether all elements of a list are the same
    class
  * uninstallAllPackages
  * userSymbols -- a list of the user's symbols
  * zero -- whether something is zero

For the programmer
==================

The object FunctionClosure, is a type, with
ancestor classes Function, < Thing.

GaloisField -- the class of all Galois fields
*********************************************

Functions and methods returning a Galois field:
===============================================

  * "GF(Ring)" -- see GF, -- make a finite field
  * "GF(ZZ)" -- see GF, -- make a finite field
  * "GF(ZZ,ZZ)" -- see GF, -- make a finite field

Methods that use a Galois field:
================================

  * ambient(GaloisField) -- corresponding
    quotient ring
  * "describe(GaloisField)" -- see describe, -- real
    description
  * "dim(GaloisField)" -- see dim(Ring), -- compute the
    Krull dimension
  * "flattenRing(GaloisField)" -- see flattenRing, -- write
    a ring as a (quotient of a) polynomial ring
  * map(GaloisField,GaloisField) (missing documentation)
  * "precision(GaloisField)" -- see precision,

For the programmer
==================

The object GaloisField, is a type, with
ancestor classes EngineRing, < Ring <
Type < MutableHashTable < HashTable
< Thing.

Gamma -- Gamma function
***********************

Synopsis
========

  * Usage:
        Gamma x
        Gamma(s, x)
  * Inputs:
      * s, a real number,
      * x, a real number,
  * Outputs:
      * a real number,

Description
===========

With one argument, this is the gamma function (see
https://en.wikipedia.org/wiki/gamma_function ) \(\Gamma(x) = \int_0^\infty
t^{x-1}e^{-t}\,dt\).

+-------------------------+
|i1 : Gamma 6             |
|                         |
|o1 = 120                 |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

With two arguments, it is the (upper) incomplete gamma function (see
https://en.wikipedia.org/wiki/incomplete_gamma_function ) \(\Gamma(s, x) =
\int_x^\infty t^{s-1}e^{-t}\,dt\).

+-------------------------+
|i2 : Gamma(3, 7)         |
|                         |
|o2 = .05927232776104355  |
|                         |
|o2 : RR (of precision 53)|
+-------------------------+

See also
========

  * regularizedGamma -- upper regularized gamma
    function
  * inverseRegularizedGamma -- inverse of the
    upper regularized gamma function

Ways to use Gamma:
==================

  * "Gamma(CC)"
  * "Gamma(CC,CC)"
  * "Gamma(CC,RR)"
  * "Gamma(RR)"
  * "Gamma(RR,CC)"
  * "Gamma(RR,RR)"
  * "Gamma(RR,RRi)"
  * "Gamma(RRi)"
  * "Gamma(RRi,RR)"
  * "Gamma(RRi,RRi)"

For the programmer
==================

The object Gamma, is a method function.

gb -- compute a Gröbner basis
*****************************

Synopsis
========

  * Usage:
        gb I
  * Inputs:
      * I, an ideal, module, or matrix
  * Optional inputs,:
      * Algorithm => a symbol, default value Inhomogeneous,
        possible values: Homogeneous, Inhomogeneous,
        see Homogeneous2, and Sugarless.
        Experimental options include LinearAlgebra, and Toric.
      * BasisElementLimit => an integer, default value infinity,
        stop when this number of (nonminimal) Gröbner basis elements has been
        found
      * ChangeMatrix => a Boolean value, default value false,
        whether to compute the change of basis matrix from Gröbner basis
        elements to original generators.  Use getChangeMatrix,
        to recover it.
      * CodimensionLimit => an integer, default value infinity, stop
        computation once codimension of submodule of lead terms reaches this
        value (not functional yet)
      * DegreeLimit => a list, default value {}, stop after the
        Gröbner basis in this degree has been computed
      * GBDegrees => a list, default value null, a list of
        positive integer weights, one for each variable in the ring, to be used
        for organizing the computation by degrees (the 'sugar' ecart vector)
      * HardDegreeLimit => ..., default value null, throws away all S-pairs of
        degrees beyond the limit. The computation will be re-initialized if
        higher degrees are required.
      * Hilbert => ..., default value null, informs Macaulay2 that this is the
        poincare, polynomial, and can be used to aid in the
        computation of the Gröbner basis (Hilbert driven)
      * MaxReductionCount => an integer, default value 10, the
        maximum number of reductions of an S-pair done before requeueing it, if
        the Inhomogeneous algorithm is in use
      * PairLimit => an integer, default value infinity, stop after
        this number of spairs has been considered
      * StopBeforeComputation => a Boolean value, default value
        false, whether to initialize the Gröbner basis engine but return before
        doing any computation (useful for using or viewing partially computed
        Gröbner bases)
      * StopWithMinimalGenerators => a Boolean value, default
        value false, whether to stop as soon as the minimal set (or a trimmed
        set, if not homogeneous or local) of generators is known.  Intended for
        internal use only
      * Strategy => ..., default value {}, either LongPolynomial,
        see Sort, or a list of these.  See
        LongPolynomial,: use a geobucket data structure while
        reducing polynomials; see Sort,: sort the S-pairs. Another
        symbol usable here is UseSyzygies. Usually S-pairs are processed degree
        by degree in the order that they were constructed.
      * SubringLimit => an integer, default value infinity, stop
        after this number of elements of the Gröbner basis lie in the first
        subring
      * Syzygies => a Boolean value, default value false,
        whether to collect syzygies on the original generators during the
        computation.  Intended for internal use only
      * SyzygyLimit => an integer, default value infinity, stop when
        this number of non-zero syzygies has been found
      * SyzygyRows => an integer, default value infinity, for each
        syzygy and change of basis element, keep only this many rows of each
        syzygy
  * Outputs:
      * a Gröbner basis, a Gröbner basis computation
        object

Description
===========

See Gröbner bases, for more information and examples.

The returned value is not the Gröbner basis itself.  The matrix whose columns
form a sorted, auto-reduced Gröbner basis are obtained by applying
generators, (synonym: gens) to the result of gb.
+-------------------------------------------+
|i1 : R = QQ[a..d]                          |
|                                           |
|o1 = R                                     |
|                                           |
|o1 : PolynomialRing                        |
+-------------------------------------------+
|i2 : I = ideal(a^3-b^2*c, b*c^2-c*d^2, c^3)|
|                                           |
|             3    2      2      2   3      |
|o2 = ideal (a  - b c, b*c  - c*d , c )     |
|                                           |
|o2 : Ideal of R                            |
+-------------------------------------------+
|i3 : G = gens gb I                         |
|                                           |
|o3 = | c3 bc2-cd2 a3-b2c c2d2 cd4 |        |
|                                           |
|             1      5                      |
|o3 : Matrix R  <-- R                       |
+-------------------------------------------+

When I is a subquotient module M/N of a free module F, then N is generated by
relations I and M is generated by the concatenated matrix generators I ||
relations I -- it is the Gröbner basis of that matrix which is computed, so
that reduction modulo the Gröbner basis can be used to determine membership in
M.  When relations are present, the option SyzygyRows, is set
to the number of columns of generators I, so that if ChangeMatrix => true is
used, then division by the Gröbner basis can be to express an element of F as a
linear combination of columns of generators I, avoiding the computation of the
coefficients of the columns of relations I, leaving all the information that is
required to specify an element of I.

+--------------------------------------------------+
|i4 : R = QQ[x,y]                                  |
|                                                  |
|o4 = R                                            |
|                                                  |
|o4 : PolynomialRing                               |
+--------------------------------------------------+
|i5 : M = subquotient(matrix {{x}}, matrix {{x+y}})|
|                                                  |
|o5 = subquotient (| x |, | x+y |)                 |
|                                                  |
|                               1                  |
|o5 : R-module, subquotient of R                   |
+--------------------------------------------------+
|i6 : gens gb M                                    |
|                                                  |
|o6 = | y x |                                      |
|                                                  |
|             1      2                             |
|o6 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i7 : matrix {{x}} // gb(M,ChangeMatrix=>true)     |
|                                                  |
|o7 = {1} | 1 |                                    |
|                                                  |
|             1      1                             |
|o7 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i8 : matrix {{y}} // gb(M,ChangeMatrix=>true)     |
|                                                  |
|o8 = {1} | -1 |                                   |
|                                                  |
|             1      1                             |
|o8 : Matrix R  <-- R                              |
+--------------------------------------------------+

See also
========

  * Gröbner bases
  * groebnerBasis -- Gröbner basis, as a matrix
  * generators(GroebnerBasis) -- the
    generator matrix of a Gröbner basis
  * gbTrace -- provide tracing output during various
    computations in the     engine.
  * poincare -- assemble degrees of a ring, module, or ideal
    into a polynomial
  * gbSnapshot -- the Gröbner basis matrix as so far
    computed
  * gbRemove -- remove Gröbner basis

Ways to use gb:
===============

  * "gb(Ideal)"
  * "gb(Matrix)"
  * "gb(Module)"

For the programmer
==================

The object gb, is a method function with options.

gbRemove -- remove Gröbner basis
********************************

Synopsis
========

  * Usage:
        gbRemove M
  * Inputs:
      * M, an ideal, a matrix, or a module,
  * Consequences:
      * all Gröbner bases computed for M are removed

Description
===========

This is a simple way to remove the space associated with large Gröbner bases
that are no longer needed.
+-----------------------------------------------------------------------------+
|i1 : R = ZZ[a]/(a^2-3)[x,y]                                                  |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : F = y^2-x*(x-1)*(x-a)                                                   |
|                                                                             |
|        3           2    2                                                   |
|o2 = - x  + (a + 1)x  + y  - a*x                                             |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+
|i3 : J = ideal(diff(x,F),diff(y,F),F)                                        |
|                                                                             |
|                2                         3           2    2                 |
|o3 = ideal (- 3x  + (2a + 2)x - a, 2y, - x  + (a + 1)x  + y  - a*x)          |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : gens gb J                                                               |
|                                                                             |
|o4 = | 12 6a+6 2y 4x-2a+6 (2a+2)x+2a+6 y2+2x-a-3 x2+3a |                     |
|                                                                             |
|             1      7                                                        |
|o4 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i5 : peek J.generators.cache                                                 |
|                                                                             |
|o5 = CacheTable{GroebnerBasisOptions{HardDegreeLimit => null} =>             |
|                                     Syzygies => false                       |
|                                     SyzygyRows => 0                         |
|                image => image | -3x2+(2a+2)x-a 2y -x3+(a+1)x2+y2            |
|                isHomogeneous => false                                       |
|-----------------------------------------------------------------------------|
|GroebnerBasis[status: done; S-pairs encountered up to degree 8]}             |
|                                                                             |
|                                                                             |
|-ax |                                                                        |
+-----------------------------------------------------------------------------+
|i6 : gbRemove J                                                              |
+-----------------------------------------------------------------------------+
|i7 : peek J.generators.cache                                                 |
|                                                                             |
|o7 = CacheTable{image => image | -3x2+(2a+2)x-a 2y -x3+(a+1)x2+y2-ax |}      |
|                isHomogeneous => false                                       |
+-----------------------------------------------------------------------------+

See also
========

  * gb -- compute a Gröbner basis
  * gbTrace -- provide tracing output during various
    computations in the     engine.
  * gbSnapshot -- the Gröbner basis matrix as so far
    computed

Ways to use gbRemove:
=====================

  * "gbRemove(Ideal)"
  * "gbRemove(Matrix)"
  * "gbRemove(Module)"

For the programmer
==================

The object gbRemove, is a method function.

gbSnapshot -- the Gröbner basis matrix as so far computed
*********************************************************

Synopsis
========

  * Usage:
        gbSnapshot M
  * Inputs:
      * M, an ideal, a matrix, or a module,
  * Outputs:
      * a matrix, the Gröbner basis as so far computed

Description
===========

This routine is useful to be able to obtain partial results from a partially
computed Gröbner basis. Little computation is done (although a minimalization,
auto-reduction and sort is performed).
+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a..d]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = intersect((ideal(a,b,c^3-d^3))^2,ideal(a^2-c^2,b^2-d^2))            |
|                                                                             |
|             2 2    2 2   2         3    3       3   3       3      2        |
|o2 = ideal (b c  - a d , a b*c - b*c  - b d + b*d , a c - a*c  - a*b d +     |
|     ------------------------------------------------------------------------|
|        3   4    2 2     3        2   2 2    2 2   3         2   4    2 2    |
|     a*d , b  - b d , a*b  - a*b*d , a b  - a d , a b - a*b*c , a  - a c ,   |
|     ------------------------------------------------------------------------|
|      2 4    6     2   3     3 3    2 4    6                                 |
|     a c  - c  - 2a c*d  + 2c d  + b d  - d )                                |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : gb(I, BasisElementLimit=>5)                                             |
|                                                                             |
|o3 = GroebnerBasis[status: BasisElementLimit; all S-pairs handled up to      |
|                                                                             |
|o3 : GroebnerBasis                                                           |
|-----------------------------------------------------------------------------|
|degree 5]                                                                    |
+-----------------------------------------------------------------------------+
|i4 : gbSnapshot I                                                            |
|                                                                             |
|o4 = | b2c2-a2d2 a2bc-bc3-b3d+bd3 a3c-ac3-ab2d+ad3 b4-b2d2 ab3-abd2 a2b2-a2d2|
|     ------------------------------------------------------------------------|
|     a3b-abc2 a4-a2c2 a2c4-c6-2a2cd3+2c3d3+b2d4-d6 |                         |
|                                                                             |
|             1      9                                                        |
|o4 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i5 : gb(I, BasisElementLimit=>10)                                            |
|                                                                             |
|o5 = GroebnerBasis[status: done; S-pairs encountered up to degree 6]         |
|                                                                             |
|o5 : GroebnerBasis                                                           |
+-----------------------------------------------------------------------------+
|i6 : gbSnapshot I                                                            |
|                                                                             |
|o6 = | b2c2-a2d2 a2bc-bc3-b3d+bd3 a3c-ac3-ab2d+ad3 b4-b2d2 ab3-abd2 a2b2-a2d2|
|     ------------------------------------------------------------------------|
|     a3b-abc2 a4-a2c2 a2c4-c6-2a2cd3+2c3d3+b2d4-d6 |                         |
|                                                                             |
|             1      9                                                        |
|o6 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i7 : gens gb I                                                               |
|                                                                             |
|o7 = | b2c2-a2d2 a2bc-bc3-b3d+bd3 a3c-ac3-ab2d+ad3 b4-b2d2 ab3-abd2 a2b2-a2d2|
|     ------------------------------------------------------------------------|
|     a3b-abc2 a4-a2c2 a2c4-c6-2a2cd3+2c3d3+b2d4-d6 |                         |
|                                                                             |
|             1      9                                                        |
|o7 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * gb -- compute a Gröbner basis
  * gbTrace -- provide tracing output during various
    computations in the     engine.
  * gbRemove -- remove Gröbner basis

Ways to use gbSnapshot:
=======================

  * "gbSnapshot(Ideal)"
  * "gbSnapshot(Matrix)"
  * "gbSnapshot(Module)"

For the programmer
==================

The object gbSnapshot, is a method function.

gbTrace -- provide tracing output during various computations in the    engine.
*******************************************************************************

Description
===========

gbTrace = n -- set the tracing level for the engine, to level n.
Meaningful values for the user n are 0, 1, 2, and 3.  Meaningful values for the
developers are 4, 5, 8, 10, 11, and 100; the parity also has an effect when the
value is at least 5.

The notations used in tracing are :
  * g       - a generator reduced to something nonzero and has been added to
    the basis.
  * m       - an S-pair reduced to something nonzero and has been added to the
    basis.
  * z       - an S-pair reduced to zero, and a syzygy has been recorded.
  * u       - an S-pair reduced to zero, but the syzygy need not be recorded.
  * o       - an S-pair or generator reduced to zero, but no new syzygy
    occurred.
  * r       - an S-pair has been removed.
  * {2}     - beginning to reduce the S-pairs of degree 2.
  * (7)     - 7 more S-pairs need to be reduced.
  * (8,9)   - 9 S-pairs, 8 predicted basis elements (see
    gb(...,Hilbert=>...))
  * .       - a minor has been computed, or something has happened while
    computing a resolution.

For the programmer
==================

The object gbTrace, is an integer.

gcd -- greatest common divisor
******************************

Synopsis
========

  * Usage:
        gcd(x,y,...)
  * Inputs:
      * x, an integer,
      * , or
      * a rational number,
      * , or
      * a ring element,
  * Outputs:
      * an integer, , or a rational number, or a
        ring element, the greatest common divisor of the
        arguments

Description
===========

+-----------------------+
|i1 : gcd(12,8,48)      |
|                       |
|o1 = 4                 |
+-----------------------+
|i2 : R = QQ[x,y,z];    |
+-----------------------+
|i3 : gcd(x^2*y,x*y^3^6)|
|                       |
|o3 = x*y               |
|                       |
|o3 : R                 |
+-----------------------+
|i4 : gcd(x^36-1,x^24-1)|
|                       |
|      12               |
|o4 = x   - 1           |
|                       |
|o4 : R                 |
+-----------------------+

See also
========

  * gcdCoefficients -- gcd with coefficients
  * lcm -- least common multiple

Ways to use gcd:
================

  * "gcd(List)"
  * "gcd(QQ,QQ)"
  * "gcd(QQ,ZZ)"
  * "gcd(RingElement,RingElement)"
  * "gcd(RingElement,ZZ)"
  * "gcd(Sequence)"
  * "gcd(ZZ,QQ)"
  * "gcd(ZZ,RingElement)"
  * "gcd(ZZ,ZZ)"
  * gcd() (missing documentation)

For the programmer
==================

The object gcd, is an associative binary method function.

gcdCoefficients -- gcd with coefficients
****************************************

Description
===========

gcdCoefficients(a,b) -- returns {d,r,s} so that a*r + b*s is the greatest
common divisor d of a and b.

Works for integers or elements of polynomial rings in onve variable.

See also
========

  * gcd -- greatest common divisor

Ways to use gcdCoefficients:
============================

  * "gcdCoefficients(RingElement,RingElement)"
  * "gcdCoefficients(ZZ,ZZ)"

For the programmer
==================

The object gcdCoefficients, is a method function.

GCstats -- information about the status of the garbage collector
****************************************************************

Description
===========

Macaulay2 uses the Hans Boehm garbage collector, to
reclaim unused memory.  The function GCstats provides information about its
status, such as the total number of bytes allocated, the current heap size, the
number of garbage collections done, the number of threads used in each
collection, the total cpu time spent in garbage collection, etc.

+---------------------------------------------------+
|i1 : s = GCstats()                                 |
|                                                   |
|o1 = HashTable{"bytesAlloc" => 15509914554        }|
|               "GC_free_space_divisor" => 3        |
|               "GC_LARGE_ALLOC_WARN_INTERVAL" => 1 |
|               "gcCpuTimeSecs" => 0                |
|               "heapSize" => 194224128             |
|               "numGCs" => 842                     |
|               "numGCThreads" => 6                 |
|                                                   |
|o1 : HashTable                                     |
+---------------------------------------------------+

The value returned is a hash table, from which individual bits of information
can be easily extracted, as follows.

+-----------------+
|i2 : s#"heapSize"|
|                 |
|o2 = 194224128   |
+-----------------+

Any entries whose keys are all upper case give the values of environment
variables affecting the operation of the garbage collector that have been
specified by the user.

For further information about the individual items in the table, we refer the
user to the source code and documentation of the garbage collector.

See also
========

  * GC garbage collector

For the programmer
==================

The object GCstats, is a compiled function.

GeneralOrderedMonoid -- the class of all ordered free commutative monoids
*************************************************************************

Description
===========

This is the class of free monoids that can be handled by the engine.
Elements of such monoids are implemented as instances of
MonoidElement.

See also
========

  * monoid -- make or retrieve a monoid

For the programmer
==================

The object GeneralOrderedMonoid, is a type,
with ancestor classes OrderedMonoid, <
Monoid < Type < MutableHashTable
< HashTable < Thing.

generateAssertions -- generate assert statements from experimental input
************************************************************************

Synopsis
========

  * Usage:
        generateAssertions x
  * Inputs:
      * x, a string whose non-comment non-blank lines are Macaulay2 expressions
        to be evaluated
  * Outputs:
      * a net whose lines are assert statements that assert that the
        expressions evaluate to the expected value, just computed

Description
===========

+----------------------------------+
|i1 : generateAssertions ///       |
|     2+2                          |
|     2^20                         |
|     ///                          |
|                                  |
|o1 =                              |
|     assert( (2+2) === 4 );       |
|     assert( (2^20) === 1048576 );|
+----------------------------------+
|i2 : value \ unstack oo           |
|                                  |
|o2 = {, }                         |
|                                  |
|o2 : List                         |
+----------------------------------+

Ways to use generateAssertions:
===============================

  * "generateAssertions(String)"

For the programmer
==================

The object generateAssertions, is a method function.

generator -- provide a single generator
***************************************

Synopsis
========

  * Usage:
        generator I
  * Inputs:
      * I, an ideal, or a module,
  * Outputs:
      * the single generator of I, if it has just one

Description
===========

If the number of apparent generators is greater than 1, then trim,
will be called.

+-----------------------------------+
|i1 : I = ideal (4,6)               |
|                                   |
|o1 = ideal (4, 6)                  |
|                                   |
|o1 : Ideal of ZZ                   |
+-----------------------------------+
|i2 : generator I                   |
|                                   |
|o2 = 2                             |
+-----------------------------------+
|i3 : M = image matrix {{4,6},{0,0}}|
|                                   |
|o3 = image | 4 6 |                 |
|           | 0 0 |                 |
|                                   |
|                               2   |
|o3 : ZZ-module, submodule of ZZ    |
+-----------------------------------+
|i4 : generator M                   |
|                                   |
|o4 = | 2 |                         |
|     | 0 |                         |
|                                   |
|o4 : Vector                        |
+-----------------------------------+

See also
========

  * generators -- provide matrix or list of generators

Ways to use generator:
======================

  * "generator(Ideal)"
  * "generator(Module)"

For the programmer
==================

The object generator, is a method function.

generators -- provide matrix or list of generators
**************************************************

Synopsis
========

  * Usage:
        generators x
        gens x
  * Inputs:
      * x
  * Optional inputs,:
      * CoefficientRing, => ..., default value
        null, only used if x is a ring
  * Outputs:
      * provides the generators of x in a convenient form, as a list or a
        matrix, depending on the type

Description
===========

Produces the generators of a Gröbner basis, a polynomial ring, an ideal, a free
module, a free group, a submodule given by means of generators (or for which
generators have been computed), or a free monoid.

Usually the result is a list of generators, but the generators of a module or
Gröbner basis are provided as the columns in a matrix. The matrix is stored in
a module M under M.generators, unless the matrix is the identity matrix.

The symbol gens is a synonym for generators.

See also
========

  * numgens -- the number of generators
  * Monoid -- the class of all monoids
  * GroebnerBasis -- the class of all Gröbner bases
  * Module -- the class of all modules
  * relations -- the defining relations
  * subquotient -- make a subquotient module

Ways to use generators:
=======================

  * generators(GroebnerBasis) -- the
    generator matrix of a Gröbner basis
  * generators(Ideal) -- the generator matrix of
    an ideal
  * "generators(MonomialIdeal)" -- see generators(Ideal),
    -- the generator matrix of an ideal
  * generators(Module) -- the generator matrix
    of a module
  * generators(Monoid) -- list of generators
  * generators(Ring) -- the list of generators of
    a ring

For the programmer
==================

The object generators, is a method function with options.

generators of ideals and modules
********************************

Synopsis
========

  * Usage:
        L_i
  * Inputs:
      * L, an ideal, a module, or a matrix,
      * i, an integer,
  * Outputs:
      * a ring element, or a vector, the i-th
        generator or column of L
As usual in Macaulay2, the first generator has index zero.

+---------------------------------------+
|i1 : R = QQ[a..d];                     |
+---------------------------------------+
|i2 : I = ideal(a^3, b^3-c^3, a^4, a*c);|
|                                       |
|o2 : Ideal of R                        |
+---------------------------------------+
|i3 : numgens I                         |
|                                       |
|o3 = 4                                 |
+---------------------------------------+
|i4 : I_0, I_2                          |
|                                       |
|       3   4                           |
|o4 = (a , a )                          |
|                                       |
|o4 : Sequence                          |
+---------------------------------------+

Notice that the generators are the ones provided.  Alternatively we can
minimalize the set of generators.
+-----------------------------+
|i5 : J = trim I              |
|                             |
|                  3    3   3 |
|o5 = ideal (a*c, b  - c , a )|
|                             |
|o5 : Ideal of R              |
+-----------------------------+
|i6 : J_0                     |
|                             |
|o6 = a*c                     |
|                             |
|o6 : R                       |
+-----------------------------+

Elements of modules are useful for producing submodules or quotients.
+-------------------------------------+
|i7 : M = cokernel matrix{{a,b},{c,d}}|
|                                     |
|o7 = cokernel | a b |                |
|              | c d |                |
|                                     |
|                            2        |
|o7 : R-module, quotient of R         |
+-------------------------------------+
|i8 : M_0                             |
|                                     |
|o8 = | 1 |                           |
|     | 0 |                           |
|                                     |
|o8 : M                               |
+-------------------------------------+
|i9 : M/M_0                           |
|                                     |
|o9 = cokernel | 1 a b |              |
|              | 0 c d |              |
|                                     |
|                            2        |
|o9 : R-module, quotient of R         |
+-------------------------------------+
|i10 : N = M/(a*M + R*M_0)            |
|                                     |
|o10 = cokernel | a 0 1 a b |         |
|               | 0 a 0 c d |         |
|                                     |
|                             2       |
|o10 : R-module, quotient of R        |
+-------------------------------------+
|i11 : N_0 == 0_N                     |
|                                     |
|o11 = true                           |
+-------------------------------------+
Columns of matrices may also be used as vectors in the target module.
+------------------------------------------------+
|i12 : M = matrix{{a,b,c},{c,d,a},{a-1,b-3,c-13}}|
|                                                |
|o12 = | a   b   c    |                          |
|      | c   d   a    |                          |
|      | a-1 b-3 c-13 |                          |
|                                                |
|              3      3                          |
|o12 : Matrix R  <-- R                           |
+------------------------------------------------+
|i13 : M_0                                       |
|                                                |
|o13 = |  a  |                                   |
|      |  c  |                                   |
|      | a-1 |                                   |
|                                                |
|       3                                        |
|o13 : R                                         |
+------------------------------------------------+
|i14 : prune((image M_{1,2})/(R*M_1))            |
|                                                |
|       1                                        |
|o14 = R                                         |
|                                                |
|o14 : R-module, free                            |
+------------------------------------------------+

Caveat
======

Fewer methods exist for manipulating vectors than other types, such as modules
and matrices

generators(GroebnerBasis) -- the generator matrix of a Gröbner basis
********************************************************************

Synopsis
========

  * Function: generators,
  * Usage:
        generators g
        gens g
  * Inputs:
      * g
  * Optional inputs,:
      * CoefficientRing, => ..., default value
        null, unused option
  * Outputs:
      * a matrix, whose columns are the generators of the
        Gröbner basis g

Description
===========

The following ideal defines a set of 18 points over the complex numbers.  We
compute a lexicographic Gröbner basis of the ideal.
+----------------------------------------------------------------+
|i1 : R = QQ[a..d, MonomialOrder=>Lex];                          |
+----------------------------------------------------------------+
|i2 : I = ideal(a^7-b-3, a*b-1, a*c^2-3, b*d-4);                 |
|                                                                |
|o2 : Ideal of R                                                 |
+----------------------------------------------------------------+
|i3 : gens gb I                                                  |
|                                                                |
|o3 = | d8-49152d-65536 16384c2-3d7+147456 16384b-d7+49152 4a-d ||
|                                                                |
|             1      4                                           |
|o3 : Matrix R  <-- R                                            |
+----------------------------------------------------------------+

See also
========

  * Gröbner bases

Ways to use this method:
========================

  * generators(GroebnerBasis) -- the
    generator matrix of a Gröbner basis

generators(Ideal) -- the generator matrix of an ideal
*****************************************************

Synopsis
========

  * Function: generators,
  * Usage:
        generators I
        gens I
  * Inputs:
      * I
  * Optional inputs,:
      * CoefficientRing, => ..., default value
        null, unused option
  * Outputs:
      * a matrix, the one-row matrix whose entries are the
        generators of I

Description
===========

Each ideal in Macaulay2 comes equipped with a one-row matrix with the
generators of the ideal. It is this matrix that is returned.
+----------------------------------------------+
|i1 : R = ZZ/101[a,b,c];                       |
+----------------------------------------------+
|i2 : I = ideal(a^2,a*b-2,c^4,a*c-1,a*c-1)     |
|                                              |
|             2            4                   |
|o2 = ideal (a , a*b - 2, c , a*c - 1, a*c - 1)|
|                                              |
|o2 : Ideal of R                               |
+----------------------------------------------+
|i3 : generators I                             |
|                                              |
|o3 = | a2 ab-2 c4 ac-1 ac-1 |                 |
|                                              |
|             1      5                         |
|o3 : Matrix R  <-- R                          |
+----------------------------------------------+
To obtain a list of generators, rather than a matrix, use
+----------------------------------------+
|i4 : first entries generators I         |
|                                        |
|       2            4                   |
|o4 = {a , a*b - 2, c , a*c - 1, a*c - 1}|
|                                        |
|o4 : List                               |
+----------------------------------------+
If you want to remove unnecessary generators, use trim.
+---------------------------------+
|i5 : I = trim I                  |
|                                 |
|                               2 |
|o5 = ideal (a*c - 1, a*b - 2, a )|
|                                 |
|o5 : Ideal of R                  |
+---------------------------------+
|i6 : gens I                      |
|                                 |
|o6 = | ac-1 ab-2 a2 |            |
|                                 |
|             1      3            |
|o6 : Matrix R  <-- R             |
+---------------------------------+

Ways to use this method:
========================

  * generators(Ideal) -- the generator matrix of
    an ideal
  * "generators(MonomialIdeal)"

generators(Module) -- the generator matrix of a module
******************************************************

Synopsis
========

  * Function: generators,
  * Usage:
        generators M
        gens M
  * Inputs:
      * M
  * Optional inputs,:
      * CoefficientRing, => ..., default value
        null, unused option
  * Outputs:
      * the matrix of generators of M.

Description
===========

Every module in Macaulay2 has, at least implicitly, a generator matrix and a
matrix of relations, both of which are matrices between free modules. This
function returns the generator matrix.  The module is generated by (the images
of) the columns of this matrix.
+---------------------------------------+
|i1 : R = GF(8,Variable=>a)             |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : GaloisField                       |
+---------------------------------------+
|i2 : f = R_0 ++ R_0^2 ++ R_0^3 ++ R_0^4|
|                                       |
|o2 = | a 0  0   0    |                 |
|     | 0 a2 0   0    |                 |
|     | 0 0  a+1 0    |                 |
|     | 0 0  0   a2+a |                 |
|                                       |
|             4      4                  |
|o2 : Matrix R  <-- R                   |
+---------------------------------------+
|i3 : generators image f                |
|                                       |
|o3 = | a 0  0   0    |                 |
|     | 0 a2 0   0    |                 |
|     | 0 0  a+1 0    |                 |
|     | 0 0  0   a2+a |                 |
|                                       |
|             4      4                  |
|o3 : Matrix R  <-- R                   |
+---------------------------------------+
|i4 : generators cokernel f             |
|                                       |
|o4 = | 1 0 0 0 |                       |
|     | 0 1 0 0 |                       |
|     | 0 0 1 0 |                       |
|     | 0 0 0 1 |                       |
|                                       |
|             4      4                  |
|o4 : Matrix R  <-- R                   |
+---------------------------------------+

Caveat
======

This function returns a matrix with the given generators.  This set of
generators may not be minimal, or sorted in any particular order. Use
trim(Module), or mingens(Module), instead.

See also
========

  * relations(Module) -- the defining relations

Ways to use this method:
========================

  * generators(Module) -- the generator matrix
    of a module

generators(Monoid) -- list of generators
****************************************

Synopsis
========

  * Function: generators,
  * Usage:
        generators M
        gens M
  * Inputs:
      * M
  * Optional inputs,:
      * CoefficientRing, => ..., default value
        null, unused option
  * Outputs:
      * a list, of generators

Description
===========

+-------------------------+
|i1 : R = QQ[a..d];       |
+-------------------------+
|i2 : M = monoid R        |
|                         |
|o2 = M                   |
|                         |
|o2 : GeneralOrderedMonoid|
+-------------------------+
|i3 : gens M              |
|                         |
|o3 = {a, b, c, d}        |
|                         |
|o3 : List                |
+-------------------------+

See also
========

  * monoid -- make or retrieve a monoid

Ways to use this method:
========================

  * generators(Monoid) -- list of generators

generators(Ring) -- the list of generators of a ring
****************************************************

Synopsis
========

  * Function: generators,
  * Usage:
        generators R
        gens R
  * Inputs:
      * R
  * Optional inputs,:
      * CoefficientRing => a ring, default value null, the
        coefficient ring over which to provide the generators of R, if
        different from the most recent one
  * Outputs:
      * a list, of generators

Description
===========

+-----------------------------------------+
|i1 : A = QQ[x,y];                        |
+-----------------------------------------+
|i2 : gens A                              |
|                                         |
|o2 = {x, y}                              |
|                                         |
|o2 : List                                |
+-----------------------------------------+
|i3 : kk = toField(QQ[t]/(t^3-t-1));      |
+-----------------------------------------+
|i4 : B = kk[x,y,z];                      |
+-----------------------------------------+
|i5 : generators B                        |
|                                         |
|o5 = {x, y, z}                           |
|                                         |
|o5 : List                                |
+-----------------------------------------+
|i6 : generators(B, CoefficientRing => QQ)|
|                                         |
|o6 = {x, y, z, t}                        |
|                                         |
|o6 : List                                |
+-----------------------------------------+

Ways to use this method:
========================

  * generators(Ring) -- the list of generators of
    a ring

genericMatrix -- make a generic matrix of variables
***************************************************

Synopsis
========

  * Usage:
        genericMatrix(R,r,m,n)
  * Inputs:
      * R, a ring,
      * r, a ring element, which is a variable in the ring
        R (this input is optional)
      * m, an integer,
      * n, an integer,
  * Outputs:
      * a matrix, with m rows and n columns whose entries are
        variables in the ring R starting with r

Description
===========

+---------------------------+
|i1 : R = ZZ[a..z];         |
+---------------------------+
|i2 : genericMatrix(R,a,2,4)|
|                           |
|o2 = | a c e g |           |
|     | b d f h |           |
|                           |
|             2      4      |
|o2 : Matrix R  <-- R       |
+---------------------------+
|i3 : genericMatrix(R,i,3,2)|
|                           |
|o3 = | i l |               |
|     | j m |               |
|     | k n |               |
|                           |
|             3      2      |
|o3 : Matrix R  <-- R       |
+---------------------------+

Omitting the input r is the same as having r be the first variable in R.
+-------------------------+
|i4 : genericMatrix(R,2,4)|
|                         |
|o4 = | a c e g |         |
|     | b d f h |         |
|                         |
|             2      4    |
|o4 : Matrix R  <-- R     |
+-------------------------+
|i5 : genericMatrix(R,3,2)|
|                         |
|o5 = | a d |             |
|     | b e |             |
|     | c f |             |
|                         |
|             3      2    |
|o5 : Matrix R  <-- R     |
+-------------------------+

See also
========

  * vars(Ring) -- row matrix of the variables
  * genericSkewMatrix -- make a generic skew
    symmetric matrix of variables
  * genericSymmetricMatrix -- make a generic
    symmetric matrix

Ways to use genericMatrix:
==========================

  * "genericMatrix(Ring,RingElement,ZZ,ZZ)"
  * "genericMatrix(Ring,ZZ,ZZ)"

For the programmer
==================

The object genericMatrix, is a method function.

genericSkewMatrix -- make a generic skew symmetric matrix of variables
**********************************************************************

Synopsis
========

  * Usage:
        genericSkewMatrix(R,r,n)
  * Inputs:
      * R, a ring,
      * r, a ring element, which is a variable in the ring
        R (this input is optional)
      * n, an integer,
  * Outputs:
      * a skew symmetric matrix, with n rows whose entries above
        the diagonal are the variables of R starting with r

Description
===========

A square matrix, M is skew symmetric if transpose(M) + M == 0.
+---------------------------------+
|i1 : R = ZZ[a..z];               |
+---------------------------------+
|i2 : M = genericSkewMatrix(R,a,3)|
|                                 |
|o2 = | 0  a  b |                 |
|     | -a 0  c |                 |
|     | -b -c 0 |                 |
|                                 |
|             3      3            |
|o2 : Matrix R  <-- R             |
+---------------------------------+
|i3 : transpose(M) + M == 0       |
|                                 |
|o3 = true                        |
+---------------------------------+
|i4 : genericSkewMatrix(R,d,5)    |
|                                 |
|o4 = | 0  d  e  f  g |           |
|     | -d 0  h  i  j |           |
|     | -e -h 0  k  l |           |
|     | -f -i -k 0  m |           |
|     | -g -j -l -m 0 |           |
|                                 |
|             5      5            |
|o4 : Matrix R  <-- R             |
+---------------------------------+

Omitting the input r is the same as having r be the first variable in R.
+---------------------------+
|i5 : genericSkewMatrix(R,3)|
|                           |
|o5 = | 0  a  b |           |
|     | -a 0  c |           |
|     | -b -c 0 |           |
|                           |
|             3      3      |
|o5 : Matrix R  <-- R       |
+---------------------------+
|i6 : genericSkewMatrix(R,5)|
|                           |
|o6 = | 0  a  b  c  d |     |
|     | -a 0  e  f  g |     |
|     | -b -e 0  h  i |     |
|     | -c -f -h 0  j |     |
|     | -d -g -i -j 0 |     |
|                           |
|             5      5      |
|o6 : Matrix R  <-- R       |
+---------------------------+

See also
========

  * vars(Ring) -- row matrix of the variables
  * genericMatrix -- make a generic matrix of variables
  * genericSymmetricMatrix -- make a generic
    symmetric matrix

Ways to use genericSkewMatrix:
==============================

  * "genericSkewMatrix(Ring,RingElement,ZZ)"
  * "genericSkewMatrix(Ring,ZZ)"

For the programmer
==================

The object genericSkewMatrix, is a method function.

genericSymmetricMatrix -- make a generic symmetric matrix
*********************************************************

Synopsis
========

  * Usage:
        genericSymmetricMatrix(R,r,n)
  * Inputs:
      * R, a ring,
      * r, a ring element, which is a variable in the ring
        R (this input is optional)
      * n, an integer,
  * Outputs:
      * a symmetric matrix, with n rows whose entries on and
        above the diagonal are the variables of R starting with r

Description
===========

A square matrix, M is symmetric if transpose(M) - M == 0.
+--------------------------------------+
|i1 : R = ZZ[a..z];                    |
+--------------------------------------+
|i2 : M = genericSymmetricMatrix(R,a,3)|
|                                      |
|o2 = | a b c |                        |
|     | b d e |                        |
|     | c e f |                        |
|                                      |
|             3      3                 |
|o2 : Matrix R  <-- R                  |
+--------------------------------------+
|i3 : transpose(M) - M == 0            |
|                                      |
|o3 = true                             |
+--------------------------------------+
|i4 : genericSymmetricMatrix(R,d,5)    |
|                                      |
|o4 = | d e f g h |                    |
|     | e i j k l |                    |
|     | f j m n o |                    |
|     | g k n p q |                    |
|     | h l o q r |                    |
|                                      |
|             5      5                 |
|o4 : Matrix R  <-- R                  |
+--------------------------------------+

Omitting the input r is the same as having r be the first variable in R.
+--------------------------------+
|i5 : genericSymmetricMatrix(R,3)|
|                                |
|o5 = | a b c |                  |
|     | b d e |                  |
|     | c e f |                  |
|                                |
|             3      3           |
|o5 : Matrix R  <-- R            |
+--------------------------------+
|i6 : genericSymmetricMatrix(R,5)|
|                                |
|o6 = | a b c d e |              |
|     | b f g h i |              |
|     | c g j k l |              |
|     | d h k m n |              |
|     | e i l n o |              |
|                                |
|             5      5           |
|o6 : Matrix R  <-- R            |
+--------------------------------+

See also
========

  * vars(Ring) -- row matrix of the variables
  * genericMatrix -- make a generic matrix of variables
  * genericSkewMatrix -- make a generic skew
    symmetric matrix of variables

Ways to use genericSymmetricMatrix:
===================================

  * "genericSymmetricMatrix(Ring,RingElement,ZZ)"
  * "genericSymmetricMatrix(Ring,ZZ)"

For the programmer
==================

The object genericSymmetricMatrix, is a
method function.

get -- get the contents of a file
*********************************

Synopsis
========

  * Usage:
        get f
  * Inputs:
      * f, a file, or a string.  If f is a string,
        then it is opened, as with openIn.
        Filenames starting with ! or with $ are treated specially, see
        openInOut.
  * Outputs:
      * a string containing the contents of the file.  If the file was already
        open and partially read, the remainder of the contents of the file are
        returned.
  * Consequences:
      * In the case where f is a file, its input side is closed.

Description
===========

+---------------------------------------+
|i1 : "test-file" << "hi there" << close|
|                                       |
|o1 = test-file                         |
|                                       |
|o1 : File                              |
+---------------------------------------+
|i2 : get "test-file"                   |
|                                       |
|o2 = hi there                          |
+---------------------------------------+
|i3 : removeFile "test-file"            |
+---------------------------------------+
|i4 : get "!date"                       |
|                                       |
|o4 = Fri Nov  1 10:23:13 AM EDT 2024   |
+---------------------------------------+

See also
========

  * read -- read from a file
  * removeFile -- remove a file
  * close -- close a file
  * File << Thing -- print to a file

Ways to use get:
================

  * "get(File)"
  * "get(String)"

For the programmer
==================

The object get, is a compiled function.

getc -- get a byte
******************

Description
===========

getc f obtains one byte from the input file f and provides it as a string of
length 1.  On end of file an empty string of is returned.

Bug: the name is cryptic and should be changed.

See also
========

  * File -- the class of all files

Ways to use getc:
=================

  * "getc(File)"

For the programmer
==================

The object getc, is a compiled function.

getChangeMatrix -- get the change of basis matrix
*************************************************

Description
===========

getChangeMatrix G -- for a Gröbner basis G, return the change of basis matrix
from the Gröbner basis to another generating set, usually a minimal, or
original, generating set.

The option ChangeMatrix, can be used with gb, to
enable the computation of the change of basis matrix.

Ways to use getChangeMatrix:
============================

  * "getChangeMatrix(GroebnerBasis)"

For the programmer
==================

The object getChangeMatrix, is a method function.

getGlobalSymbol -- create a global symbol in a global dictionary
****************************************************************

Synopsis
========

  * Usage:
        getGlobalSymbol(dict,nam)
        getGlobalSymbol nam
  * Inputs:
      * dict, an instance of the type GlobalDictionary,
      * nam, a string,
  * Outputs:
      * a global symbol in the dictionary dict whose name is the string nam,
        which will be created, if necessary
  * Consequences:
      * if a new symbol is created, it is stored under the name nam in the
        dictionary dict

Description
===========

If dict is omitted, then the first symbol found in the dictionaries listed in
dictionaryPath, will be returned. If none is found, one
will be created in the first dictionary listed in dictionaryPath,
unless it is not mutable, in which case an error will be
signalled; perhaps that behavior should be changed.

+------------------------------------+
|i1 : d = new Dictionary             |
|                                    |
|o1 = d                              |
|                                    |
|o1 : GlobalDictionary               |
+------------------------------------+
|i2 : sym = getGlobalSymbol(d,"foo") |
|                                    |
|o2 = foo                            |
|                                    |
|o2 : Symbol                         |
+------------------------------------+
|i3 : d                              |
|                                    |
|o3 = d                              |
|                                    |
|o3 : GlobalDictionary               |
+------------------------------------+
|i4 : peek d                         |
|                                    |
|o4 = GlobalDictionary{"foo" => foo} |
+------------------------------------+
|i5 : d#"foo" === sym                |
|                                    |
|o5 = true                           |
+------------------------------------+
|i6 : d#"asfd" = sym                 |
|                                    |
|o6 = foo                            |
|                                    |
|o6 : Symbol                         |
+------------------------------------+
|i7 : peek d                         |
|                                    |
|o7 = GlobalDictionary{"asfd" => foo}|
|                      "foo" => foo  |
+------------------------------------+

For the programmer
==================

The object getGlobalSymbol, is a compiled function.

getIOThreadMode -- get I/O thread mode
**************************************

Synopsis
========

  * Usage:
        getIOThreadMode()
        getIOThreadMode f
  * Inputs:
      * f, a file,
  * Consequences:
      * returns the I/O thread mode for the file f, or if no file is given,
        see stdio, as an integer:
          * 0 for unsynchronized
          * 1 for synchronized
          * 2 for exclusive

See also
========

  * setIOUnSynchronized -- unsynchronized I/O for
    threads
  * setIOSynchronized -- synchronized I/O for threads
  * setIOExclusive -- exclusive I/O for the current
    thread

For the programmer
==================

The object getIOThreadMode, is a compiled function.

getNetFile -- get the sequence of completed lines (nets) from a net file
************************************************************************

Synopsis
========

  * Usage:
        getNetFile n
  * Inputs:
      * n, an instance of the type NetFile,

Description
===========

This function is experimental.

For the programmer
==================

The object getNetFile, is a compiled function.

getNonUnit -- retrieve a previously discovered non-unit
*******************************************************

Synopsis
========

  * Usage:
        getNonUnit R
  * Inputs:
      * R, a ring, in which division by a non-unit may have been
        attempted
  * Outputs:
      * a ring element, the non-unit, if any, or
        null,

Description
===========

If a ring has been declared to be a field, using toField,
or frac, but a nonzero element is found to not
be a unit, this routine will return that element, otherwise null,
is returned.
+---------------------------+
|i1 : A = ZZ/101[a]/(a^2-1);|
+---------------------------+
|i2 : toField A             |
|                           |
|o2 = A[]                   |
|                           |
|o2 : PolynomialRing        |
+---------------------------+
|i3 : 1//(a-1)              |
|                           |
|o3 = 0                     |
|                           |
|o3 : A                     |
+---------------------------+
|i4 : getNonUnit A          |
+---------------------------+
Warning: this function does not work yet for divisions attempted in the course
of computing a Gröbner basis or resolution.

See also
========

  * toField -- declare that a ring is a field
  * frac -- construct a fraction field

For the programmer
==================

The object getNonUnit, is a function closure.

getPrimeWithRootOfUnity -- find a prime p with a primitive n-th root of unity r in ZZ/p
***************************************************************************************

Synopsis
========

  * Usage:
        (p,r)=getPrimeWithRootOfUnity(n,r1)
  * Inputs:
      * n, an integer, the exponent of the root of unity
      * r1, an integer, tentative root of unity
  * Optional inputs,:
      * Range => a sequence, default value (10000,30000), of
        integers (a,b)
  * Outputs:
      * p, an integer, a prime in the specified range. The default
        range is $(10^4,3*10^4)$
      * r, an integer, a primitive n-th root of unity mod p

Description
===========

We compute the prime p as a larger prime factor of $r1^n-1$. If the largest p
in the desired range does not work, we pass to $r1+1$ and repeat.

+------------------------------------------------------------+
|i1 : n = 12                                                 |
|                                                            |
|o1 = 12                                                     |
+------------------------------------------------------------+
|i2 : (p,r) = getPrimeWithRootOfUnity(n,5)                   |
|                                                            |
|o2 = (20593, 12)                                            |
|                                                            |
|o2 : Sequence                                               |
+------------------------------------------------------------+
|i3 : factor(r^n-1)                                          |
|                                                            |
|o3 = 5*7*11*13*19*29*157*20593                              |
|                                                            |
|o3 : Expression of class Product                            |
+------------------------------------------------------------+
|i4 : r^12%p==1, r^6%p==1, r^4%p==1                          |
|                                                            |
|o4 = (true, false, false)                                   |
|                                                            |
|o4 : Sequence                                               |
+------------------------------------------------------------+
|i5 : (p,r) = getPrimeWithRootOfUnity(12,11,Range=>(100,200))|
|                                                            |
|o5 = (157, 22)                                              |
|                                                            |
|o5 : Sequence                                               |
+------------------------------------------------------------+
|i6 : factor(r^n-1)                                          |
|                                                            |
|      2      2                                              |
|o6 = 3 5*7*13 23*97*157*463*1489                            |
|                                                            |
|o6 : Expression of class Product                            |
+------------------------------------------------------------+
|i7 : r^12%p==1, r^6%p==1, r^4%p==1                          |
|                                                            |
|o7 = (true, false, false)                                   |
|                                                            |
|o7 : Sequence                                               |
+------------------------------------------------------------+

See also
========

  * nextPrime -- compute the smallest prime greater than or
    equal to a given number
  * Range -- can be assigned a integral interval

Ways to use getPrimeWithRootOfUnity:
====================================

  * "getPrimeWithRootOfUnity(ZZ,ZZ)"

For the programmer
==================

The object getPrimeWithRootOfUnity, is a
method function with options.

getSymbol -- make a global user symbol from a string
****************************************************

Synopsis
========

  * Usage:
        getSymbol s
  * Inputs:
      * s, a string,
  * Outputs:
      * a symbol, a global symbol whose name is provided by the
        string s in the private dictionary for the package User (missing
        documentation).

Description
===========

+-----------------------------------+
|i1 : x = "aaaa"                    |
|                                   |
|o1 = aaaa                          |
+-----------------------------------+
|i2 : s = getSymbol x               |
|                                   |
|o2 = aaaa                          |
|                                   |
|o2 : Symbol                        |
+-----------------------------------+
|i3 : dictionary s                  |
|                                   |
|o3 = GlobalDictionary{...3...}     |
|                                   |
|o3 : GlobalDictionary              |
+-----------------------------------+
|i4 : s === getSymbol x             |
|                                   |
|o4 = true                          |
+-----------------------------------+
|i5 : keys User#"private dictionary"|
|                                   |
|o5 = {aaaa, x, s}                  |
|                                   |
|o5 : List                          |
+-----------------------------------+

Caveat
======

The old behavior, up to version 1.3.1, was to provide a previously existing
global symbol, if one exists and is visible in one of the dictionaries in
dictionaryPath, or, if not, to create a new global symbol in
the first mutable dictionary listed in dictionaryPath.

See also
========

  * getGlobalSymbol -- create a global symbol in a
    global dictionary

For the programmer
==================

The object getSymbol, is a function closure.

getWWW -- get a web page
************************

Description
===========

Synopsis
========

  * Usage:
        getWWW URL
  * Inputs:
      * URL, a string,
  * Outputs:
      * the contents of the web page, together with the http headers, at the
        address given by URL

Synopsis
========

  * Usage:
        getWWW(URL,TEXT)
  * Inputs:
      * URL, a string,
      * TEXT, a string,
  * Outputs:
      * obtain the contents of the web page addressed by URL from an http
        server, using the POST method, provided with TEXT

Accessing a secure web site (whose URL begins with https:) depends on your
having installed openssl on your system.

See also
========

  * splitWWW -- separate an http response into header and body

Ways to use getWWW:
===================

  * "getWWW(String)"
  * "getWWW(String,Nothing)"
  * "getWWW(String,String)"

For the programmer
==================

The object getWWW, is a method function.

GF -- make a finite field
*************************

Description
===========

Synopsis
========

  * Usage:
        GF(p,n)
        GF(q)
  * Inputs:
      * p, a prime number
      * n
      * Variable, => a symbol, default value null, the
        name to use for the generator of the field.  If null, then a is used.
      * SizeLimit, => an integer, default value 10000, the
        limit on the size of a Galois field whose elements will be represented
        internally as powers of the primitive element
  * Outputs:
      * a Galois field, a finite field with q = p^n
        elements
The generator of this ring is a primitive element: it generates the
multiplicative group of non-zero elements.

If the single argument form GF(q) is given, q should be a prime power q = p^n

+-----------------------------+
|i1 : A = GF(3,2,Variable=>b);|
+-----------------------------+
|i2 : ambient A               |
|                             |
|        ZZ                   |
|        --[b]                |
|         3                   |
|o2 = ----------              |
|      2                      |
|     b  - b - 1              |
|                             |
|o2 : QuotientRing            |
+-----------------------------+
|i3 : b^8                     |
|                             |
|o3 = 1                       |
|                             |
|o3 : A                       |
+-----------------------------+
|i4 : b^4                     |
|                             |
|o4 = -1                      |
|                             |
|o4 : A                       |
+-----------------------------+
+----------------+
|i5 : K = GF 8   |
|                |
|o5 = K          |
|                |
|o5 : GaloisField|
+----------------+
|i6 : a^3+a      |
|                |
|o6 = 1          |
|                |
|o6 : K          |
+----------------+

Synopsis
========

  * Usage:
        GF R
  * Inputs:
      * R, a ring, A quotient of a polynomial ring over ZZ/p in
        one variable, modulo an irreducible polynomial
      * PrimitiveElement, => ..., default value FindOne, either an
        element of R, or the symbol FindOne.  An element is
        primitive if it generates the multiplicative group of non-zero elements
        of R
      * SizeLimit, => an integer, default value 10000, the
        limit on the size of a Galois field whose elements will be represented
        internally as powers of the primitive element
  * Outputs:
      * a Galois field, a finite field isomorphic to R
+--------------------------------+
|i7 : A = ZZ/5[a]/(a^3-a-2)      |
|                                |
|o7 = A                          |
|                                |
|o7 : QuotientRing               |
+--------------------------------+
|i8 : B = GF A                   |
|                                |
|o8 = B                          |
|                                |
|o8 : GaloisField                |
+--------------------------------+
|i9 : C = ZZ/5[b]/(b^3+1+3*b^2+b)|
|                                |
|o9 = C                          |
|                                |
|o9 : QuotientRing               |
+--------------------------------+
|i10 : D = GF C                  |
|                                |
|o10 = D                         |
|                                |
|o10 : GaloisField               |
+--------------------------------+
|i11 : map(B,D,{a^2})            |
|                                |
|                   2            |
|o11 = map (B, D, {a })          |
|                                |
|o11 : RingMap B <-- D           |
+--------------------------------+

See also
========

  * toField -- declare that a ring is a field
  * finite fields

Ways to use GF:
===============

  * "GF(Ring)"
  * "GF(ZZ)"
  * "GF(ZZ,ZZ)"

For the programmer
==================

The object GF, is a method function with options.

global -- get a global symbol
*****************************

Description
===========

global s provides the global symbol s, even if s currently has a value.
+---------------+
|i1 : num       |
|               |
|o1 = num       |
|               |
|o1 : Symbol    |
+---------------+
|i2 : num = 5   |
|               |
|o2 = 5         |
+---------------+
|i3 : num       |
|               |
|o3 = 5         |
+---------------+
|i4 : global num|
|               |
|o4 = num       |
|               |
|o4 : Symbol    |
+---------------+

See also
========

  * local -- get a local symbol
  * symbol -- get a symbol

For the programmer
==================

The object global, is a keyword.

globalAssign -- global assignment, in function form
***************************************************

Synopsis
========

  * Usage:
        globalAssign(s,v)
  * Inputs:
      * s, a symbol, the symbol whose value is to be set
      * v, a thing, the value to be assigned to s
  * Outputs:
      * v, a thing,

Description
===========

This function mimics what happens in the interpreter when an assignment to a
global variable occurs, and can be useful if the name of the symbol is not
known when the code is written.  If the value changes, then
GlobalReleaseHook, and GlobalAssignHook,
are called appropriately.

+----------------------+
|i1 : x = y            |
|                      |
|o1 = y                |
|                      |
|o1 : Symbol           |
+----------------------+
|i2 : globalAssign(x,4)|
|                      |
|o2 = 4                |
+----------------------+
|i3 : x                |
|                      |
|o3 = y                |
|                      |
|o3 : Symbol           |
+----------------------+
|i4 : y                |
|                      |
|o4 = 4                |
+----------------------+

For the programmer
==================

The object globalAssign, is a function closure.

globalAssignFunction -- the standard method for the global assignment hook
**************************************************************************

Description
===========

globalAssignFunction -- the standard function that can be used as a method for
GlobalAssignHook, so that certain types of things, when
assigned to a global variable, will acquire the name of the global variable as
their name.  The companion function globalReleaseFunction,
is used to release the name when the global variable
gets reassigned.

Another thing done by this function is to apply use, to the thing.
This is used for polynomial rings to assign values to the symbols representing
the variables (indeterminates) in the ring.

+-----------------------------------------------------------------------------+
|i1 : X = new Type of MutableHashTable                                        |
|                                                                             |
|o1 = X                                                                       |
|                                                                             |
|o1 : Type                                                                    |
+-----------------------------------------------------------------------------+
|i2 : x = new X                                                               |
|                                                                             |
|o2 = X{}                                                                     |
|                                                                             |
|o2 : X                                                                       |
+-----------------------------------------------------------------------------+
|i3 : X.GlobalAssignHook = globalAssignFunction                               |
|                                                                             |
|o3 = globalAssignFunction                                                    |
|                                                                             |
|o3 : FunctionClosure                                                         |
+-----------------------------------------------------------------------------+
|i4 : X.GlobalReleaseHook = globalReleaseFunction                             |
|                                                                             |
|o4 = globalReleaseFunction                                                   |
|                                                                             |
|o4 : FunctionClosure                                                         |
+-----------------------------------------------------------------------------+
|i5 : x' = new X                                                              |
|                                                                             |
|o5 = x'                                                                      |
|                                                                             |
|o5 : X                                                                       |
+-----------------------------------------------------------------------------+
|i6 : t = {x,x'}                                                              |
|                                                                             |
|o6 = {X{}, x'}                                                               |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : x = x' = 44                                                             |
|                                                                             |
|o7 = 44                                                                      |
+-----------------------------------------------------------------------------+
|i8 : t                                                                       |
|                                                                             |
|o8 = {X{}, X{}}                                                              |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : code globalAssignFunction                                               |
|                                                                             |
|o9 = /usr/local/share/Macaulay2/Core/startup.m2.in:191:28-                   |
|     195:11: --source code:                                                  |
|          globalAssignFunction = (X,x) -> (                                  |
|               if not instance(X,Symbol) then error("globalAssignFunction:   |
|               if not hasAttribute(x,ReverseDictionary) then setAttribute(x  |
|               use x;                                                        |
|               );                                                            |
|-----------------------------------------------------------------------------|
|expected a symbol: ", toString X);                                           |
|,ReverseDictionary,X);                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * symbol -- get a symbol
  * SelfInitializingType -- the class of all self
    initializing types

For the programmer
==================

The object globalAssignFunction, is a
function closure.

GlobalAssignHook -- hook for assignment to global variables
***********************************************************

Synopsis
========

  * Usage:
        X.GlobalAssignHook = f
  * Inputs:
      * X, a type,
      * f, a function,  of two variables: the symbol to which
        a value is about to be assigned, and the value being assigned
  * Consequences:
      * f will be called just before an assignment to a global variable of an
        instance of class X occurs

Description
===========

This technique is used, for example, for instances of Type, and
Ring, to arrange for the name of the type or ring to be set to the
name of the global variable to which it is first assigned.  The functions
globalAssignFunction, and globalReleaseFunction,
may installed as methods for this purpose.

+-----------------------------------------------------------------------------+
|i1 : RR.GlobalAssignHook = (sym,val) -> << "--about to assign " << val << "  |
|-----------------------------------------------------------------------------|
|to " << sym << endl;                                                         |
+-----------------------------------------------------------------------------+
|i2 : a = 4.5                                                                 |
|--about to assign 4.5 to a                                                   |
|                                                                             |
|o2 = 4.5                                                                     |
|                                                                             |
|o2 : RR (of precision 53)                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * GlobalReleaseHook

For the programmer
==================

The object GlobalAssignHook, is a symbol.

globalAssignment -- install standard global assignment method
*************************************************************

Synopsis
========

  * Usage:
        globalAssignment X
  * Inputs:
      * X, a type,
  * Consequences:
      * the functions globalAssignFunction, and
        globalReleaseFunction, are installed in
        the type X under GlobalAssignHook, and
        GlobalReleaseHook, respectively.  The effect is
        that when an object of type X is assigned to a global variable, the
        function use, is called on it, and thereafter that object
        will print out as the name of the variable.

Description
===========

One type for which this has been done is Ring, as illustrated in
the following example.
+-----------------------+
|i1 : S := QQ[x]        |
|                       |
|o1 = QQ[x]             |
|                       |
|o1 : PolynomialRing    |
+-----------------------+
|i2 : S                 |
|                       |
|o2 = QQ[x]             |
|                       |
|o2 : PolynomialRing    |
+-----------------------+
|i3 : S^3               |
|                       |
|            3          |
|o3 = (QQ[x])           |
|                       |
|o3 : QQ[x]-module, free|
+-----------------------+
|i4 : R = S             |
|                       |
|o4 = R                 |
|                       |
|o4 : PolynomialRing    |
+-----------------------+
|i5 : S                 |
|                       |
|o5 = R                 |
|                       |
|o5 : PolynomialRing    |
+-----------------------+
|i6 : S^3               |
|                       |
|      3                |
|o6 = R                 |
|                       |
|o6 : R-module, free    |
+-----------------------+

For the programmer
==================

The object globalAssignment, is a function closure.

globalAssignmentHooks -- assignment hooks for global symbols
************************************************************

Synopsis
========

  * Usage:
        globalAssignmentHooks#s = f
  * Inputs:
      * s, a symbol, a global symbol
      * f, a function, a function of two arguments, f =
        (sym,val) -> ...; the argument sym is the symbol whose value is about
        to be assigned to, and val is the value about be assigned to it
  * Consequences:
      * whenever an assignment statement of the form s=e is done, the
        expression f(s,e) is first evaluated

See also
========

  * globalAssignFunction -- the standard method
    for the global assignment hook

For the programmer
==================

The object globalAssignmentHooks, is a
mutable hash table.

GlobalDictionary -- the class of all global dictionaries
********************************************************

See also
========

  * dictionaryPath
  * LocalDictionary -- the class of all local
    dictionaries

Protected objects of class GlobalDictionary:
============================================

  * OutputDictionary -- the dictionary for output
    values
  * PackageDictionary -- the dictionary for names of
    packages

For the programmer
==================

The object GlobalDictionary, is a type,
with ancestor classes Dictionary, < Thing.

globalReleaseFunction -- the standard method for the global variable release hook
*********************************************************************************

Description
===========

globalReleaseFunction -- the standard function that can be used as a method for
GlobalReleaseHook, so that certain types of things,
which have acquired as their name the name of a global variable to which they
have been assigned, will lose that name when a different value is assigned to
the variable.

See also
========

  * globalAssignFunction -- the standard method
    for the global assignment hook

For the programmer
==================

The object globalReleaseFunction, is a
function closure.

GlobalReleaseHook
*****************

Description
===========

GlobalReleaseHook -- a method name that is consulted when an assignment to a
global variable is about to occur.

The method should be a function of two variables: the symbol to which a value
is being assigned, and the old value about to be overwritten. The method should
be stored under the name GlobalReleaseHook in the class of the old value.  It
is executed before the assignment occurs, and before the execution of
GlobalAssignHook.

+----------------------------------------------------------+
|i1 : RR.GlobalReleaseHook = (sym,val) -> << concatenate ( |
|          "assigning ", toString val, " to ", toString sym|
|          ) << endl                                       |
|                                                          |
|o1 = FunctionClosure[stdio:1:23-3:14]                     |
|                                                          |
|o1 : FunctionClosure                                      |
+----------------------------------------------------------+
|i2 : a=4.5                                                |
|                                                          |
|o2 = 4.5                                                  |
|                                                          |
|o2 : RR (of precision 53)                                 |
+----------------------------------------------------------+
|i3 : a=5.4                                                |
|assigning 4.5 to a                                        |
|                                                          |
|o3 = 5.4                                                  |
|                                                          |
|o3 : RR (of precision 53)                                 |
+----------------------------------------------------------+

See also
========

  * GlobalAssignHook -- hook for assignment to global
    variables

For the programmer
==================

The object GlobalReleaseHook, is a symbol.

graded modules
**************

GradedModule -- the class of all graded modules
***********************************************

Description
===========

A new graded module can be made with 'M = new GradedModule'. The i-th module
can be installed with a statement like M#i=N, and can be retrieved with an
expression like M_i.  The ground ring should be installed with a statement like
M.ring = R.

See also
========

  * GradedModuleMap -- the class of all maps between
    graded modules

Types of graded module:
=======================

  * ChainComplex -- the class of all chain complexes

Functions and methods returning a graded module:
================================================

  * "ambient(GradedModule)" -- see ambient(Module),
    -- ambient free module
  * "GradedModule ++ GradedModule" -- see ChainComplex ++ ChainComplex,
    -- direct sum
  * "coimage(GradedModuleMap)" -- see coimage, -- coimage of a
    map
  * "cokernel(GradedModuleMap)" -- see cokernel, -- cokernel of
    a map of modules, graded modules, or chaincomplexes
  * "cover(GradedModule)" -- see cover(Module), -- get
    the covering free module
  * "directSum(GradedModule)" -- see directSum, -- direct sum
    of modules or maps
  * "gradedModule(ChainComplex)" -- see gradedModule, --
    make a graded module
  * "gradedModule(List)" -- see gradedModule, -- make a
    graded module
  * "gradedModule(Module)" -- see gradedModule, -- make a
    graded module
  * "gradedModule(Sequence)" -- see gradedModule, -- make a
    graded module
  * GradedModule ** GradedModule -- a
    binary operator, usually used for tensor product or Cartesian product
  * GradedModule ** Module -- a binary
    operator, usually used for tensor product or Cartesian product
  * "Module ** GradedModule" -- see GradedModule ** Module,
    -- a binary operator, usually used for tensor product or
    Cartesian product
  * GradedModule Array -- degree shift
  * HH ChainComplex -- homology of a chain complex
  * "image(GradedModuleMap)" -- see image, -- image of a map
  * "kernel(GradedModuleMap)" -- see kernel(ChainComplexMap),
    -- kernel of a chain complex map
  * "minimalPresentation(GradedModule)" -- see
    minimalPresentation(Module), -- minimal
    presentation of a module
  * "prune(GradedModule)" -- see minimalPresentation(Module),
    -- minimal presentation of a module
  * "GradedModule ++ Module" -- see Module ++ Module,
    -- direct sum of modules
  * "Module ++ GradedModule" -- see Module ++ Module,
    -- direct sum of modules
  * source(GradedModuleMap) -- find the
    source of a map of graded modules
  * "super(GradedModule)" -- see super, -- get the ambient module
  * target(GradedModuleMap) -- find the
    target of a map of graded modules

Methods that use a graded module:
=================================

  * "betti(GradedModule)" -- see betti, -- display or modify a
    Betti diagram
  * ChainComplex ** GradedModule, --
    tensor product
  * "GradedModule _ ZZ" -- see ChainComplex _ ZZ, --
    component
  * chainComplex(GradedModule) -- make a
    chain complex from a graded module
  * "complete(GradedModule)" -- see complete,
  * "components(GradedModule)" -- see components, -- list the
    components of a direct sum
  * "formation(GradedModule)" -- see formation, -- recover the
    methods used to make a module
  * GradedModule ** ChainComplex, --
    tensor product
  * GradedModule == GradedModule (missing documentation)
  * "isDirectSum(GradedModule)" -- see isDirectSum, --
    whether something is a direct sum
  * "isSupportedInZeroLocus(Ideal,GradedModule)" -- see
    isSupportedInZeroLocus (Saturation), -- whether
    support of a module is contained in the zero locus of the (irrelevant)
    ideal
  * length(GradedModule) -- length of a graded
    module
  * "map(GradedModule,GradedModule,Function)" -- see
    map(ChainComplex,ChainComplex,Function),
    -- make a map of chain
    complexes
  * max(GradedModule)
  * min(GradedModule)
  * "rank(GradedModule)" -- see rank, -- compute the rank
  * "ring(GradedModule)" -- see ring, -- get the associated ring of
    an object
  * "tensorAssociativity(GradedModule,GradedModule,GradedModule)" -- see
    tensorAssociativity, -- associativity isomorphisms for
    tensor products

For the programmer
==================

The object GradedModule, is a type, with
ancestor classes MutableHashTable, < HashTable
< Thing.

gradedModule -- make a graded module
************************************

Synopsis
========

  * Usage:
        gradedModule v
  * Inputs:
      * v, a list, a module, or a list or sequence of modules
  * Outputs:
      * the graded module with the i-th element of v installed as its i-th
        component

Description
===========

+-----------------------------------+
|i1 : gradedModule ZZ^2             |
|                                   |
|           2                       |
|o1 = 0 : ZZ                        |
|                                   |
|o1 : GradedModule                  |
+-----------------------------------+
|i2 : gradedModule(ZZ^2,ZZ^3,ZZ^400)|
|                                   |
|           2                       |
|o2 = 0 : ZZ                        |
|                                   |
|           3                       |
|     1 : ZZ                        |
|                                   |
|           400                     |
|     2 : ZZ                        |
|                                   |
|o2 : GradedModule                  |
+-----------------------------------+
If v is a chain complex, then the return value is the
graded module underlying it.
+---------------------------+
|i3 : R = QQ[x,y]           |
|                           |
|o3 = R                     |
|                           |
|o3 : PolynomialRing        |
+---------------------------+
|i4 : C = res coker vars R  |
|                           |
|      1      2      1      |
|o4 = R  <-- R  <-- R  <-- 0|
|                           |
|     0      1      2      3|
|                           |
|o4 : ChainComplex          |
+---------------------------+
|i5 : gradedModule C        |
|                           |
|          1                |
|o5 = 0 : R                 |
|                           |
|          2                |
|     1 : R                 |
|                           |
|          1                |
|     2 : R                 |
|                           |
|     3 : 0                 |
|                           |
|o5 : GradedModule          |
+---------------------------+

Ways to use gradedModule:
=========================

  * "gradedModule(ChainComplex)"
  * "gradedModule(List)"
  * "gradedModule(Module)"
  * "gradedModule(Sequence)"

For the programmer
==================

The object gradedModule, is a method function with a single argument.

GradedModule ** ChainComplex -- tensor product
**********************************************

Synopsis
========

  * Operator: **,

Description
===========

C**D -- the tensor product of a graded module with a chain complex.

The result is a chain complex.

Ways to use this method:
========================

  * GradedModule ** ChainComplex, --
    tensor product

GradedModule ** GradedModule -- a binary operator, usually used for tensor product or Cartesian product
*******************************************************************************************************

Synopsis
========

  * Operator: **,
  * Usage:
        C ** D
  * Inputs:
      * C
      * D
  * Outputs:
      * the tensor product of C with D

Description
===========

+-------------------------------------+
|i1 : C = gradedModule(ZZ^1,ZZ^6,ZZ^2)|
|                                     |
|           1                         |
|o1 = 0 : ZZ                          |
|                                     |
|           6                         |
|     1 : ZZ                          |
|                                     |
|           2                         |
|     2 : ZZ                          |
|                                     |
|o1 : GradedModule                    |
+-------------------------------------+
|i2 : C ** C                          |
|                                     |
|           1                         |
|o2 = 0 : ZZ                          |
|                                     |
|           12                        |
|     1 : ZZ                          |
|                                     |
|           40                        |
|     2 : ZZ                          |
|                                     |
|           24                        |
|     3 : ZZ                          |
|                                     |
|           4                         |
|     4 : ZZ                          |
|                                     |
|o2 : GradedModule                    |
+-------------------------------------+
|i3 : betti oo                        |
|                                     |
|            0  1  2  3 4             |
|o3 = total: 1 12 40 24 4             |
|        -4: .  .  .  . 4             |
|        -3: .  .  . 24 .             |
|        -2: .  . 40  . .             |
|        -1: . 12  .  . .             |
|         0: 1  .  .  . .             |
|                                     |
|o3 : BettiTally                      |
+-------------------------------------+

Ways to use this method:
========================

  * GradedModule ** GradedModule -- a
    binary operator, usually used for tensor product or Cartesian product

GradedModule ** Module -- a binary operator, usually used for tensor product or Cartesian product
*************************************************************************************************

Synopsis
========

  * Operator: **,
  * Usage:
        C ** M
  * Inputs:
      * C
      * M
  * Outputs:
      * the tensor product of C with M

Description
===========

+-------------------------------------+
|i1 : C = gradedModule(ZZ^1,ZZ^6,ZZ^2)|
|                                     |
|           1                         |
|o1 = 0 : ZZ                          |
|                                     |
|           6                         |
|     1 : ZZ                          |
|                                     |
|           2                         |
|     2 : ZZ                          |
|                                     |
|o1 : GradedModule                    |
+-------------------------------------+
|i2 : C ** ZZ^3                       |
|                                     |
|           3                         |
|o2 = 0 : ZZ                          |
|                                     |
|           18                        |
|     1 : ZZ                          |
|                                     |
|           6                         |
|     2 : ZZ                          |
|                                     |
|o2 : GradedModule                    |
+-------------------------------------+
|i3 : betti oo                        |
|                                     |
|            0  1 2                   |
|o3 = total: 3 18 6                   |
|        -2: .  . 6                   |
|        -1: . 18 .                   |
|         0: 3  . .                   |
|                                     |
|o3 : BettiTally                      |
+-------------------------------------+

It also works the other way around.

+-----------------+
|i4 : ZZ^3 ** C   |
|                 |
|           3     |
|o4 = 0 : ZZ      |
|                 |
|           18    |
|     1 : ZZ      |
|                 |
|           6     |
|     2 : ZZ      |
|                 |
|o4 : GradedModule|
+-----------------+

Ways to use this method:
========================

  * GradedModule ** Module -- a binary
    operator, usually used for tensor product or Cartesian product
  * "Module ** GradedModule"

GradedModule Array -- degree shift
**********************************

Synopsis
========

  * Operator: SPACE,

Description
===========

C[i] -- shifts the graded module C, producing a new graded module D in which
D_j is C_(i+j).

Ways to use this method:
========================

  * GradedModule Array -- degree shift

GradedModuleMap -- the class of all maps between graded modules
***************************************************************

See also
========

  * GradedModule -- the class of all graded modules

Types of graded module map:
===========================

  * ChainComplexMap -- the class of all maps between
    chain complexes

Functions and methods returning a graded module map:
====================================================

  * "GradedModuleMap * GradedModuleMap" -- see *, -- a binary
    operator, usually used for multiplication
  * "RingElement * GradedModuleMap" -- see *, -- a binary operator,
    usually used for multiplication
  * "GradedModuleMap + GradedModuleMap" -- see +, -- a unary or binary
    operator, usually used for addition
  * "GradedModuleMap + RingElement" -- see +, -- a unary or binary
    operator, usually used for addition
  * "RingElement + GradedModuleMap" -- see +, -- a unary or binary
    operator, usually used for addition
  * "- GradedModuleMap" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "GradedModuleMap - GradedModuleMap" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "GradedModuleMap - RingElement" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "RingElement - GradedModuleMap" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "GradedModuleMap ^ ZZ" -- see ChainComplexMap ^ ZZ,
    -- iterated composition
  * "gradedModuleMap(List)" -- see gradedModuleMap, --
    make a map of graded modules
  * "gradedModuleMap(Matrix)" -- see gradedModuleMap, --
    make a map of graded modules
  * "gradedModuleMap(Sequence)" -- see gradedModuleMap,
    -- make a map of graded modules
  * HH ChainComplexMap -- homology of a chain
    complex map
  * "map(GradedModule,GradedModule,Function)" -- see
    map(ChainComplex,ChainComplex,Function),
    -- make a map of chain
    complexes
  * "GradedModuleMap ++ GradedModuleMap" -- see Matrix ++ Matrix,
    -- direct sum of maps
  * "GradedModuleMap ^ Array" -- see Matrix ^ Array, --
    component of map corresponding to summand of target
  * "GradedModuleMap _ Array" -- see Matrix _ Array, --
    component of map corresponding to summand of source
  * "minimalPresentation(GradedModuleMap)" -- see
    minimalPresentation(Module), -- minimal
    presentation of a module
  * "prune(GradedModuleMap)" -- see minimalPresentation(Module),
    -- minimal presentation of a module
  * "tensorAssociativity(GradedModule,GradedModule,GradedModule)" -- see
    tensorAssociativity, -- associativity isomorphisms for
    tensor products

Methods that use a graded module map:
=====================================

  * "GradedModuleMap _ ZZ" -- see ChainComplexMap _ ZZ,
    -- component map
  * "coimage(GradedModuleMap)" -- see coimage, -- coimage of a
    map
  * "cokernel(GradedModuleMap)" -- see cokernel, -- cokernel of
    a map of modules, graded modules, or chaincomplexes
  * "components(GradedModuleMap)" -- see components, -- list
    the components of a direct sum
  * degree(GradedModuleMap) (missing documentation)
  * "formation(GradedModuleMap)" -- see formation, -- recover
    the methods used to make a module
  * GradedModuleMap == GradedModuleMap (missing documentation)
  * GradedModuleMap == RingElement (missing documentation)
  * GradedModuleMap == ZZ (missing documentation)
  * GradedModuleMap | GradedModuleMap,
    -- a binary operator, often used for horizontal concatenation
  * GradedModuleMap || GradedModuleMap
    -- a binary operator, often used for vertical
    concatenation
  * "image(GradedModuleMap)" -- see image, -- image of a map
  * "kernel(GradedModuleMap)" -- see kernel(ChainComplexMap),
    -- kernel of a chain complex map
  * "ring(GradedModuleMap)" -- see ring, -- get the associated ring
    of an object
  * RingElement == GradedModuleMap (missing documentation)
  * source(GradedModuleMap) -- find the
    source of a map of graded modules
  * target(GradedModuleMap) -- find the
    target of a map of graded modules
  * ZZ == GradedModuleMap (missing documentation)

For the programmer
==================

The object GradedModuleMap, is a type, with
ancestor classes MutableHashTable, < HashTable
< Thing.

gradedModuleMap -- make a map of graded modules
***********************************************

Synopsis
========

  * Usage:
        gradedModuleMap v
  * Inputs:
      * v, a list, a matrix, or a list or sequence of matrices
  * Outputs:
      * the graded module map with the i-th element of v installed as its i-th
        component

Description
===========

+---------------------------------------------------------+
|i1 : gradedModuleMap(random(ZZ^3,ZZ^4),random(ZZ^2,ZZ^2))|
|                                                         |
|          3                    4                         |
|o1 = 0: ZZ  <--| 8 7 3 8 |-- ZZ  :0                      |
|               | 1 8 7 5 |                               |
|               | 3 3 8 7 |                               |
|                                                         |
|          2                2                             |
|     1: ZZ  <--| 8 2 |-- ZZ  :1                          |
|               | 5 3 |                                   |
|                                                         |
|o1 : GradedModuleMap                                     |
+---------------------------------------------------------+

Ways to use gradedModuleMap:
============================

  * "gradedModuleMap(List)"
  * "gradedModuleMap(Matrix)"
  * "gradedModuleMap(Sequence)"

For the programmer
==================

The object gradedModuleMap, is a method function with a single argument.

GradedModuleMap | GradedModuleMap -- a binary operator, often used for horizontal concatenation
***********************************************************************************************

Synopsis
========

  * Operator: |,
  * Usage:
        f|g
  * Inputs:
      * f
      * g
  * Outputs:
      * the map of graded modules whose component in degree i is f_i|g_i see
        Matrix | Matrix,

Description
===========

+------------------------------------------------------+
|i1 : f = gradedModuleMap( matrix "1;2", matrix "2,3" )|
|                                                      |
|          2              1                            |
|o1 = 0: ZZ  <--| 1 |-- ZZ  :0                         |
|               | 2 |                                  |
|                                                      |
|          1                2                          |
|     1: ZZ  <--| 2 3 |-- ZZ  :1                       |
|                                                      |
|o1 : GradedModuleMap                                  |
+------------------------------------------------------+
|i2 : f|f                                              |
|                                                      |
|          2                2                          |
|o2 = 0: ZZ  <--| 1 1 |-- ZZ  :0                       |
|               | 2 2 |                                |
|                                                      |
|          1                    4                      |
|     1: ZZ  <--| 2 3 2 3 |-- ZZ  :1                   |
|                                                      |
|o2 : GradedModuleMap                                  |
+------------------------------------------------------+

Ways to use this method:
========================

  * GradedModuleMap | GradedModuleMap,
    -- a binary operator, often used for horizontal concatenation

GradedModuleMap || GradedModuleMap -- a binary operator, often used for vertical concatenation
**********************************************************************************************

Synopsis
========

  * Operator: ||,
  * Usage:
        f||g
  * Inputs:
      * f
      * g
  * Outputs:
      * the map of graded modules whose component in degree i is f_i||g_i see
        Matrix || Matrix,

Description
===========

+------------------------------------------------------+
|i1 : f = gradedModuleMap( matrix "1;2", matrix "2,3" )|
|                                                      |
|          2              1                            |
|o1 = 0: ZZ  <--| 1 |-- ZZ  :0                         |
|               | 2 |                                  |
|                                                      |
|          1                2                          |
|     1: ZZ  <--| 2 3 |-- ZZ  :1                       |
|                                                      |
|o1 : GradedModuleMap                                  |
+------------------------------------------------------+
|i2 : f||f                                             |
|                                                      |
|          4              1                            |
|o2 = 0: ZZ  <--| 1 |-- ZZ  :0                         |
|               | 2 |                                  |
|               | 1 |                                  |
|               | 2 |                                  |
|                                                      |
|          2                2                          |
|     1: ZZ  <--| 2 3 |-- ZZ  :1                       |
|               | 2 3 |                                |
|                                                      |
|o2 : GradedModuleMap                                  |
+------------------------------------------------------+

Ways to use this method:
========================

  * GradedModuleMap || GradedModuleMap
    -- a binary operator, often used for vertical
    concatenation

Grassmannian(ZZ,ZZ) -- the Grassmannian of linear subspaces of a vector space
*****************************************************************************

Synopsis
========

  * Function: Grassmannian,
  * Usage:
        Grassmannian(k,r)
        Grassmannian(k,r,R)
  * Inputs:
      * k
      * r
  * Optional inputs,:
      * CoefficientRing => a ring, default value ZZ, the
        coefficient ring for the polynomial ring to be made
      * Variable => a symbol, default value "p", the base symbol
        for the indexed variables to be used.  The subscripts are the elements
        of subsets(n+1,k+1), converted to sequences and, if k is 0, converted
        to integers.
  * Outputs:
                                                                             r
      * the ideal of the Grassmannian variety of all projective k-planes in P

Description
===========

If a polynomial ring R is given as the third argument, then the resulting ideal
is moved to that ring.
+-----------------------------------------------------------------------------+
|i1 : Grassmannian(1,3)                                                       |
|                                                                             |
|o1 = ideal(p   p    - p   p    + p   p   )                                   |
|            1,2 0,3    0,2 1,3    0,1 2,3                                    |
|                                                                             |
|o1 : Ideal of ZZ[p   ..p   , p   , p   , p   , p   ]                         |
|                  0,1   0,2   1,2   0,3   1,3   2,3                          |
+-----------------------------------------------------------------------------+
|i2 : J = Grassmannian(2,5, CoefficientRing => ZZ/31, Variable => T)          |
|                                                                             |
|o2 = ideal (T     T      - T     T      + T     T     , T     T      -       |
|             2,3,5 1,4,5    1,3,5 2,4,5    1,2,5 3,4,5   2,3,4 1,4,5         |
|     ------------------------------------------------------------------------|
|     T     T      + T     T     , T     T      - T     T      + T     T     ,|
|      1,3,4 2,4,5    1,2,4 3,4,5   2,3,5 0,4,5    0,3,5 2,4,5    0,2,5 3,4,5 |
|     ------------------------------------------------------------------------|
|     T     T      - T     T      + T     T     , T     T      - T     T      |
|      1,3,5 0,4,5    0,3,5 1,4,5    0,1,5 3,4,5   1,2,5 0,4,5    0,2,5 1,4,5 |
|     ------------------------------------------------------------------------|
|     + T     T     , T     T      - T     T      + T     T     , T     T     |
|        0,1,5 2,4,5   2,3,4 0,4,5    0,3,4 2,4,5    0,2,4 3,4,5   1,3,4 0,4,5|
|     ------------------------------------------------------------------------|
|     - T     T      + T     T     , T     T      - T     T      +            |
|        0,3,4 1,4,5    0,1,4 3,4,5   1,2,4 0,4,5    0,2,4 1,4,5              |
|     ------------------------------------------------------------------------|
|     T     T     , T     T      - T     T      + T     T      - T     T     ,|
|      0,1,4 2,4,5   1,2,3 0,4,5    0,2,3 1,4,5    0,1,3 2,4,5    0,1,2 3,4,5 |
|     ------------------------------------------------------------------------|
|     T     T      - T     T      + T     T     , T     T      - T     T      |
|      2,3,4 1,3,5    1,3,4 2,3,5    1,2,3 3,4,5   1,2,5 0,3,5    0,2,5 1,3,5 |
|     ------------------------------------------------------------------------|
|     + T     T     , T     T      - T     T      + T     T     , T     T     |
|        0,1,5 2,3,5   2,3,4 0,3,5    0,3,4 2,3,5    0,2,3 3,4,5   1,3,4 0,3,5|
|     ------------------------------------------------------------------------|
|     - T     T      + T     T     , T     T      - T     T      +            |
|        0,3,4 1,3,5    0,1,3 3,4,5   1,2,4 0,3,5    0,2,4 1,3,5              |
|     ------------------------------------------------------------------------|
|     T     T      + T     T     , T     T      - T     T      + T     T     ,|
|      0,1,4 2,3,5    0,1,2 3,4,5   1,2,3 0,3,5    0,2,3 1,3,5    0,1,3 2,3,5 |
|     ------------------------------------------------------------------------|
|     T     T      - T     T      + T     T     , T     T      - T     T      |
|      2,3,4 1,2,5    1,2,4 2,3,5    1,2,3 2,4,5   1,3,4 1,2,5    1,2,4 1,3,5 |
|     ------------------------------------------------------------------------|
|     + T     T     , T     T      - T     T      + T     T      +            |
|        1,2,3 1,4,5   0,3,4 1,2,5    0,2,4 1,3,5    0,1,4 2,3,5              |
|     ------------------------------------------------------------------------|
|     T     T      - T     T      + T     T     , T     T      - T     T      |
|      0,2,3 1,4,5    0,1,3 2,4,5    0,1,2 3,4,5   2,3,4 0,2,5    0,2,4 2,3,5 |
|     ------------------------------------------------------------------------|
|     + T     T     , T     T      - T     T      + T     T      +            |
|        0,2,3 2,4,5   1,3,4 0,2,5    0,2,4 1,3,5    0,2,3 1,4,5              |
|     ------------------------------------------------------------------------|
|     T     T     , T     T      - T     T      + T     T     , T     T      -|
|      0,1,2 3,4,5   0,3,4 0,2,5    0,2,4 0,3,5    0,2,3 0,4,5   1,2,4 0,2,5  |
|     ------------------------------------------------------------------------|
|     T     T      + T     T     , T     T      - T     T      + T     T     ,|
|      0,2,4 1,2,5    0,1,2 2,4,5   1,2,3 0,2,5    0,2,3 1,2,5    0,1,2 2,3,5 |
|     ------------------------------------------------------------------------|
|     T     T      - T     T      + T     T      - T     T     , T     T      |
|      2,3,4 0,1,5    0,1,4 2,3,5    0,1,3 2,4,5    0,1,2 3,4,5   1,3,4 0,1,5 |
|     ------------------------------------------------------------------------|
|     - T     T      + T     T     , T     T      - T     T      +            |
|        0,1,4 1,3,5    0,1,3 1,4,5   0,3,4 0,1,5    0,1,4 0,3,5              |
|     ------------------------------------------------------------------------|
|     T     T     , T     T      - T     T      + T     T     , T     T      -|
|      0,1,3 0,4,5   1,2,4 0,1,5    0,1,4 1,2,5    0,1,2 1,4,5   0,2,4 0,1,5  |
|     ------------------------------------------------------------------------|
|     T     T      + T     T     , T     T      - T     T      + T     T     ,|
|      0,1,4 0,2,5    0,1,2 0,4,5   1,2,3 0,1,5    0,1,3 1,2,5    0,1,2 1,3,5 |
|     ------------------------------------------------------------------------|
|     T     T      - T     T      + T     T     , T     T      - T     T      |
|      0,2,3 0,1,5    0,1,3 0,2,5    0,1,2 0,3,5   1,2,4 0,3,4    0,2,4 1,3,4 |
|     ------------------------------------------------------------------------|
|     + T     T     , T     T      - T     T      + T     T     , T     T     |
|        0,1,4 2,3,4   1,2,3 0,3,4    0,2,3 1,3,4    0,1,3 2,3,4   1,2,3 0,2,4|
|     ------------------------------------------------------------------------|
|     - T     T      + T     T     , T     T      - T     T      +            |
|        0,2,3 1,2,4    0,1,2 2,3,4   1,2,3 0,1,4    0,1,3 1,2,4              |
|     ------------------------------------------------------------------------|
|     T     T     , T     T      - T     T      + T     T     )               |
|      0,1,2 1,3,4   0,2,3 0,1,4    0,1,3 0,2,4    0,1,2 0,3,4                |
|                                                                             |
|              ZZ                                                             |
|o2 : Ideal of --[T     ..T     , T     , T     , T     , T     , T     , T   |
|              31  0,1,2   0,1,3   0,2,3   1,2,3   0,1,4   0,2,4   1,2,4   0,3|
|-----------------------------------------------------------------------------|
|  , T     , T     , T     , T     , T     , T     , T     , T     , T     ,  |
|,4   1,3,4   2,3,4   0,1,5   0,2,5   1,2,5   0,3,5   1,3,5   2,3,5   0,4,5   |
|-----------------------------------------------------------------------------|
|T     , T     , T     ]                                                      |
| 1,4,5   2,4,5   3,4,5                                                       |
+-----------------------------------------------------------------------------+
The variables of the ring are based on the symbol provided, but assignments are
not made until the ring or the ideal is assigned to a global variable or is
submitted to use, as follows.
+-----------------------------------------------------------------------------+
|i3 : T_(0,2,3)                                                               |
|                                                                             |
|o3 = T                                                                       |
|      0,2,3                                                                  |
|                                                                             |
|o3 : IndexedVariable                                                         |
+-----------------------------------------------------------------------------+
|i4 : use ring J                                                              |
|                                                                             |
|     ZZ                                                                      |
|o4 = --[T     ..T     , T     , T     , T     , T     , T     , T     ,      |
|     31  0,1,2   0,1,3   0,2,3   1,2,3   0,1,4   0,2,4   1,2,4   0,3,4       |
|                                                                             |
|o4 : PolynomialRing                                                          |
|-----------------------------------------------------------------------------|
|T     , T     , T     , T     , T     , T     , T     , T     , T     ,      |
| 1,3,4   2,3,4   0,1,5   0,2,5   1,2,5   0,3,5   1,3,5   2,3,5   0,4,5       |
|-----------------------------------------------------------------------------|
|T     , T     , T     ]                                                      |
| 1,4,5   2,4,5   3,4,5                                                       |
+-----------------------------------------------------------------------------+
|i5 : T_(0,2,3)                                                               |
|                                                                             |
|o5 = T                                                                       |
|      0,2,3                                                                  |
|                                                                             |
|     ZZ                                                                      |
|o5 : --[T     ..T     , T     , T     , T     , T     , T     , T     ,      |
|     31  0,1,2   0,1,3   0,2,3   1,2,3   0,1,4   0,2,4   1,2,4   0,3,4       |
|-----------------------------------------------------------------------------|
|T     , T     , T     , T     , T     , T     , T     , T     , T     ,      |
| 1,3,4   2,3,4   0,1,5   0,2,5   1,2,5   0,3,5   1,3,5   2,3,5   0,4,5       |
|-----------------------------------------------------------------------------|
|T     , T     , T     ]                                                      |
| 1,4,5   2,4,5   3,4,5                                                       |
+-----------------------------------------------------------------------------+
In many ways, more natural than returning an ideal would be to return the
corresponding quotient ring or variety, but creating a quotient ring involves
computing a Gröbner basis, which might impose a heavy computational burden that
the user would prefer to avoid.

See also
========

  * Schubert -- find the Plücker
    ideal of a Schubert variety
  * pfaffians -- ideal generated by Pfaffians

Ways to use this method:
========================

  * Grassmannian(ZZ,ZZ) -- the Grassmannian
    of linear subspaces of a vector space
  * "Grassmannian(ZZ,ZZ,PolynomialRing)"

GroebnerBasis -- the class of all Gröbner bases
***********************************************

Description
===========

A Gröbner basis in Macaulay2 consists of a Gröbner basis computation, and
several associated matrices. Normally you don't need to refer to these objects
directly, as many operations on matrices and modules create them, and refer to
them.  For more information, see Gröbner bases.

Functions and methods returning a Gröbner basis:
================================================

  * forceGB -- declare that the columns of a matrix are a
    Gröbner basis
  * "forceGB(Matrix)" -- see forceGB, -- declare that the
    columns of a matrix are a Gröbner basis
  * gb -- compute a Gröbner basis
  * "gb(Ideal)" -- see gb, -- compute a Gröbner basis
  * "gb(Matrix)" -- see gb, -- compute a Gröbner basis
  * "gb(Module)" -- see gb, -- compute a Gröbner basis
  * "markedGB" -- see markedGB(Matrix,Matrix),
    -- make a marked Gröbner basis
  * markedGB(Matrix,Matrix) -- make a
    marked Gröbner basis

Methods that use a Gröbner basis:
=================================

  * "Number % GroebnerBasis" -- see %, -- a binary operator, usually
    used for remainder and reduction
  * "betti(GroebnerBasis)" -- see betti, -- display or modify a
    Betti diagram
  * generators(GroebnerBasis) -- the
    generator matrix of a Gröbner basis
  * "getChangeMatrix(GroebnerBasis)" -- see getChangeMatrix,
    -- get the change of basis matrix
  * GroebnerBasis == GroebnerBasis (missing documentation)
  * "leadTerm(GroebnerBasis)" -- see leadTerm(Matrix),
    -- get the greatest term of each column
  * Matrix % GroebnerBasis -- calculate the
    normal form of ring elements and matrices using a (partially computed)
    Gröbner basis
  * "RingElement % GroebnerBasis" -- see Matrix % GroebnerBasis,
    -- calculate the normal form of ring elements and matrices
    using a (partially computed) Gröbner basis
  * "Matrix // GroebnerBasis" -- see Matrix // Matrix,
    -- factor a map through another
  * "RingElement // GroebnerBasis" -- see Matrix // Matrix,
    -- factor a map through another
  * mingens(GroebnerBasis) -- (partially
    constructed) minimal generator matrix
  * quotient(Matrix,GroebnerBasis),
    -- matrix quotient
  * "quotientRemainder(Matrix,GroebnerBasis)" -- see quotientRemainder,
    -- matrix quotient and remainder
  * "remainder(Matrix,GroebnerBasis)" -- see remainder, --
    matrix remainder
  * "ring(GroebnerBasis)" -- see ring, -- get the associated ring
    of an object
  * "status(GroebnerBasis)" -- see status, -- status of a
    resolution computation
  * syz(GroebnerBasis) -- retrieve the syzygy
    matrix
  * target(GroebnerBasis) -- find target of a
    Gröbner basis

For the programmer
==================

The object GroebnerBasis, is a type, with
ancestor classes MutableHashTable, < HashTable
< Thing.

groebnerBasis -- Gröbner basis, as a matrix
*******************************************

Synopsis
========

  * Usage:
        M = groebnerBasis I
        M = groebnerBasis(I, Strategy=>"MGB")
        M = groebnerBasis(I, Strategy=>"F4")
  * Inputs:
      * I, an ideal, or a module or a matrix (in which case the
        result is the Groebner basis of the submodule generated by the columns)
      * MGBOptions, a list, For internal use only.  Warning: the
        interface is likely to change.
  * Optional inputs,:
      * Strategy => a string, default value null, If not given,
        use the default algorithm.  If given, value must be "MGB" or "F4", and
        the result is experimental
      * MGBOptions
  * Outputs:
      * M, a matrix, The matrix whose columns are the generators
        of the Groebner basis of I. In the non-local monomial order case, the
        result is auto-reduced, and sorted.

Description
===========

With no Strategy option, this just calls gb.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..d]                                                            |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : M = groebnerBasis random(R^1,R^{4:-2});                                 |
|                                                                             |
|             1      12                                                       |
|o2 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i3 : netList (ideal M)_*                                                     |
|                                                                             |
|     +-----------------------------------------------------------------------|
|     |                                   2                                   |
|o3 = |11299050a*c + 6906531b*c + 5601225c  + 22096970a*d + 10053225b*d - 1013|
|     +-----------------------------------------------------------------------|
|     |        2                      2                                       |
|     |9039240b  + 154881b*c + 789975c  + 2230550a*d + 2703015b*d + 532455c*d |
|     +-----------------------------------------------------------------------|
|     |                                   2                                   |
|     |45196200a*b - 2066697b*c - 3338775c  - 12617990a*d - 9788625b*d + 32683|
|     +-----------------------------------------------------------------------|
|     |         2                        2                                    |
|     |45196200a  - 6222819b*c - 4176525c  - 40248530a*d - 6956775b*d + 336305|
|     +-----------------------------------------------------------------------|
|     |                                   2                                   |
|     |3964358137052399637161262316798260c d + 5941680292864001985366442826132|
|     +-----------------------------------------------------------------------|
|     |                                                                       |
|     |792871627410479927432252463359652b*c*d + 907626632807183390740981849104|
|     +-----------------------------------------------------------------------|
|     |                                    3                                  |
|     |95144595289257591291870295603158240c  - 2841837152455056818005034904179|
|     +-----------------------------------------------------------------------|
|     |                                      2                                |
|     |19028919057851518258374059120631648b*c  + 64257621219904726957716712697|
|     +-----------------------------------------------------------------------|
|     |                                                                    3  |
|     |92377306833998610621043459166544878258614194423854521609030515753c*d  +|
|     +-----------------------------------------------------------------------|
|     |                                                                     3 |
|     |461886534169993053105217295832724391293070972119272608045152578765b*d  |
|     +-----------------------------------------------------------------------|
|     |                                                                     3 |
|     |153962178056664351035072431944241463764356990706424202681717526255a*d  |
|     +-----------------------------------------------------------------------|
|     | 5                                                                     |
|     |d                                                                      |
|     +-----------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|                 2                                                           |
|8695c*d - 803376d                                                            |
|-----------------------------------------------------------------------------|
|          2                                                                  |
|+ 1175328d                                                                   |
|-----------------------------------------------------------------------------|
|                 2                                                           |
|665c*d + 1493072d                                                            |
|-----------------------------------------------------------------------------|
|                2                                                            |
|55c*d + 7946624d                                                             |
|-----------------------------------------------------------------------------|
|     2                                        2                              |
|64a*d  + 1337598604362667816823185742844123b*d  + 424753421763943979030064359|
|-----------------------------------------------------------------------------|
|      2                                       2                              |
|360a*d  + 459506552743851049077630547055715b*d  - 482254086694892198398595134|
|-----------------------------------------------------------------------------|
|         2                                          2                        |
|920616a*d  - 976817993612564469525108588611526519b*d  + 258163850710445415446|
|-----------------------------------------------------------------------------|
|         2                                         2                         |
|169784a*d  + 33694597027785012215432150401502373b*d  - 6223892447912755734854|
|-----------------------------------------------------------------------------|
|                                                                  4          |
| 8498151665540849564229808863382997782054706833761464637212817128d           |
|-----------------------------------------------------------------------------|
|                                                                    4        |
|+ 90396066568414181641497131332966112726627833129769050446288485072d         |
|-----------------------------------------------------------------------------|
|                                                                    4        |
|- 17326088189814257165217320650455953486068430536610639471432672813d         |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-------------------------------------------------------------+               |
|                                                             |               |
|                                                             |               |
|-------------------------------------------------------------+               |
|                                                             |               |
|                                                             |               |
|-------------------------------------------------------------+               |
|                                                             |               |
|                                                             |               |
|-------------------------------------------------------------+               |
|                                                             |               |
|                                                             |               |
|-------------------------------------------------------------+               |
|          2                                     3            |               |
|1761688c*d  + 633197914362837742374002422591576d             |               |
|-------------------------------------------------------------+               |
|         2                                    3              |               |
|531980c*d  - 66868686610007296427523927539912d               |               |
|-------------------------------------------------------------+               |
|                   2                                        3|               |
|2789583156791212c*d  + 363076509596312359223810846059182696d |               |
|-------------------------------------------------------------+               |
|                2                                      3     |               |
|7050385679908c*d  - 7226409689483732200678023735720504d      |               |
|-------------------------------------------------------------+               |
|                                                             |               |
|                                                             |               |
|-------------------------------------------------------------+               |
|                                                             |               |
|                                                             |               |
|-------------------------------------------------------------+               |
|                                                             |               |
|                                                             |               |
|-------------------------------------------------------------+               |
|                                                             |               |
|                                                             |               |
|-------------------------------------------------------------+               |
+-----------------------------------------------------------------------------+

With a Strategy option, the code is experimental, subject to interface changes,
and might have bugs.  So use at your own risk!  However, it appears to work
correctly and is often very fast, in cases where it applies.  If you encounter
any bugs, please let us know!

If either "MGB" (MGB stands for mathicGB, the name of the package used), or
"F4" is given for the Strategy, then experimental code (written by Bjarke Roune
and M. Stillman) is used. The plan is for this to become the default version
for Groebner bases in later versions of Macaulay2.  But for now, it is
experimental.

These strategies only work for ideals in polynomial rings over a finite field
ZZ/p. In other cases, either an error will be given, or the current default
Groebner basis algorithm will be used.

+-----------------------------------------------------------------------------+
|i4 : R = ZZ/101[a..e]                                                        |
|                                                                             |
|o4 = R                                                                       |
|                                                                             |
|o4 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i5 : I = ideal sub(random(R^1, R^{4:-2}), e=>1);                             |
|                                                                             |
|o5 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i6 : netList I_*                                                             |
|                                                                             |
|     +-----------------------------------------------------------------------|
|     |     2              2                     2                            |
|o6 = |- 33a  - 19a*b - 39b  + 17a*c + 36b*c + 4c  - 20a*d + 9b*d + 13c*d + 22|
|     +-----------------------------------------------------------------------|
|     |    2              2                     2                            2|
|     |- 8a  + 43a*b - 22b  - 8a*c - 30b*c - 28c  + 36a*d + 41b*d - 6c*d - 9d |
|     +-----------------------------------------------------------------------|
|     |   2             2                      2                              |
|     |40a  + 3a*b - 41b  - 31a*c - 49b*c + 30c  + 25a*d - 13b*d - 47c*d - 40d|
|     +-----------------------------------------------------------------------|
|     |     2              2                      2                           |
|     |- 31a  - 39a*b - 48b  - 31a*c + 30b*c - 49c  - 48a*d - 37b*d + 28c*d + |
|     +-----------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-------------------------------+                                             |
| 2                             |                                             |
|d  + 44a - 39b - 26c - 49d - 11|                                             |
|-------------------------------+                                             |
|                               |                                             |
| - 3a + 16b + 35c - 35d + 6    |                                             |
|-------------------------------+                                             |
|2                              |                                             |
|  - 2a + 4b + 27c + 37d - 35   |                                             |
|-------------------------------+                                             |
|   2                           |                                             |
|46d  - 29a + 47b - 18c + d + 40|                                             |
|-------------------------------+                                             |
+-----------------------------------------------------------------------------+
|i7 : gbI = ideal groebnerBasis(I, Strategy=>"MGB");                          |
|                                                                             |
|o7 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i8 : netList gbI_*                                                           |
|                                                                             |
|     +-----------------------------------------------------------------------|
|     |                 2                             2                       |
|o8 = |a*c + 12b*c - 46c  + 43a*d + 33b*d - 26c*d - 3d  - 15a + 42b + 49c - 13|
|     +-----------------------------------------------------------------------|
|     | 2              2                              2                       |
|     |b  + 28b*c + 40c  + 28a*d - 11b*d + 35c*d - 13d  - 29a + 18b - 15c - 17|
|     +-----------------------------------------------------------------------|
|     |                 2                              2                      |
|     |a*b + 21b*c + 15c  + 26a*d + 42b*d + 46c*d - 34d  - 32a + 8b + 38c + 14|
|     +-----------------------------------------------------------------------|
|     | 2              2                           2                          |
|     |a  + 15b*c - 43c  - 10a*d - 22b*d + c*d - 4d  - 39a + 28c + 38d - 2    |
|     +-----------------------------------------------------------------------|
|     | 2         2        2        2      3              2                   |
|     |c d - 34a*d  + 37b*d  + 29c*d  + 42d  + 10b*c - 11c  + 17a*d + 9b*d + 3|
|     +-----------------------------------------------------------------------|
|     |             2       2        2      3              2                  |
|     |b*c*d - 22a*d  + 5b*d  + 42c*d  - 21d  - 43b*c - 36c  - 2a*d - 13b*d - |
|     +-----------------------------------------------------------------------|
|     | 3        2        2        2      3              2                    |
|     |c  - 31a*d  + 30b*d  - 22c*d  - 29d  + 12b*c + 34c  + 41a*d - b*d - 27c|
|     +-----------------------------------------------------------------------|
|     |   2        2       2        2    3              2                     |
|     |b*c  + 19a*d  + 2b*d  - 16c*d  - d  - 35b*c + 32c  - 19a*d - 33b*d - 24|
|     +-----------------------------------------------------------------------|
|     |   3      4        2        2     3              2                     |
|     |c*d  - 43d  - 33a*d  - 12b*d  + 7d  - 18b*c - 40c  - 16a*d - 5b*d - 5c*|
|     +-----------------------------------------------------------------------|
|     |   3      4        2       2        2      3            2              |
|     |b*d  - 32d  - 16a*d  + 3b*d  - 34c*d  - 33d  + b*c + 24c  + 39a*d - b*d|
|     +-----------------------------------------------------------------------|
|     |   3      4        2        2        2      3              2           |
|     |a*d  - 15d  + 10a*d  - 25b*d  - 43c*d  + 21d  - 15b*c + 46c  - 3a*d - b|
|     +-----------------------------------------------------------------------|
|     | 5      4        2        2        2      3              2             |
|     |d  + 34d  + 41a*d  - 21b*d  - 39c*d  + 10d  - 16b*c - 44c  - 13a*d + 47|
|     +-----------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|--------------------------------------------+                                |
|                                            |                                |
|                                            |                                |
|--------------------------------------------+                                |
|                                            |                                |
|d + 15                                      |                                |
|--------------------------------------------+                                |
|                                            |                                |
|d - 49                                      |                                |
|--------------------------------------------+                                |
|                                            |                                |
|                                            |                                |
|--------------------------------------------+                                |
|         2                                  |                                |
|2c*d + 8d  - 39a - 36b + 32c + 25d - 49     |                                |
|--------------------------------------------+                                |
|          2                                 |                                |
|3c*d + 25d  + 7a + 11b - 37c + 40d - 22     |                                |
|--------------------------------------------+                                |
|        2                                   |                                |
|*d + 33d  - 13a - 21b - 49c - 29d - 24      |                                |
|--------------------------------------------+                                |
|         2                                  |                                |
|c*d - 37d  + 47a - 33b - 31c - 28d - 12     |                                |
|--------------------------------------------+                                |
|       2                                    |                                |
|d + 30d  + 32a - 26b - 43c + 20d + 34       |                                |
|--------------------------------------------+                                |
|              2                             |                                |
| - 45c*d + 13d  - 49a + 18b - 3c + 2d + 34  |                                |
|--------------------------------------------+                                |
|              2                             |                                |
|*d - 5c*d - 8d  - 29a + 19b + 30c - 8d + 21 |                                |
|--------------------------------------------+                                |
|               2                            |                                |
|b*d + c*d + 44d  - 29a - 18b + 25c + 2d - 19|                                |
|--------------------------------------------+                                |
+-----------------------------------------------------------------------------+

Also implemented is a Faugere-like algorithm that is sometimes much faster (but
also sometimes takes a large amount of memory).

+-----------------------------------------------------------------------------+
|i9 : gbTrace=1                                                               |
|                                                                             |
|o9 = 1                                                                       |
+-----------------------------------------------------------------------------+
|i10 : gbI = ideal groebnerBasis(I, Strategy=>"F4");                          |
|-- computing mgb F4 OptionTable{"Log" =>             }                       |
|                                "Reducer" => F4                              |
|                                "SPairGroupSize" => 0                        |
|                                "Threads" => null                            |
|                                                                             |
|o10 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i11 : netList gbI_*                                                          |
|                                                                             |
|      +----------------------------------------------------------------------|
|      |                 2                             2                      |
|o11 = |a*c + 12b*c - 46c  + 43a*d + 33b*d - 26c*d - 3d  - 15a + 42b + 49c - 1|
|      +----------------------------------------------------------------------|
|      | 2              2                              2                      |
|      |b  + 28b*c + 40c  + 28a*d - 11b*d + 35c*d - 13d  - 29a + 18b - 15c - 1|
|      +----------------------------------------------------------------------|
|      |                 2                              2                     |
|      |a*b + 21b*c + 15c  + 26a*d + 42b*d + 46c*d - 34d  - 32a + 8b + 38c + 1|
|      +----------------------------------------------------------------------|
|      | 2              2                           2                         |
|      |a  + 15b*c - 43c  - 10a*d - 22b*d + c*d - 4d  - 39a + 28c + 38d - 2   |
|      +----------------------------------------------------------------------|
|      | 2         2        2        2      3              2                  |
|      |c d - 34a*d  + 37b*d  + 29c*d  + 42d  + 10b*c - 11c  + 17a*d + 9b*d + |
|      +----------------------------------------------------------------------|
|      |             2       2        2      3              2                 |
|      |b*c*d - 22a*d  + 5b*d  + 42c*d  - 21d  - 43b*c - 36c  - 2a*d - 13b*d -|
|      +----------------------------------------------------------------------|
|      | 3        2        2        2      3              2                   |
|      |c  - 31a*d  + 30b*d  - 22c*d  - 29d  + 12b*c + 34c  + 41a*d - b*d - 27|
|      +----------------------------------------------------------------------|
|      |   2        2       2        2    3              2                    |
|      |b*c  + 19a*d  + 2b*d  - 16c*d  - d  - 35b*c + 32c  - 19a*d - 33b*d - 2|
|      +----------------------------------------------------------------------|
|      |   3      4        2        2     3              2                    |
|      |c*d  - 43d  - 33a*d  - 12b*d  + 7d  - 18b*c - 40c  - 16a*d - 5b*d - 5c|
|      +----------------------------------------------------------------------|
|      |   3      4        2       2        2      3            2             |
|      |b*d  - 32d  - 16a*d  + 3b*d  - 34c*d  - 33d  + b*c + 24c  + 39a*d - b*|
|      +----------------------------------------------------------------------|
|      |   3      4        2        2        2      3              2          |
|      |a*d  - 15d  + 10a*d  - 25b*d  - 43c*d  + 21d  - 15b*c + 46c  - 3a*d - |
|      +----------------------------------------------------------------------|
|      | 5      4        2        2        2      3              2            |
|      |d  + 34d  + 41a*d  - 21b*d  - 39c*d  + 10d  - 16b*c - 44c  - 13a*d + 4|
|      +----------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|---------------------------------------------+                               |
|                                             |                               |
|3                                            |                               |
|---------------------------------------------+                               |
|                                             |                               |
|7d + 15                                      |                               |
|---------------------------------------------+                               |
|                                             |                               |
|4d - 49                                      |                               |
|---------------------------------------------+                               |
|                                             |                               |
|                                             |                               |
|---------------------------------------------+                               |
|          2                                  |                               |
|32c*d + 8d  - 39a - 36b + 32c + 25d - 49     |                               |
|---------------------------------------------+                               |
|           2                                 |                               |
| 3c*d + 25d  + 7a + 11b - 37c + 40d - 22     |                               |
|---------------------------------------------+                               |
|         2                                   |                               |
|c*d + 33d  - 13a - 21b - 49c - 29d - 24      |                               |
|---------------------------------------------+                               |
|          2                                  |                               |
|4c*d - 37d  + 47a - 33b - 31c - 28d - 12     |                               |
|---------------------------------------------+                               |
|        2                                    |                               |
|*d + 30d  + 32a - 26b - 43c + 20d + 34       |                               |
|---------------------------------------------+                               |
|               2                             |                               |
|d - 45c*d + 13d  - 49a + 18b - 3c + 2d + 34  |                               |
|---------------------------------------------+                               |
|               2                             |                               |
|b*d - 5c*d - 8d  - 29a + 19b + 30c - 8d + 21 |                               |
|---------------------------------------------+                               |
|                2                            |                               |
|7b*d + c*d + 44d  - 29a - 18b + 25c + 2d - 19|                               |
|---------------------------------------------+                               |
+-----------------------------------------------------------------------------+

Caveat
======

(1) The MGB and F4 options are experimental, work only over a finite field of
char $< 2^{32}$, not over quotient rings, and not over exterior or Weyl
algebras.  However, these versions can be much faster when they apply. (2) The
experimental versions do not stash their results into the ideal or module. (3)
The experimental version only works for ideals currently.

See also
========

  * gb -- compute a Gröbner basis

Ways to use groebnerBasis:
==========================

  * "groebnerBasis(Ideal)"
  * "groebnerBasis(Matrix)"
  * "groebnerBasis(Module)"

For the programmer
==================

The object groebnerBasis, is a method function with options.

GroebnerBasisOptions
********************

Description
===========

This class is used internally to record the options used with gb,
when the resulting Gröbner basis is cached inside a matrix.

For the programmer
==================

The object GroebnerBasisOptions, is a type,
with ancestor classes OptionTable, < HashTable
< Thing.

groupID -- the process group identifier
***************************************

Synopsis
========

  * Usage:
        groupID()
  * Outputs:
      * an integer, the process group identifier of the current
        Macaulay2 process

Description
===========

+--------------+
|i1 : groupID()|
|              |
|o1 = 2525120  |
+--------------+

See also
========

  * processID -- the process identifier
  * setGroupID -- set the process group identifier

For the programmer
==================

The object groupID, is a compiled function.

handleInterrupts
****************

Synopsis
========

  * Usage:
        handleInterrupts = b
  * Inputs:
      * b, a Boolean value,
  * Outputs:
      * a Boolean value, the value of b
  * Consequences:
      * If b is false, then the default operating system actions
        for the signals SIGINT, and SIGALRM are restored, and thus typing
        CTRL-C or the triggering of an alarm, will result in the
        Macaulay2 process terminating immediately. If b is true,
        then the default Macaulay2 signal handlers are installed, and thus
        control will be returned to top level after the code currently
        executing notices that the interrupt flag has been set.

Description
===========

The command line option --int has the same effect as handleInterrupts=false.

For the programmer
==================

The object handleInterrupts, is a Boolean value.

handling hypertext
******************

Output formatting routines:
  * html -- convert to HTML format
  * mathML -- convert to MathML format
  * tex -- convert to $\TeX$ format
  * info -- convert hypertext to info format
  * net -- format for printing, as a net

HardDegreeLimit -- compute only up to this degree
*************************************************

Description
===========

HardDegreeLimit -- keyword for an optional argument that specifies that
information above a specified degree is to be discarded.

Functions with optional argument named HardDegreeLimit:
=======================================================

  * "gb(...,HardDegreeLimit=>...)" -- see gb, -- compute a Gröbner
    basis
  * resolution(...,HardDegreeLimit=>...)
  * "syz(...,HardDegreeLimit=>...)" -- see syz(Matrix),
    -- compute the syzygy matrix

For the programmer
==================

The object HardDegreeLimit, is a symbol.

hash -- hash code of an object
******************************

Synopsis
========

  * Usage:
        hash x
  * Inputs:
      * x, a thing,
  * Outputs:
      * an integer, the hash code of x

Description
===========

The hash code of x is an integer produced in a deterministic way from x, and
perhaps from the hash codes of the contents of x. See hashing,
for a discussion of the requirements that the hash codes used here are designed
to satisfy.

Hash codes may change from one version of Macaulay2 to the next, but changes to
the hash codes of the basic types will be avoided, if possible.  That includes
lists, sequences, strings, hash tables, options, Boolean values, and numbers.

For the programmer
==================

The object hash, is a compiled function.

HeaderType -- a class of lists with abbreviated constructors
************************************************************

Description
===========

These are the types X of lists that can be constructed by expressions of the
form X {a,b,c,...}.  They also act on sequences.

+------------------------------------+
|i1 : X = new HeaderType of BasicList|
|                                    |
|o1 = X                              |
|                                    |
|o1 : HeaderType                     |
+------------------------------------+
|i2 : X {a,b,c}                      |
|                                    |
|o2 = X{a, b, c}                     |
|                                    |
|o2 : X                              |
+------------------------------------+

See also
========

  * WrapperType -- a class of lists with abbreviated
    constructors
  * SelfInitializingType -- the class of all self
    initializing types

Methods that use a header type:
===============================

  * "HeaderType List"
  * "HeaderType Sequence"

Protected objects of class HeaderType:
======================================

  * Adjacent -- the class of all adjacent expression pairs
  * BinaryOperation -- the class of all binary
    operation expressions
  * Divide -- the class of all divide expressions
  * Equation -- the class of all equation expressions
  * FunctionApplication -- the class of all
    function application expressions
  * MapExpression -- the class of map expressions
  * MatrixExpression -- the class of all matrix
    expressions
  * Power -- the class of all power expressions
  * RowExpression -- the class of all matrix expressions
  * SparseMonomialVectorExpression, --
    the class of all sparse monomial vector expressions
  * SparseVectorExpression -- the class of all
    sparse vector expressions
  * Subscript -- the class of all subscript expressions
  * Superscript -- the class of all superscript expressions
  * Table -- the class of all table expressions
  * VectorExpression -- the class of all vector
    expressions

For the programmer
==================

The object HeaderType, is a type, with ancestor
classes Type, < MutableHashTable <
HashTable < Thing.

headlines -- display a table of documentation headlines
*******************************************************

Synopsis
========

  * Usage:
        headlines about s
        headlines apropos p
        headlines methods f

Description
===========

This method displays a table of documentation headlines for the input list.

+-----------------------------------------------------------------------------+
|i1 : headlines about firstFunction                                           |
|                                                                             |
|o1 = 0.  "FirstPackage :: firstFunction"       -- a silly first function     |
|     1.  "FirstPackage :: firstFunction(ZZ)"   -- a silly first function     |
+-----------------------------------------------------------------------------+
|i2 : help 0                                                                  |
|                                                                             |
|o2 = FirstPackage::firstFunction -- a silly first function                   |
|     *****************************************************                   |
|                                                                             |
|     Synopsis                                                                |
|     ========                                                                |
|                                                                             |
|       * Usage:                                                              |
|             firstFunction n                                                 |
|       * Inputs:                                                             |
|           * n,                                                              |
|       * Outputs:                                                            |
|           * a silly string, depending on the value of n                     |
|                                                                             |
|     Here we show an example.                                                |
|                                                                             |
|     +------------------------+                                              |
|     |  i1 : firstFunction 1  |                                              |
|     |                        |                                              |
|     |  o1 = Hello World!     |                                              |
|     +------------------------+                                              |
|     |  i2 : firstFunction 0  |                                              |
|     |                        |                                              |
|     |  o2 = D'oh!            |                                              |
|     +------------------------+                                              |
+-----------------------------------------------------------------------------+
|i3 : headlines apropos "hilbert"                                             |
|                                                                             |
|o3 = 0.  "Polyhedra :: hilbertBasis"           --                            |
|     1.  "Macaulay2Doc :: hilbertFunction"     --                            |
|     2.  "Macaulay2Doc :: hilbertPolynomial"   --                            |
|     3.  "Macaulay2Doc :: hilbertSeries"       --                            |
|-----------------------------------------------------------------------------|
|computes the Hilbert basis of a Cone                                         |
|the Hilbert function                                                         |
|compute the Hilbert polynomial                                               |
|compute the Hilbert series                                                   |
+-----------------------------------------------------------------------------+
|i4 : headlines methods syz                                                   |
|                                                                             |
|o4 = 0.  "Macaulay2Doc :: syz(GroebnerBasis)"   -- retrieve the syzygy matrix|
|     1.  "Macaulay2Doc :: syz(Matrix)"          -- compute the syzygy matrix |
+-----------------------------------------------------------------------------+
|i5 : code 0                                                                  |
|                                                                             |
|o5 = -- code for method: syz(GroebnerBasis)                                  |
|     ../../../../../Macaulay2/m2/gb.m2:203:45-203:106: --source code:        |
|     syz              GroebnerBasis  := Matrix => o -> G -> map(ring G,      |
|-----------------------------------------------------------------------------|
|rawsort rawGBSyzygies G.RawComputation)                                      |
+-----------------------------------------------------------------------------+

See also
========

  * help -- view documentation nodes
  * viewHelp -- view online documentation in a web browser
  * about -- search the documentation
  * apropos -- symbols matching a pattern
  * methods -- list methods
  * code -- display source code

Ways to use headlines:
======================

  * headlines(List) (missing documentation)

For the programmer
==================

The object headlines, is a method function.

height(File) -- get window height
*********************************

Synopsis
========

  * Function: height,
  * Usage:
        height f
  * Inputs:
      * f
  * Outputs:
      * an integer, the height of the window or terminal attached to
        the file f, if any, else 0

Ways to use this method:
========================

  * height(File) -- get window height

HH -- general homology and cohomology functor
*********************************************

Description
===========

HH is a ScriptedFunctor, which serves as an interface to
the methods for homology, and cohomology, in
the sense that, HH_i(M) is an abbreviation for homology(i,M) HH^i(M) is an
abbreviation for cohomology(i,M), and HH(M) is an abbreviation for
homology(,M). A second argument and optional arguments may be added.

Ways to use HH:
===============

  * HH ChainComplex -- homology of a chain complex
  * HH ChainComplexMap -- homology of a chain
    complex map
  * HH^ZZ ChainComplex -- cohomology of a chain
    complex
  * HH^ZZ ChainComplexMap -- cohomology of a
    chain complex map
  * HH^ZZ Module -- local cohomology of a module
  * HH^ZZ SheafMap (missing documentation)
  * HH^ZZ SheafOfRings (Varieties) -- cohomology of a
    sheaf of rings on a projective variety
  * HH^ZZ SumOfTwists (Varieties) -- coherent sheaf
    cohomology module
  * HH^ZZ(AffineVariety,CoherentSheaf) (missing documentation)
  * "HH^ZZ CoherentSheaf" -- see HH^ZZ(ProjectiveVariety,CoherentSheaf) (Varieties),
    -- cohomology of a
    coherent sheaf on a projective variety
  * HH^ZZ(ProjectiveVariety,CoherentSheaf) (Varieties)
    -- cohomology of a
    coherent sheaf on a projective variety
  * HH^ZZ(ProjectiveVariety,SheafMap) (missing documentation)
  * HH^ZZ(ProjectiveVariety,SumOfTwists) (missing documentation)
  * HH^ZZ(Variety,SheafOfRings) (missing documentation)
  * HH_ZZ ChainComplex -- homology of a chain
    complex
  * HH_ZZ ChainComplexMap -- homology of a
    chain complex map
  * HH_ZZ Sequence (missing documentation)
  * homology(Matrix,Matrix) -- homology
    of a pair of maps
  * homology(SheafMap,SheafMap) (missing documentation)

For the programmer
==================

The object HH, is a scripted functor.

HH ChainComplex -- homology of a chain complex
**********************************************

Synopsis
========

  * Function: homology,
  * Usage:
        HH C
  * Inputs:
      * C
  * Outputs:
      * the homology of C

Description
===========

+---------------------------------------------+
|i1 : R = QQ[x]/x^5;                          |
+---------------------------------------------+
|i2 : C = res coker vars R                    |
|                                             |
|      1      1      1                        |
|o2 = R  <-- R  <-- R                         |
|                                             |
|     0      1      2                         |
|                                             |
|o2 : ChainComplex                            |
+---------------------------------------------+
|i3 : M = HH C                                |
|                                             |
|o3 = 0 : cokernel | x |                      |
|                                             |
|     1 : subquotient ({1} | x4 |, {1} | x4 |)|
|                                             |
|     2 : image {5} | x |                     |
|                                             |
|o3 : GradedModule                            |
+---------------------------------------------+
|i4 : prune M                                 |
|                                             |
|o4 = 0 : cokernel | x |                      |
|                                             |
|     1 : 0                                   |
|                                             |
|     2 : cokernel {6} | x4 |                 |
|                                             |
|o4 : GradedModule                            |
+---------------------------------------------+

Ways to use this method:
========================

  * HH ChainComplex -- homology of a chain complex

HH ChainComplexMap -- homology of a chain complex map
*****************************************************

Synopsis
========

  * Function: homology,
  * Usage:
        HH f
  * Inputs:
      * i
  * Outputs:
      * the map on the homology induced by the map f of chain complexes

Ways to use this method:
========================

  * HH ChainComplexMap -- homology of a chain
    complex map

HH^ZZ ChainComplex -- cohomology of a chain complex
***************************************************

Synopsis
========

  * Function: cohomology,
  * Usage:
        HH^i C
  * Inputs:
      * i, an integer,
      * C, a chain complex,
  * Optional inputs,:
      * Degree (SimplicialComplexes),
        => ..., default value 0,
  * Outputs:
      * a module, HH^i C -- homology at the i-th spot of the
        chain complex C.

Description
===========

By definition, this is the same as computing HH_(-i) C.

+---------------------------------------------------------+
|i1 : R = ZZ/101[x,y]                                     |
|                                                         |
|o1 = R                                                   |
|                                                         |
|o1 : PolynomialRing                                      |
+---------------------------------------------------------+
|i2 : C = chainComplex(matrix{{x,y}},matrix{{x*y},{-x^2}})|
|                                                         |
|      1      2      1                                    |
|o2 = R  <-- R  <-- R                                     |
|                                                         |
|     0      1      2                                     |
|                                                         |
|o2 : ChainComplex                                        |
+---------------------------------------------------------+
|i3 : M = HH^1 C                                          |
|                                                         |
|o3 = 0                                                   |
|                                                         |
|o3 : R-module                                            |
+---------------------------------------------------------+
|i4 : prune M                                             |
|                                                         |
|o4 = 0                                                   |
|                                                         |
|o4 : R-module                                            |
+---------------------------------------------------------+

Here is another example computing simplicial cohomology (for a hollow
tetrahedron):
+----------------------------------------------------+
|i5 : needsPackage "SimplicialComplexes"             |
|                                                    |
|o5 = SimplicialComplexes                            |
|                                                    |
|o5 : Package                                        |
+----------------------------------------------------+
|i6 : R = QQ[a..d]                                   |
|                                                    |
|o6 = R                                              |
|                                                    |
|o6 : PolynomialRing                                 |
+----------------------------------------------------+
|i7 : D = simplicialComplex {a*b*c,a*b*d,a*c*d,b*c*d}|
|                                                    |
|o7 = simplicialComplex | bcd acd abd abc |          |
|                                                    |
|o7 : SimplicialComplex                              |
+----------------------------------------------------+
|i8 : C = complex D                                  |
|                                                    |
|       1       4       6       4                    |
|o8 = QQ  <-- QQ  <-- QQ  <-- QQ                     |
|                                                    |
|     -1      0       1       2                      |
|                                                    |
|o8 : Complex                                        |
+----------------------------------------------------+
|i9 : HH_2 C                                         |
|                                                    |
|o9 = image | -1 |                                   |
|           | 1  |                                   |
|           | -1 |                                   |
|           | 1  |                                   |
|                                                    |
|                               4                    |
|o9 : QQ-module, submodule of QQ                     |
+----------------------------------------------------+
|i10 : prune oo                                      |
|                                                    |
|        1                                           |
|o10 = QQ                                            |
|                                                    |
|o10 : QQ-module, free                               |
+----------------------------------------------------+

See also
========

  * GradedModule -- the class of all graded modules
  * HH -- general homology and cohomology functor

Ways to use this method:
========================

  * HH^ZZ ChainComplex -- cohomology of a chain
    complex

HH^ZZ ChainComplexMap -- cohomology of a chain complex map
**********************************************************

Synopsis
========

  * Function: cohomology,
  * Usage:
        HH^i f
  * Inputs:
      * i
      * f
  * Optional inputs,:
      * Degree (SimplicialComplexes),
        => ..., default value 0,
  * Outputs:
      * a matrix, the i-th cohomology map induced by the chain
        complex map f

Description
===========

The command provides the map on the i-th cohomology module induced by a map f
of chain complexes.

See also
========

  * cohomology -- general cohomology functor
  * HH -- general homology and cohomology functor
  * ChainComplex -- the class of all chain complexes

Ways to use this method:
========================

  * HH^ZZ ChainComplexMap -- cohomology of a
    chain complex map

HH^ZZ Module -- local cohomology of a module
********************************************

Synopsis
========

  * Function: cohomology,
  * Usage:
        HH^i(M)
  * Inputs:
      * i,  which is non negative
      * M,  which is graded over its base polynomial ring
  * Optional inputs,:
      * Degree (SimplicialComplexes),
        => ..., default value 0,
  * Outputs:
      * a module,

Description
===========

The command computes the local cohomology of the graded module M with respect
to the maximal irrelevant ideal (the ideal of variables in the base ring of M).

The package Dmodules, has alternative code to compute
local cohomology (even in the non homogeneous case)

A very simple example:
+-----------------------------+
|i1 : R = QQ[a,b];            |
+-----------------------------+
|i2 : HH^2 (R^{-3})           |
|                             |
|o2 = cokernel | b a  0 |     |
|              | 0 -b a |     |
|                             |
|                            2|
|o2 : R-module, quotient of R |
+-----------------------------+
|i3 : HH^2 (R^{-4})           |
|                             |
|o3 = cokernel | b a  0  0 |  |
|              | 0 -b a  0 |  |
|              | 0 0  -b a |  |
|                             |
|                            3|
|o3 : R-module, quotient of R |
+-----------------------------+

Another example, a singular surface in projective fourspace (with one apparent
double point):
+-----------------------------------------------------------------------------+
|i4 : R = ZZ/101[x_0..x_4];                                                   |
+-----------------------------------------------------------------------------+
|i5 : I = ideal(x_1*x_4-x_2*x_3, x_1^2*x_3+x_1*x_2*x_0-x_2^2*x_0, x_3^3+x_3*x_|
|                                                                             |
|                                       2    2     3               2          |
|o5 = ideal (- x x  + x x , x x x  - x x  + x x , x  + x x x  - x x )         |
|               2 3    1 4   0 1 2    0 2    1 3   3    0 3 4    0 4          |
|                                                                             |
|o5 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|4*x_0-x_4^2*x_0)                                                             |
+-----------------------------------------------------------------------------+
|i6 : M = R^1/module(I)                                                       |
|                                                                             |
|o6 = cokernel | -x_2x_3+x_1x_4 x_0x_1x_2-x_0x_2^2+x_1^2x_3                   |
|                                                                             |
|                            1                                                |
|o6 : R-module, quotient of R                                                 |
|-----------------------------------------------------------------------------|
|x_3^3+x_0x_3x_4-x_0x_4^2 |                                                   |
+-----------------------------------------------------------------------------+
|i7 : HH^1(M)                                                                 |
|                                                                             |
|o7 = cokernel | x_4 x_3 x_2 x_1 x_0^3 |                                      |
|                                                                             |
|                            1                                                |
|o7 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i8 : HH^2(M)                                                                 |
|                                                                             |
|o8 = cokernel | x_4 x_3 x_2 x_1 x_0 |                                        |
|                                                                             |
|                            1                                                |
|o8 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+

Caveat
======

There is no check made if the given module is graded over the base polynomial
ring

See also
========

  * Dmodules -- D-modules package collection
  * HH^ZZ SumOfTwists (Varieties) -- coherent sheaf
    cohomology module
  * HH^ZZ CoherentSheaf (Varieties)
    -- cohomology of a
    coherent sheaf on a projective variety

Ways to use this method:
========================

  * HH^ZZ Module -- local cohomology of a module

HH_ZZ ChainComplex -- homology of a chain complex
*************************************************

Synopsis
========

  * Function: homology,
  * Usage:
        HH_i C
  * Inputs:
      * i
      * C
  * Outputs:
      * the homology at the i-th spot of the chain complex C.

Description
===========

+---------------------------------------------------------+
|i1 : R = ZZ/101[x,y]                                     |
|                                                         |
|o1 = R                                                   |
|                                                         |
|o1 : PolynomialRing                                      |
+---------------------------------------------------------+
|i2 : C = chainComplex(matrix{{x,y}},matrix{{x*y},{-x^2}})|
|                                                         |
|      1      2      1                                    |
|o2 = R  <-- R  <-- R                                     |
|                                                         |
|     0      1      2                                     |
|                                                         |
|o2 : ChainComplex                                        |
+---------------------------------------------------------+
|i3 : M = HH_1 C                                          |
|                                                         |
|o3 = subquotient ({1} | -y |, {1} | xy  |)               |
|                  {1} | x  |  {1} | -x2 |                |
|                                                         |
|                               2                         |
|o3 : R-module, subquotient of R                          |
+---------------------------------------------------------+
|i4 : prune M                                             |
|                                                         |
|o4 = cokernel {2} | x |                                  |
|                                                         |
|                            1                            |
|o4 : R-module, quotient of R                             |
+---------------------------------------------------------+

Ways to use this method:
========================

  * HH_ZZ ChainComplex -- homology of a chain
    complex

HH_ZZ ChainComplexMap -- homology of a chain complex map
********************************************************

Synopsis
========

  * Function: homology,
  * Usage:
        HH_i f
  * Inputs:
      * i
      * f
  * Outputs:
      * the map on the i-th homology module induced by the map f of chain
        complexes

Ways to use this method:
========================

  * HH_ZZ ChainComplexMap -- homology of a
    chain complex map

hilbertFunction -- the Hilbert function
***************************************

Synopsis
========

  * Usage:
        hilbertFunction(d,X)
  * Inputs:
      * d, an integer, or a list, of integers;
        specifying a degree (or multidegree)
      * M, a ring, an ideal, or a module,
  * Outputs:
      * an integer, the dimension of the degree d part of M.  For an
        ideal, the corresponding quotient ring is used.

Description
===========

In the following example, compare the rank of the source of the basis map to
the number provided by hilbertFunction.

+---------------------------------------------+
|i1 : R = QQ[x,y,z, Degrees=>{3:{1,1}}];      |
+---------------------------------------------+
|i2 : hilbertFunction({3,3}, R)               |
|                                             |
|o2 = 10                                      |
+---------------------------------------------+
|i3 : basis({3,3},R)                          |
|                                             |
|o3 = | x3 x2y x2z xy2 xyz xz2 y3 y2z yz2 z3 ||
|                                             |
|             1      10                       |
|o3 : Matrix R  <-- R                         |
+---------------------------------------------+

The standard meaning of subscripts on functions permits a simpler syntax to be
used.

+----------------------------+
|i4 : hilbertFunction_{3,3} R|
|                            |
|o4 = 10                     |
+----------------------------+

Here is a singly graded example.

+----------------------------+
|i5 : R = QQ[x,y,z];         |
+----------------------------+
|i6 : hilbertFunction({3}, R)|
|                            |
|o6 = 10                     |
+----------------------------+
|i7 : hilbertFunction(3, R)  |
|                            |
|o7 = 10                     |
+----------------------------+

Here is an example with a module.

+---------------------------------------+
|i8 : R = QQ[a..d, Degrees=>{4:{1,1}}]; |
+---------------------------------------+
|i9 : M = coker matrix {{a,c,d},{c,b,d}}|
|                                       |
|o9 = cokernel | a c d |                |
|              | c b d |                |
|                                       |
|                            2          |
|o9 : R-module, quotient of R           |
+---------------------------------------+
|i10 : hilbertFunction({2,2}, M)        |
|                                       |
|o10 = 8                                |
+---------------------------------------+
|i11 : B = basis({2,2},M)               |
|                                       |
|o11 = | b2 bc c2 cd d2 0  0  0  |      |
|      | 0  0  0  0  0  a2 ac c2 |      |
|                                       |
|                    8                  |
|o11 : Matrix M <-- R                   |
+---------------------------------------+
|i12 : numgens source B                 |
|                                       |
|o12 = 8                                |
+---------------------------------------+

Here is an example with an ideal.

+---------------------------------------------------------------+
|i13 : R = QQ[a..f, Degrees=>{6:{1,1}}];                        |
+---------------------------------------------------------------+
|i14 : I = ideal (a*b, c*d, e*f);                               |
|                                                               |
|o14 : Ideal of R                                               |
+---------------------------------------------------------------+
|i15 : hilbertFunction({2,2}, I)                                |
|                                                               |
|o15 = 18                                                       |
+---------------------------------------------------------------+
|i16 : S = R/I;                                                 |
+---------------------------------------------------------------+
|i17 : basis({2,2},S)                                           |
|                                                               |
|o17 = | a2 ac ad ae af b2 bc bd be bf c2 ce cf d2 de df e2 f2 ||
|                                                               |
|              1      18                                        |
|o17 : Matrix S  <-- S                                          |
+---------------------------------------------------------------+

If d is not given, then a function is returned that will accept different
values of d.

+-----------------------------------------+
|i18 : R = QQ[a..d];                      |
+-----------------------------------------+
|i19 : I = monomialCurveIdeal(R, {1,2,3});|
|                                         |
|o19 : Ideal of R                         |
+-----------------------------------------+
|i20 : h = hilbertFunction I              |
|                                         |
|o20 = h                                  |
|                                         |
|o20 : FunctionClosure                    |
+-----------------------------------------+
|i21 : h 1                                |
|                                         |
|o21 = 4                                  |
+-----------------------------------------+
|i22 : h 2                                |
|                                         |
|o22 = 7                                  |
+-----------------------------------------+

Caveat
======

It can be much faster to compute a basis for the desired degree, because
hilbertFunction works by expanding the Hilbert series to a sufficiently high
order, thus, in effect, computing many values of the Hilbert function
simultaneously.  If several values of the Hilbert function are desired, it is
best to compute the ones of higher degree first, so the expansion will be done
to sufficiently high order at the first attempt, and thus be done just once.

See also
========

  * degreesRing -- the ring or monoid of degrees
  * reduceHilbert -- reduce a Hilbert series expression
  * poincare -- assemble degrees of a ring, module, or ideal
    into a polynomial
  * poincareN -- assemble degrees into polynomial
  * hilbertSeries -- compute the Hilbert series
  * hilbertPolynomial -- compute the Hilbert
    polynomial
  * numgens -- the number of generators
  * Function _ Thing -- attach the first argument to
    a function of two or more arguments

Ways to use hilbertFunction:
============================

  * "hilbertFunction(Ideal)"
  * "hilbertFunction(List,Ideal)"
  * "hilbertFunction(List,Module)"
  * "hilbertFunction(List,Ring)"
  * "hilbertFunction(Module)"
  * "hilbertFunction(Ring)"
  * "hilbertFunction(ZZ,Ideal)"
  * "hilbertFunction(ZZ,Module)"
  * "hilbertFunction(ZZ,Ring)"

For the programmer
==================

The object hilbertFunction, is a method function.

hilbertPolynomial -- compute the Hilbert polynomial
***************************************************

Description
===========

In a singly graded ambient ring, the Hilbert function,
eventually is a polynomial called the Hilbert polynomial. By default this
polynomial is written in terms of the Hilbert polynomials of projective spaces
because it is a good form for extracting geometric information from the
polynomial. The Hilbert polynomial of P^i is z |--> binomial(z + i, i).

See also
========

  * degreesRing -- the ring or monoid of degrees
  * reduceHilbert -- reduce a Hilbert series expression
  * poincare -- assemble degrees of a ring, module, or ideal
    into a polynomial
  * poincareN -- assemble degrees into polynomial
  * hilbertSeries -- compute the Hilbert series
  * hilbertFunction -- the Hilbert function

Ways to use hilbertPolynomial:
==============================

  * "hilbertPolynomial(ZZ,BettiTally)" -- see BettiTally, --
    the class of all Betti tallies
  * hilbertPolynomial(CoherentSheaf) (Varieties)
    -- compute the Hilbert
    polynomial of the coherent sheaf
  * hilbertPolynomial(Ideal) -- compute
    the Hilbert polynomial of the quotient of the ambient ring by the ideal
  * hilbertPolynomial(Module) -- compute
    the Hilbert polynomial of the module
  * hilbertPolynomial(ProjectiveVariety) (Varieties)
    -- compute the Hilbert
    polynomial of the projective variety
  * hilbertPolynomial(Ring) -- compute the
    Hilbert polynomial of the ring

For the programmer
==================

The object hilbertPolynomial, is a method function with options.

hilbertPolynomial(...,Projective=>...) -- choose how to display the Hilbert polynomial
**************************************************************************************

Synopsis
========

  * Usage:
        hilbertPolynomial(...,Projective => b
  * Inputs:
      * b, a Boolean value, either true or false

Description
===========

Projective => true is an option to hilbertPolynomial,
which specifies that the Hilbert polynomial produced should be expressed in
terms of the Hilbert polynomials of projective spaces. This is the default.

Projective => false is an option to hilbertPolynomial,
which specifies that the Hilbert polynomial produced should be expressed as a
polynomial in the variable i.

We compute the Hilbert polynomial, of a coordinate
ring of the  rational quartic curve in P^3.
+-----------------------------------------------------+
|i1 : R = ZZ/101[a..d];                               |
+-----------------------------------------------------+
|i2 : S = coimage map(R, R, {a^4, a^3*b, a*b^3, b^4});|
+-----------------------------------------------------+
|i3 : hilbertPolynomial S                             |
|                                                     |
|o3 = - 3*P  + 4*P                                    |
|          0      1                                   |
|                                                     |
|o3 : ProjectiveHilbertPolynomial                     |
+-----------------------------------------------------+
|i4 : hilbertPolynomial(S, Projective=>false)         |
|                                                     |
|o4 = 4i + 1                                          |
|                                                     |
|o4 : QQ[i]                                           |
+-----------------------------------------------------+
When the option Projective is false, the variable i is a local variable. The
command use ringwill make iinto a global variable.

Further information
===================

  * Default value: true,
  * Function: hilbertPolynomial, -- compute the
    Hilbert polynomial
  * Option key: Projective, -- whether to produce a
    projective Hilbert polynomial

See also
========

  * ProjectiveHilbertPolynomial -- the
    class of all Hilbert polynomials

Functions with optional argument named Projective:
==================================================

  * hilbertPolynomial(...,Projective=>...)
    -- choose how to
    display the Hilbert polynomial

hilbertPolynomial(Ideal) -- compute the Hilbert polynomial of the quotient of the ambient ring by the ideal
***********************************************************************************************************

Synopsis
========

  * Function: hilbertPolynomial,
  * Usage:
        hilbertPolynomial I
  * Inputs:
      * I, an ideal,
  * Optional inputs,:
      * Projective,
        => ..., default value true, choose how to display the Hilbert
        polynomial
  * Outputs:
      * a projective Hilbert polynomial,
        unless the option Projective is false

Description
===========

We compute the Hilbert polynomial, of the quotient of
the ambient ring by an ideal.
+--------------------------------------------+
|i1 : R = QQ[a..d];                          |
+--------------------------------------------+
|i2 : I = monomialCurveIdeal(R, {1,3,4});    |
|                                            |
|o2 : Ideal of R                             |
+--------------------------------------------+
|i3 : h = hilbertPolynomial I                |
|                                            |
|o3 = - 3*P  + 4*P                           |
|          0      1                          |
|                                            |
|o3 : ProjectiveHilbertPolynomial            |
+--------------------------------------------+
|i4 : hilbertPolynomial (R/I)                |
|                                            |
|o4 = - 3*P  + 4*P                           |
|          0      1                          |
|                                            |
|o4 : ProjectiveHilbertPolynomial            |
+--------------------------------------------+
|i5 : hilbertPolynomial(I, Projective=>false)|
|                                            |
|o5 = 4i + 1                                 |
|                                            |
|o5 : QQ[i]                                  |
+--------------------------------------------+

These Hilbert polynomials can serve as Hilbert functions,
too since the values of the Hilbert polynomial eventually are
the same as the Hilbert function.
+------------------------------------------+
|i6 : apply(10, k-> h(k))                  |
|                                          |
|o6 = {1, 5, 9, 13, 17, 21, 25, 29, 33, 37}|
|                                          |
|o6 : List                                 |
+------------------------------------------+
|i7 : apply(10, k-> hilbertFunction(k,I))  |
|                                          |
|o7 = {1, 4, 9, 13, 17, 21, 25, 29, 33, 37}|
|                                          |
|o7 : List                                 |
+------------------------------------------+

Caveat
======

As is often the case, calling this function on an ideal I actually computes it
for R/I where R is the ring of I.

Ways to use this method:
========================

  * hilbertPolynomial(Ideal) -- compute
    the Hilbert polynomial of the quotient of the ambient ring by the ideal

hilbertPolynomial(Module) -- compute the Hilbert polynomial of the module
*************************************************************************

Synopsis
========

  * Function: hilbertPolynomial,
  * Usage:
        hilbertPolynomial M
  * Inputs:
      * M, a module,
  * Optional inputs,:
      * Projective,
        => ..., default value true, choose how to display the Hilbert
        polynomial
  * Outputs:
      * a projective Hilbert polynomial,
        unless the option Projective is false

Description
===========

We compute the Hilbert polynomial, of a module.
+-----------------------------------------------+
|i1 : R = QQ[a..d];                             |
+-----------------------------------------------+
|i2 : M = module monomialCurveIdeal(R, {1,3,4});|
+-----------------------------------------------+
|i3 : h = hilbertPolynomial M                   |
|                                               |
|o3 = 3*P  - 4*P  + P                           |
|        0      1    3                          |
|                                               |
|o3 : ProjectiveHilbertPolynomial               |
+-----------------------------------------------+
|i4 : hilbertPolynomial(M, Projective=>false)   |
|                                               |
|     1 3    2   13                             |
|o4 = -i  + i  - --i                            |
|     6           6                             |
|                                               |
|o4 : QQ[i]                                     |
+-----------------------------------------------+

Ways to use this method:
========================

  * hilbertPolynomial(Module) -- compute
    the Hilbert polynomial of the module

hilbertPolynomial(Ring) -- compute the Hilbert polynomial of the ring
*********************************************************************

Synopsis
========

  * Function: hilbertPolynomial,
  * Usage:
        hilbertPolynomial R
  * Inputs:
      * R, a ring,
  * Optional inputs,:
      * Projective,
        => ..., default value true, choose how to display the Hilbert
        polynomial
  * Outputs:
      * a projective Hilbert polynomial,
        unless the option Projective is false

Description
===========

We compute the Hilbert polynomial, of a coordinate
ring of the rational quartic curve in P^3.
+-----------------------------------------------------+
|i1 : R = ZZ/101[a..d];                               |
+-----------------------------------------------------+
|i2 : S = coimage map(R, R, {a^4, a^3*b, a*b^3, b^4});|
+-----------------------------------------------------+
|i3 : presentation S                                  |
|                                                     |
|o3 = | bc-ad c3-bd2 ac2-b2d b3-a2c |                 |
|                                                     |
|             1      4                                |
|o3 : Matrix R  <-- R                                 |
+-----------------------------------------------------+
|i4 : h =  hilbertPolynomial S                        |
|                                                     |
|o4 = - 3*P  + 4*P                                    |
|          0      1                                   |
|                                                     |
|o4 : ProjectiveHilbertPolynomial                     |
+-----------------------------------------------------+
|i5 : hilbertPolynomial(S, Projective=>false)         |
|                                                     |
|o5 = 4i + 1                                          |
|                                                     |
|o5 : QQ[i]                                           |
+-----------------------------------------------------+
The rational quartic curve in P^3 is therefore 'like' 4 copies of P^1, with
three points missing.  One can see this by noticing that there is a deformation
of the rational quartic to the union of 4 lines, or 'sticks', which intersect
in three successive points.

These Hilbert polynomials can serve as Hilbert functions,
too since the values of the Hilbert polynomial eventually are
the same as the Hilbert function.
+---------------------------------------+
|i6 : apply(5, k-> h(k))                |
|                                       |
|o6 = {1, 5, 9, 13, 17}                 |
|                                       |
|o6 : List                              |
+---------------------------------------+
|i7 : apply(5, k-> hilbertFunction(k,S))|
|                                       |
|o7 = {1, 4, 9, 13, 17}                 |
|                                       |
|o7 : List                              |
+---------------------------------------+

Ways to use this method:
========================

  * hilbertPolynomial(Ring) -- compute the
    Hilbert polynomial of the ring

hilbertSeries -- compute the Hilbert series
*******************************************

Description
===========

The Hilbert series is the formal power series in the variables of the degrees
ring whose coefficients are the dimensions of the corresponding graded
component.Note that the series is provided as a type of expression called a
Divide.

See also
========

  * degreesRing -- the ring or monoid of degrees
  * reduceHilbert -- reduce a Hilbert series expression
  * poincare -- assemble degrees of a ring, module, or ideal
    into a polynomial
  * poincareN -- assemble degrees into polynomial
  * hilbertPolynomial -- compute the Hilbert
    polynomial
  * hilbertFunction -- the Hilbert function

Ways to use hilbertSeries:
==========================

  * "hilbertSeries(ZZ,BettiTally)" -- see BettiTally, -- the
    class of all Betti tallies
  * hilbertSeries(Ideal) -- compute the
    Hilbert series of the quotient of the ambient ring by the ideal
  * hilbertSeries(Module) -- compute the
    Hilbert series of the module
  * hilbertSeries(PolynomialRing), --
    compute the Hilbert series of a ring
  * "hilbertSeries(QuotientRing)" -- see hilbertSeries(PolynomialRing),
    -- compute the Hilbert series of a ring
  * hilbertSeries(ProjectiveHilbertPolynomial)
    -- compute the Hilbert
    series of a projective Hilbert polynomial

For the programmer
==================

The object hilbertSeries, is a method function with options.

hilbertSeries(...,Order=>...) -- display the truncated power series expansion
*****************************************************************************

Synopsis
========

  * Usage:
        hilbertSeries(..., Order => n)
  * Inputs:
      * n, an integer,
  * Consequences:
      * The output is no longer of type Divide. It is a
        polynomial in the degrees ring.

Description
===========

We compute the Hilbert series both without and with the optional argument. In
the second case notice the terms of power series expansion up to, but not
including, degree 5 are displayed rather than expressing the series as a
rational function. The polynomial expression is an element of a Laurent
polynomial ring that is the degrees ring, of the ambient
ring.
+------------------------------------+
|i1 : R = ZZ/101[x,y];               |
+------------------------------------+
|i2 : hilbertSeries(R/x^3)           |
|                                    |
|           3                        |
|      1 - T                         |
|o2 = --------                       |
|            2                       |
|     (1 - T)                        |
|                                    |
|o2 : Expression of class Divide     |
+------------------------------------+
|i3 : hilbertSeries(R/x^3, Order =>5)|
|                                    |
|                2     3     4       |
|o3 = 1 + 2T + 3T  + 3T  + 3T        |
|                                    |
|o3 : ZZ[T]                          |
+------------------------------------+
If the ambient ring is multigraded, then the degrees ring,
has multiple variables.
+------------------------------------------------+
|i4 : R = ZZ/101[x,y, Degrees=>{{1,2},{2,3}}];   |
+------------------------------------------------+
|i5 : hilbertSeries(R/x^3, Order =>5)            |
|                                                |
|            2    2 4    2 3    3 5    4 7    4 6|
|o5 = 1 + T T  + T T  + T T  + T T  + T T  + T T |
|          0 1    0 1    0 1    0 1    0 1    0 1|
|                                                |
|o5 : ZZ[T ..T ]                                 |
|         0   1                                  |
+------------------------------------------------+
The heft vector provides a suitable monomial ordering and degrees in the ring
of the Hilbert series.
+-----------------------------------------------------------------------------+
|i6 : R = QQ[a..d,Degrees=>{{-2,-1},{-1,0},{0,1},{1,2}}]                      |
|                                                                             |
|o6 = R                                                                       |
|                                                                             |
|o6 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i7 : hilbertSeries(R, Order =>3)                                             |
|                                                                             |
|            2         -1    -2 -1    2 4      3     2     -1       -2        |
|o7 = 1 + T T  + T  + T   + T  T   + T T  + T T  + 2T  + 2T  T  + 2T   +      |
|          0 1    1    0     0  1     0 1    0 1     1     0  1     0         |
|     ------------------------------------------------------------------------|
|      -3 -1    -4 -2                                                         |
|     T  T   + T  T                                                           |
|      0  1     0  1                                                          |
|                                                                             |
|o7 : ZZ[T ..T ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i8 : degrees ring oo                                                         |
|                                                                             |
|o8 = {{-1}, {1}}                                                             |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : heft R                                                                  |
|                                                                             |
|o9 = {-1, 1}                                                                 |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+

Further information
===================

  * Default value: infinity,
  * Function: hilbertSeries, -- compute the Hilbert series
  * Option key: Order, -- specify the order of a Hilbert series
    required

Functions with optional argument named Order:
=============================================

  * hilbertSeries(...,Order=>...)
    -- display the truncated
    power series expansion

hilbertSeries(...,Reduce=>...) -- reduce the Hilbert series
***********************************************************

Synopsis
========

  * Usage:
        hilbertSeries(..., Reduce => true)
  * Consequences:
      * the resulting rational function is reduced by cancelling factors of the
        numerator that occur explicitly as factors of the denominator. See also
        reduceHilbert.

Description
===========

+-----------------------------------------------+
|i1 : R = QQ[x,y,z];                            |
+-----------------------------------------------+
|i2 : hilbertSeries ideal (x,y)                 |
|                                               |
|               2                               |
|     1 - 2T + T                                |
|o2 = -----------                               |
|              3                                |
|       (1 - T)                                 |
|                                               |
|o2 : Expression of class Divide                |
+-----------------------------------------------+
|i3 : hilbertSeries(ideal (x,y), Reduce => true)|
|                                               |
|        1                                      |
|o3 = -------                                   |
|     (1 - T)                                   |
|                                               |
|o3 : Expression of class Divide                |
+-----------------------------------------------+

Further information
===================

  * Default value: false,
  * Function: hilbertSeries, -- compute the Hilbert series
  * Option key: Reduce, -- an optional argument

Functions with optional argument named Reduce:
==============================================

  * hilbertSeries(...,Reduce=>...)
    -- reduce the Hilbert
    series

hilbertSeries(Ideal) -- compute the Hilbert series of the quotient of the ambient ring by the ideal
***************************************************************************************************

Synopsis
========

  * Function: hilbertSeries,
  * Usage:
        hilbertSeries I
  * Inputs:
      * I, an ideal,
  * Optional inputs,:
      * Order, => ...,
        default value infinity, display the truncated power series expansion
      * Reduce, => ...,
        default value false, reduce the Hilbert series
  * Outputs:
      * a divide expression, the Hilbert series

Description
===========

We compute the Hilbert series, of R/I, the quotient of the
ambient ring by the ideal. Caution: For an ideal I running hilbertSeries I
calculates the Hilbert series of R/I.
+-----------------------------------+
|i1 : R = ZZ/101[x, Degrees => {2}];|
+-----------------------------------+
|i2 : I = ideal x^2                 |
|                                   |
|            2                      |
|o2 = ideal x                       |
|                                   |
|o2 : Ideal of R                    |
+-----------------------------------+
|i3 : s = hilbertSeries I           |
|                                   |
|           4                       |
|      1 - T                        |
|o3 = --------                      |
|           2                       |
|     (1 - T )                      |
|                                   |
|o3 : Expression of class Divide    |
+-----------------------------------+
|i4 : numerator s                   |
|                                   |
|          4                        |
|o4 = 1 - T                         |
|                                   |
|o4 : ZZ[T]                         |
+-----------------------------------+
|i5 : poincare I                    |
|                                   |
|          4                        |
|o5 = 1 - T                         |
|                                   |
|o5 : ZZ[T]                         |
+-----------------------------------+
|i6 : reduceHilbert s               |
|                                   |
|          2                        |
|     1 + T                         |
|o6 = ------                        |
|        1                          |
|                                   |
|o6 : Expression of class Divide    |
+-----------------------------------+
Recall that the variables of the power series are the variables of the
degrees ring.
+-------------------------------------+
|i7 : R=ZZ/101[x, Degrees => {{1,1}}];|
+-------------------------------------+
|i8 : I = ideal x^2;                  |
|                                     |
|o8 : Ideal of R                      |
+-------------------------------------+
|i9 : s = hilbertSeries I             |
|                                     |
|           2 2                       |
|      1 - T T                        |
|           0 1                       |
|o9 = ----------                      |
|     (1 - T T )                      |
|           0 1                       |
|                                     |
|o9 : Expression of class Divide      |
+-------------------------------------+
|i10 : numerator s                    |
|                                     |
|           2 2                       |
|o10 = 1 - T T                        |
|           0 1                       |
|                                     |
|o10 : ZZ[T ..T ]                     |
|          0   1                      |
+-------------------------------------+
|i11 : poincare I                     |
|                                     |
|           2 2                       |
|o11 = 1 - T T                        |
|           0 1                       |
|                                     |
|o11 : ZZ[T ..T ]                     |
|          0   1                      |
+-------------------------------------+
|i12 : reduceHilbert s                |
|                                     |
|      1 + T T                        |
|           0 1                       |
|o12 = --------                       |
|          1                          |
|                                     |
|o12 : Expression of class Divide     |
+-------------------------------------+

Caveat
======

As is often the case, calling this function on an ideal I actually computes it
for R/I where R is the ring of I.

Ways to use this method:
========================

  * hilbertSeries(Ideal) -- compute the
    Hilbert series of the quotient of the ambient ring by the ideal

hilbertSeries(PolynomialRing) -- compute the Hilbert series of a ring
*********************************************************************

Synopsis
========

  * Function: hilbertSeries,
  * Usage:
        hilbertSeries R
  * Inputs:
      * R
  * Optional inputs,:
      * Order, => ...,
        default value infinity, display the truncated power series expansion
      * Reduce, => ...,
        default value false, reduce the Hilbert series
  * Outputs:
      * a divide expression, the Hilbert series

Description
===========

We compute the Hilbert series, of a ring.
+----------------------------------------------+
|i1 : R = ZZ/101[x, Degrees => {2}]/ideal(x^2);|
+----------------------------------------------+
|i2 : s = hilbertSeries R                      |
|                                              |
|           4                                  |
|      1 - T                                   |
|o2 = --------                                 |
|           2                                  |
|     (1 - T )                                 |
|                                              |
|o2 : Expression of class Divide               |
+----------------------------------------------+
|i3 : numerator s                              |
|                                              |
|          4                                   |
|o3 = 1 - T                                    |
|                                              |
|o3 : ZZ[T]                                    |
+----------------------------------------------+
|i4 : poincare R                               |
|                                              |
|          4                                   |
|o4 = 1 - T                                    |
|                                              |
|o4 : ZZ[T]                                    |
+----------------------------------------------+
Recall that the variables of the power series are the variables of the
degrees ring.
+------------------------------------------------+
|i5 : R=ZZ/101[x, Degrees => {{1,1}}]/ideal(x^2);|
+------------------------------------------------+
|i6 : s = hilbertSeries R                        |
|                                                |
|           2 2                                  |
|      1 - T T                                   |
|           0 1                                  |
|o6 = ----------                                 |
|     (1 - T T )                                 |
|           0 1                                  |
|                                                |
|o6 : Expression of class Divide                 |
+------------------------------------------------+
|i7 : numerator s                                |
|                                                |
|          2 2                                   |
|o7 = 1 - T T                                    |
|          0 1                                   |
|                                                |
|o7 : ZZ[T ..T ]                                 |
|         0   1                                  |
+------------------------------------------------+
|i8 : poincare R                                 |
|                                                |
|          2 2                                   |
|o8 = 1 - T T                                    |
|          0 1                                   |
|                                                |
|o8 : ZZ[T ..T ]                                 |
|         0   1                                  |
+------------------------------------------------+

Ways to use this method:
========================

  * hilbertSeries(PolynomialRing), --
    compute the Hilbert series of a ring
  * "hilbertSeries(QuotientRing)"

hilbertSeries(ProjectiveHilbertPolynomial) -- compute the Hilbert series of a projective Hilbert polynomial
***********************************************************************************************************

Synopsis
========

  * Function: hilbertSeries,
  * Usage:
        hilbertSeries P
  * Inputs:
      * P, a projective Hilbert polynomial,
  * Optional inputs,:
      * Order, => ...,
        default value infinity, display the truncated power series expansion
      * Reduce, => ...,
        default value false, reduce the Hilbert series
  * Outputs:
      * a divide expression, the Hilbert series

Description
===========

We compute the Hilbert series, of a projective Hilbert
polynomial.
+--------------------------------------+
|i1 : P = projectiveHilbertPolynomial 3|
|                                      |
|o1 = P                                |
|      3                               |
|                                      |
|o1 : ProjectiveHilbertPolynomial      |
+--------------------------------------+
|i2 : s = hilbertSeries P              |
|                                      |
|         1                            |
|o2 = --------                         |
|            4                         |
|     (1 - T)                          |
|                                      |
|o2 : Expression of class Divide       |
+--------------------------------------+
|i3 : numerator s                      |
|                                      |
|o3 = 1                                |
|                                      |
|o3 : ZZ[T]                            |
+--------------------------------------+
Computing the Hilbert series, of a projective variety can
be useful for finding the h-vector of a simplicial complex from its f-vector.
For example, consider the octahedron. The ideal below is its Stanley-Reisner
ideal. We can see its f-vector (1, 6, 12, 8) in the Hilbert polynomial, and
then we get the h-vector (1,3,3,1) from the coefficients of the Hilbert series
projective Hilbert polynomial.
+--------------------------------+
|i4 : R = QQ[a..h];              |
+--------------------------------+
|i5 : I = ideal (a*b, c*d, e*f); |
|                                |
|o5 : Ideal of R                 |
+--------------------------------+
|i6 : P=hilbertPolynomial(I)     |
|                                |
|o6 = - P  + 6*P  - 12*P  + 8*P  |
|        1      2       3      4 |
|                                |
|o6 : ProjectiveHilbertPolynomial|
+--------------------------------+
|i7 : s = hilbertSeries P        |
|                                |
|                2    3          |
|     1 + 3T + 3T  + T           |
|o7 = -----------------          |
|                 5              |
|          (1 - T)               |
|                                |
|o7 : Expression of class Divide |
+--------------------------------+
|i8 : numerator s                |
|                                |
|                2    3          |
|o8 = 1 + 3T + 3T  + T           |
|                                |
|o8 : ZZ[T]                      |
+--------------------------------+

Ways to use this method:
========================

  * hilbertSeries(ProjectiveHilbertPolynomial)
    -- compute the Hilbert
    series of a projective Hilbert polynomial

hold -- hold something in a holder expression
*********************************************

Synopsis
========

  * Usage:
        hold x
  * Inputs:
      * x
  * Outputs:
      * an expression,  of class Holder,
        containing x as its single element, unless x is already an expression,
        in which case x is returned.

Description
===========

+--------------------------------+
|i1 : (hold 2)^5 * (hold 3)^3    |
|                                |
|      5 3                       |
|o1 = 2 3                        |
|                                |
|o1 : Expression of class Product|
+--------------------------------+

For the programmer
==================

The object hold, is a method function with a single argument.

Holder -- the class of all holder expressions
*********************************************

Description
===========

This type of expression is a container for a single, arbitrary, thing that is
basic enough that the correct method for printing does not depend on its
neighbors in the containing expression.  A negative number would not be basic
enough for this purpose, since as a member of a sum, it would require special
treatment.

Types of holder:
================

  * Describe -- the class of the output of describe
  * OneExpression -- the class all one expressions
  * Parenthesize
  * ZeroExpression -- the class of all zero expressions

For the programmer
==================

The object Holder, is a wrapper type, with
ancestor classes Expression, < BasicList <
Thing.

Hom -- module of homomorphisms
******************************

Synopsis
========

  * Usage:
        Hom(M, N)
  * Inputs:
      * M, a ring, an ideal, or a module,
      * N, a ring, an ideal, or a module,
  * Optional inputs,:
      * DegreeLimit => an integer, or a list, default
        value null, if set, stop after homomorphisms in this degree have been
        computed
      * MinimalGenerators => a Boolean value, default value
        true, whether to trim, the resulting module
      * Strategy => a thing, default value null
  * Outputs:
      * a module, isomorphic to $\mathrm{Hom}_R(M,N), where $M$
        and $N$ are both $R$-modules

Description
===========

If $M$ or $N$ is an ideal or ring, it is regarded as a module in the evident
way.

+---------------------------------------------+
|i1 : R = QQ[x,y]/(y^2 - x^3);                |
+---------------------------------------------+
|i2 : M = image matrix{{x, y}}                |
|                                             |
|o2 = image | x y |                           |
|                                             |
|                             1               |
|o2 : R-module, submodule of R                |
+---------------------------------------------+
|i3 : H = Hom(M, M, MinimalGenerators => true)|
|                                             |
|o3 = image {-1} | x y  |                     |
|           {-1} | y x2 |                     |
|                                             |
|                             2               |
|o3 : R-module, submodule of R                |
+---------------------------------------------+

To recover the modules used to create a Hom-module, use the function
formation.

+------------------------------------------------------------+
|i4 : formation H                                            |
|                                                            |
|o4 = Hom (image | x y |, image | x y |, DegreeLimit => null)|
|                                                            |
|o4 : Expression of class FunctionApplication                |
+------------------------------------------------------------+

Specific homomorphisms may be obtained using homomorphism,
as follows.

+----------------------------+
|i5 : f0 = homomorphism H_{0}|
|                            |
|o5 = {1} | 1 0 |            |
|     {1} | 0 1 |            |
|                            |
|o5 : Matrix M <-- M         |
+----------------------------+
|i6 : f1 = homomorphism H_{1}|
|                            |
|o6 = {1} | 0 x |            |
|     {1} | 1 0 |            |
|                            |
|o6 : Matrix M <-- M         |
+----------------------------+

In the example above, f0 is the identity map, and f1 maps $x$ to $y$ and $y$ to
$x^2$.

+--------------------+
|i7 : M_0, M_1       |
|                    |
|o7 = (| x |, | y |) |
|                    |
|o7 : Sequence       |
+--------------------+
|i8 : f0 M_0, f0 M_1 |
|                    |
|o8 = (| x |, | y |) |
|                    |
|o8 : Sequence       |
+--------------------+
|i9 : f1 M_0, f1 M_1 |
|                    |
|o9 = (| y |, | x2 |)|
|                    |
|o9 : Sequence       |
+--------------------+

Contributors
============

Devlin Mallory implemented the strategy which accepts a degree limit.

See also
========

  * Ext -- compute an Ext module
  * formation -- recover the methods used to make a module

Ways to use Hom:
================

  * "Hom(Ideal,Ideal)"
  * "Hom(Ideal,Module)"
  * "Hom(Ideal,Ring)"
  * "Hom(Module,Ideal)"
  * "Hom(Module,Module)"
  * "Hom(Module,Ring)"
  * "Hom(Ring,Ideal)"
  * "Hom(Ring,Module)"
  * "Hom(Ring,Ring)"
  * Hom(CoherentSheaf,CoherentSheaf) (Varieties)
    -- global Hom
  * "Hom(CoherentSheaf,SheafOfRings)" -- see
    Hom(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Hom
  * "Hom(SheafOfRings,CoherentSheaf)" -- see
    Hom(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Hom
  * "Hom(SheafOfRings,SheafOfRings)" -- see
    Hom(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Hom
  * "Hom(ChainComplex,Module)" -- see Hom(Module,ChainComplex),
    -- the Hom functor
  * "Hom(ChainComplexMap,Module)" -- see Hom(Module,ChainComplex),
    -- the Hom functor
  * Hom(Module,ChainComplex) -- the Hom
    functor
  * "Hom(Module,ChainComplexMap)" -- see Hom(Module,ChainComplex),
    -- the Hom functor
  * "Hom(Matrix,Matrix)" -- see Hom(Module,Matrix),
    -- induced map on Hom
  * "Hom(Matrix,Module)" -- see Hom(Module,Matrix),
    -- induced map on Hom
  * Hom(Module,Matrix) -- induced map on Hom

For the programmer
==================

The object Hom, is a method function with options.

adjoint -- the tensor-Hom adjunction maps
*****************************************

Description
===========

Recall that tensor(Module,Module), and
Hom(Module,Module), form an adjoint pair, meaning that there is a natural
isomorphism $$ \mathrm{Hom}(F\otimes G,H) \cong
\mathrm{Hom}(F,\mathrm{Hom}(G,H)). $$

Synopsis
========

  * Usage:
        adjoint(f, F, G)
  * Inputs:
      * f, a matrix, a homomorphism $F \otimes G \to H$
      * F, a module, a free module;
      * G, a module, a free module;
  * Outputs:
      * a matrix, the adjoint homomorphism $F \to
        \mathrm{Hom}(G,H)$
+----------------------------------------------------------------+
|i1 : R = QQ[x_1 .. x_24];                                       |
+----------------------------------------------------------------+
|i2 : f = genericMatrix(R, 2, 4*3)                               |
|                                                                |
|o2 = | x_1 x_3 x_5 x_7 x_9  x_11 x_13 x_15 x_17 x_19 x_21 x_23 ||
|     | x_2 x_4 x_6 x_8 x_10 x_12 x_14 x_16 x_18 x_20 x_22 x_24 ||
|                                                                |
|             2      12                                          |
|o2 : Matrix R  <-- R                                            |
+----------------------------------------------------------------+
|i3 : isHomogeneous f                                            |
|                                                                |
|o3 = true                                                       |
+----------------------------------------------------------------+
|i4 : g = adjoint(f, R^4, R^3)                                   |
|                                                                |
|o4 = | x_1 x_7  x_13 x_19 |                                     |
|     | x_2 x_8  x_14 x_20 |                                     |
|     | x_3 x_9  x_15 x_21 |                                     |
|     | x_4 x_10 x_16 x_22 |                                     |
|     | x_5 x_11 x_17 x_23 |                                     |
|     | x_6 x_12 x_18 x_24 |                                     |
|                                                                |
|             6      4                                           |
|o4 : Matrix R  <-- R                                            |
+----------------------------------------------------------------+

If f is homogeneous, and source f === F ** G (including the grading), then the
resulting matrix will be homogeneous.

+-----------------------------------------+
|i5 : g = adjoint(f, R^4, R^{-1,-1,-1})   |
|                                         |
|o5 = {-1} | x_1 x_7  x_13 x_19 |         |
|     {-1} | x_2 x_8  x_14 x_20 |         |
|     {-1} | x_3 x_9  x_15 x_21 |         |
|     {-1} | x_4 x_10 x_16 x_22 |         |
|     {-1} | x_5 x_11 x_17 x_23 |         |
|     {-1} | x_6 x_12 x_18 x_24 |         |
|                                         |
|             6      4                    |
|o5 : Matrix R  <-- R                     |
+-----------------------------------------+
|i6 : isHomogeneous g                     |
|                                         |
|o6 = true                                |
+-----------------------------------------+
|i7 : f === adjoint'(g, R^{-1,-1,-1}, R^2)|
|                                         |
|o7 = true                                |
+-----------------------------------------+

Synopsis
========

  * Usage:
        adjoint'(g, G, H)
  * Inputs:
      * g, a matrix, a homomorphism $F \to \mathrm{Hom}(G,H)$
        between modules
      * G, a module, a free module;
      * H, a module, a free module;
  * Outputs:
      * a matrix, the adjoint homomorphism $F \otimes G \to H$

If g is homogeneous, and target g === Hom(G,H) (including the grading), then
the resulting matrix will be homogeneous.

+--------------------------------------+
|i8 : R = QQ[x_1 .. x_12];             |
+--------------------------------------+
|i9 : g = genericMatrix(R, 6, 2)       |
|                                      |
|o9 = | x_1 x_7  |                     |
|     | x_2 x_8  |                     |
|     | x_3 x_9  |                     |
|     | x_4 x_10 |                     |
|     | x_5 x_11 |                     |
|     | x_6 x_12 |                     |
|                                      |
|             6      2                 |
|o9 : Matrix R  <-- R                  |
+--------------------------------------+
|i10 : f = adjoint'(g, R^2, R^3)       |
|                                      |
|o10 = | x_1 x_4 x_7 x_10 |            |
|      | x_2 x_5 x_8 x_11 |            |
|      | x_3 x_6 x_9 x_12 |            |
|                                      |
|              3      4                |
|o10 : Matrix R  <-- R                 |
+--------------------------------------+
|i11 : isHomogeneous f                 |
|                                      |
|o11 = true                            |
+--------------------------------------+
|i12 : g === adjoint(f, R^{-1,-1}, R^2)|
|                                      |
|o12 = true                            |
+--------------------------------------+

See also
========

  * dual -- dual module or map
  * flip -- isomorphism map of commutativity of tensor product
  * compose -- composition as a pairing on Hom-modules
  * reshape -- reshape a matrix
  * Hom(Module,Module) -- module of homomorphisms
  * tensor(Module,Module) -- tensor product
    of modules

Ways to use adjoint:
====================

  * "adjoint(Matrix,Module,Module)"

For the programmer
==================

The object adjoint, is a method function with options.

compose -- composition as a pairing on Hom-modules
**************************************************

Synopsis
========

  * Usage:
        compose(M, N, P)
  * Inputs:
      * M, a module,
      * N, a module,
      * P, a module,
  * Outputs:
      * a matrix, the composition map of homomorphism modules
        $\mathrm{Hom}(M,N)$ and $\mathrm{Hom}(N,P)$

Description
===========

In the following example we check that the map does implement the composition
map $$ \mathrm{Hom}(M,N) \otimes \mathrm{Hom}(N,P) \to \mathrm{Hom}(M,P). $$

+------------------------------+
|i1 : R = QQ[x,y]              |
|                              |
|o1 = R                        |
|                              |
|o1 : PolynomialRing           |
+------------------------------+
|i2 : M = image vars R ++ R^2  |
|                              |
|o2 = image | x y 0 0 |        |
|           | 0 0 1 0 |        |
|           | 0 0 0 1 |        |
|                              |
|                             3|
|o2 : R-module, submodule of R |
+------------------------------+
|i3 : f = compose(M,M,M);      |
|                              |
|o3 : Matrix                   |
+------------------------------+
|i4 : H = Hom(M,M);            |
+------------------------------+
|i5 : g = H_{0}                |
|                              |
|o5 = {0} | 1 |                |
|     {0} | 0 |                |
|     {0} | 0 |                |
|     {0} | 0 |                |
|     {0} | 0 |                |
|     {0} | 0 |                |
|     {0} | 0 |                |
|     {1} | 0 |                |
|     {1} | 0 |                |
|     {1} | 0 |                |
|     {1} | 0 |                |
|                              |
|                   1          |
|o5 : Matrix H <-- R           |
+------------------------------+
|i6 : h = homomorphism g       |
|                              |
|o6 = {1} | 1 0 0 0 |          |
|     {1} | 0 1 0 0 |          |
|     {0} | 0 0 0 0 |          |
|     {0} | 0 0 0 0 |          |
|                              |
|o6 : Matrix M <-- M           |
+------------------------------+
|i7 : f * (g ** g)             |
|                              |
|o7 = {0} | 1 |                |
|     {0} | 0 |                |
|     {0} | 0 |                |
|     {0} | 0 |                |
|     {0} | 0 |                |
|     {0} | 0 |                |
|     {0} | 0 |                |
|     {1} | 0 |                |
|     {1} | 0 |                |
|     {1} | 0 |                |
|     {1} | 0 |                |
|                              |
|                   1          |
|o7 : Matrix H <-- R           |
+------------------------------+
|i8 : h' = homomorphism oo     |
|                              |
|o8 = {1} | 1 0 0 0 |          |
|     {1} | 0 1 0 0 |          |
|     {0} | 0 0 0 0 |          |
|     {0} | 0 0 0 0 |          |
|                              |
|o8 : Matrix M <-- M           |
+------------------------------+
|i9 : h' === h * h             |
|                              |
|o9 = true                     |
+------------------------------+
|i10 : assert oo               |
+------------------------------+

The modules should be defined over the same ring.

See also
========

  * Hom -- module of homomorphisms
  * homomorphism -- get the homomorphism from element of
    Hom
  * homomorphism' -- get the element of Hom from a
    homomorphism
  * adjoint -- the tensor-Hom adjunction maps
  * flip -- isomorphism map of commutativity of tensor product

Ways to use compose:
====================

  * "compose(Module,Module,Module)"

For the programmer
==================

The object compose, is a method function with options.

homomorphism -- get the homomorphism from element of Hom
********************************************************

Synopsis
========

  * Usage:
        homomorphism f
  * Inputs:
      * f, a vector, or a matrix, corresponding to
        an element in $\mathrm{Hom}(M,N)$ or a map $R^1 \to \mathrm{Hom}(M,N)$
  * Outputs:
      * a matrix, the map $M \to N$, corresponding to the
        element $f \in \mathrm{Hom}(M,N)$

Description
===========

When H = Hom(M,N) is computed, information about computing the morphisms
corresponding to its elements is stored in H.

+--------------------------------------------------+
|i1 : R = QQ[x,y,z, Degrees => {2,3,1}]/(y^2 - x^3)|
|                                                  |
|o1 = R                                            |
|                                                  |
|o1 : QuotientRing                                 |
+--------------------------------------------------+
|i2 : H = Hom(ideal(x,y), R^1)                     |
|                                                  |
|o2 = image {-2} | x y  |                          |
|           {-3} | y x2 |                          |
|                                                  |
|                             2                    |
|o2 : R-module, submodule of R                     |
+--------------------------------------------------+
|i3 : f = H_{1}                                    |
|                                                  |
|o3 = {0} | 0 |                                    |
|     {1} | 1 |                                    |
|                                                  |
|                   1                              |
|o3 : Matrix H <-- R                               |
+--------------------------------------------------+
|i4 : g = homomorphism f                           |
|                                                  |
|o4 = | y x2 |                                     |
|                                                  |
|o4 : Matrix                                       |
+--------------------------------------------------+

The source and target are what they should be.

+-----------------------------------+
|i5 : source g === module ideal(x,y)|
|                                   |
|o5 = true                          |
+-----------------------------------+
|i6 : target g === R^1              |
|                                   |
|o6 = true                          |
+-----------------------------------+

Except for a possible redistribution of degrees between the map and modules, we
can undo the process with homomorphism'.

+------------------------------------------------+
|i7 : f' = homomorphism' g                       |
|                                                |
|o7 = {0} | 0 |                                  |
|     {1} | 1 |                                  |
|                                                |
|                   1                            |
|o7 : Matrix H <-- R                             |
+------------------------------------------------+
|i8 : f === f'                                   |
|                                                |
|o8 = false                                      |
+------------------------------------------------+
|i9 : f - f'                                     |
|                                                |
|o9 = 0                                          |
|                                                |
|                   1                            |
|o9 : Matrix H <-- R                             |
+------------------------------------------------+
|i10 : degree f, degree f'                       |
|                                                |
|o10 = ({0}, {1})                                |
|                                                |
|o10 : Sequence                                  |
+------------------------------------------------+
|i11 : degrees f, degrees f'                     |
|                                                |
|o11 = ({{{0}, {1}}, {{1}}}, {{{0}, {1}}, {{0}}})|
|                                                |
|o11 : Sequence                                  |
+------------------------------------------------+

After pruning, a Hom module, one cannot
use homomorphism directly. Instead, first apply the pruning map:

+------------------------------------------------+
|i12 : H1 = prune H                              |
|                                                |
|o12 = cokernel {0} | y  x2 |                    |
|               {1} | -x -y |                    |
|                                                |
|                             2                  |
|o12 : R-module, quotient of R                   |
+------------------------------------------------+
|i13 : homomorphism(H1.cache.pruningMap * H1_{1})|
|                                                |
|o13 = | y x2 |                                  |
|                                                |
|o13 : Matrix                                    |
+------------------------------------------------+

See also
========

  * Hom -- module of homomorphisms
  * homomorphism' -- get the element of Hom from a
    homomorphism

Ways to use homomorphism:
=========================

  * "homomorphism(Matrix)"
  * "homomorphism(Vector)"

For the programmer
==================

The object homomorphism, is a method function.

homomorphism' -- get the element of Hom from a homomorphism
***********************************************************

Synopsis
========

  * Usage:
        homomorphism' f
  * Inputs:
      * f, a matrix, of the form $M \to N$
  * Optional inputs,:
      * DegreeLimit => an integer, or a list, default
        value null, see Hom(...,DegreeLimit=>...),
      * MinimalGenerators => a Boolean value, default value
        true, see Hom(...,MinimalGenerators=>...),
      * Strategy => a thing, default value null, see
        Hom(...,Strategy=>...),
  * Outputs:
      * a matrix, the map $R^1 \to \mathrm{Hom}(M,N)$,
        corresponding to the map $f \in \mathrm{Hom}(M,N)$

Description
===========

+-----------------------------------------+
|i1 : R = QQ[x,y,z]                       |
|                                         |
|o1 = R                                   |
|                                         |
|o1 : PolynomialRing                      |
+-----------------------------------------+
|i2 : f = vars R ++ vars R                |
|                                         |
|o2 = | x y z 0 0 0 |                     |
|     | 0 0 0 x y z |                     |
|                                         |
|             2      6                    |
|o2 : Matrix R  <-- R                     |
+-----------------------------------------+
|i3 : g = homomorphism' f                 |
|                                         |
|o3 = {-1} | x |                          |
|     {-1} | 0 |                          |
|     {-1} | y |                          |
|     {-1} | 0 |                          |
|     {-1} | z |                          |
|     {-1} | 0 |                          |
|     {-1} | 0 |                          |
|     {-1} | x |                          |
|     {-1} | 0 |                          |
|     {-1} | y |                          |
|     {-1} | 0 |                          |
|     {-1} | z |                          |
|                                         |
|             12      1                   |
|o3 : Matrix R   <-- R                    |
+-----------------------------------------+
|i4 : target g === Hom(source f, target f)|
|                                         |
|o4 = true                                |
+-----------------------------------------+

We can undo the process with homomorphism.

+------------------------+
|i5 : f' = homomorphism g|
|                        |
|o5 = | x y z 0 0 0 |    |
|     | 0 0 0 x y z |    |
|                        |
|             2      6   |
|o5 : Matrix R  <-- R    |
+------------------------+
|i6 : f === f'           |
|                        |
|o6 = true               |
+------------------------+

Code
====

../../../../../Macaulay2/m2/Hom.m2:99:34-101:46: --source code:
homomorphism' Matrix := Matrix => opts -> f -> (
    -- from a map M --> N produce a map R^1 -> Hom(M, N)
    adjoint(f, module ring f, source f, opts))

See also
========

  * Hom -- module of homomorphisms
  * homomorphism -- get the homomorphism from element of
    Hom
  * adjoint -- the tensor-Hom adjunction maps

Ways to use homomorphism':
==========================

  * "homomorphism'(Matrix)"
  * homomorphism'(SheafMap) (missing documentation)

For the programmer
==================

The object homomorphism', is a method function with options.

Hom(Module,Matrix) -- induced map on Hom
****************************************

Synopsis
========

  * Function: Hom,

Description
===========

Synopsis
========

  * Usage:
        Hom(f,g)
  * Inputs:
      * f, a matrix,
      * g, a matrix,
      * DegreeLimit => ...
      * MinimalGenerators => ...
      * Strategy => ...
  * Outputs:
      * a matrix, the map on Hom induced by the maps $f$ and $g$

Synopsis
========

  * Usage:
        Hom(f,M)
        Hom(M,f)
  * Inputs:
      * f, a matrix,
      * M, a module,
      * DegreeLimit => ...
      * MinimalGenerators => ...
      * Strategy => ...
  * Outputs:
      * a matrix, the map on Hom induced by the map $f$
+------------------------------+
|i1 : R = QQ[x]                |
|                              |
|o1 = R                        |
|                              |
|o1 : PolynomialRing           |
+------------------------------+
|i2 : f = vars R               |
|                              |
|o2 = | x |                    |
|                              |
|             1      1         |
|o2 : Matrix R  <-- R          |
+------------------------------+
|i3 : M = image f              |
|                              |
|o3 = image | x |              |
|                              |
|                             1|
|o3 : R-module, submodule of R |
+------------------------------+
|i4 : g = Hom(f,M)             |
|                              |
|o4 = | x |                    |
|                              |
|o4 : Matrix                   |
+------------------------------+
|i5 : target g                 |
|                              |
|o5 = image {-1} | x |         |
|                              |
|                             1|
|o5 : R-module, submodule of R |
+------------------------------+
|i6 : source g                 |
|                              |
|o6 = image | x |              |
|                              |
|                             1|
|o6 : R-module, submodule of R |
+------------------------------+
+----------------------------------+
|i7 : R = QQ[x]                    |
|                                  |
|o7 = R                            |
|                                  |
|o7 : PolynomialRing               |
+----------------------------------+
|i8 : f = vars R                   |
|                                  |
|o8 = | x |                        |
|                                  |
|             1      1             |
|o8 : Matrix R  <-- R              |
+----------------------------------+
|i9 : M = image f                  |
|                                  |
|o9 = image | x |                  |
|                                  |
|                             1    |
|o9 : R-module, submodule of R     |
+----------------------------------+
|i10 : g = Hom(M,f)                |
|                                  |
|o10 = {-1} | x |                  |
|                                  |
|              1      1            |
|o10 : Matrix R  <-- R             |
+----------------------------------+
|i11 : target g                    |
|                                  |
|       1                          |
|o11 = R                           |
|                                  |
|o11 : R-module, free, degrees {-1}|
+----------------------------------+
|i12 : source g                    |
|                                  |
|       1                          |
|o12 = R                           |
|                                  |
|o12 : R-module, free              |
+----------------------------------+

See also
========

  * inducedMap -- compute an induced map

Ways to use this method:
========================

  * "Hom(Matrix,Matrix)"
  * "Hom(Matrix,Module)"
  * Hom(Module,Matrix) -- induced map on Hom

Hom(Module,ChainComplex) -- the Hom functor
*******************************************

Synopsis
========

  * Function: Hom,
  * Usage:
        Hom(M, C)
        Hom(C, M)
  * Inputs:
      * M, a module,
      * C, a chain complex,
  * Optional inputs,:
      * DegreeLimit, => an integer, or a list,
        default value null, see Hom(...,DegreeLimit=>...),
      * MinimalGenerators, => a Boolean value,
        default value true, see Hom(...,MinimalGenerators=>...),
      * Strategy, => a thing, default value null, see
        Hom(...,Strategy=>...),
  * Outputs:
      * a chain complex, the chain complex whose $i$-th
        spot is $\mathrm{Hom}(M, C_i)$, in the first case, or
        $\mathrm{Hom}(C_(-i), M)$ in the second case.

Description
===========

+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..d];                                                           |
+-----------------------------------------------------------------------------+
|i2 : C = res coker vars R                                                    |
|                                                                             |
|      1      4      6      4      1                                          |
|o2 = R  <-- R  <-- R  <-- R  <-- R  <-- 0                                    |
|                                                                             |
|     0      1      2      3      4      5                                    |
|                                                                             |
|o2 : ChainComplex                                                            |
+-----------------------------------------------------------------------------+
|i3 : M = R^1/(a,b)                                                           |
|                                                                             |
|o3 = cokernel | a b |                                                        |
|                                                                             |
|                            1                                                |
|o3 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i4 : C' = Hom(C,M)                                                           |
|                                                                             |
|o4 = 0  <-- cokernel {-4} | b a | <-- cokernel {-3} | b a 0 0 0 0 0 0 | <--  |
|                                               {-3} | 0 0 b a 0 0 0 0 |      |
|     -5     -4                                 {-3} | 0 0 0 0 b a 0 0 |      |
|                                               {-3} | 0 0 0 0 0 0 b a |      |
|                                                                             |
|                                      -3                                     |
|                                                                             |
|                                                                             |
|                                                                             |
|o4 : ChainComplex                                                            |
|-----------------------------------------------------------------------------|
|cokernel {-2} | b a 0 0 0 0 0 0 0 0 0 0 | <-- cokernel {-1} | b a 0 0 0 0 0 0|
|         {-2} | 0 0 b a 0 0 0 0 0 0 0 0 |              {-1} | 0 0 b a 0 0 0 0|
|         {-2} | 0 0 0 0 b a 0 0 0 0 0 0 |              {-1} | 0 0 0 0 b a 0 0|
|         {-2} | 0 0 0 0 0 0 b a 0 0 0 0 |              {-1} | 0 0 0 0 0 0 b a|
|         {-2} | 0 0 0 0 0 0 0 0 b a 0 0 |                                    |
|         {-2} | 0 0 0 0 0 0 0 0 0 0 b a |     -1                             |
|                                                                             |
|-2                                                                           |
|-----------------------------------------------------------------------------|
|| <-- cokernel | b a |                                                       |
||                                                                            |
||     0                                                                      |
||                                                                            |
+-----------------------------------------------------------------------------+
|i5 : C'.dd_-1                                                                |
|                                                                             |
|o5 = {-2} | 0 0 0 0  |                                                       |
|     {-2} | c 0 0 0  |                                                       |
|     {-2} | 0 c 0 0  |                                                       |
|     {-2} | d 0 0 0  |                                                       |
|     {-2} | 0 d 0 0  |                                                       |
|     {-2} | 0 0 d -c |                                                       |
|                                                                             |
|o5 : Matrix                                                                  |
+-----------------------------------------------------------------------------+
|i6 : C'.dd^2 == 0                                                            |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

induced map on Hom
==================

  * Usage:
        Hom(f,M)
        Hom(M,f)
  * Inputs:
      * f, a chain complex map,
      * M, a module,
      * DegreeLimit => ...
      * MinimalGenerators => ...
      * Strategy => ...
  * Outputs:
      * a chain complex map, the induced map on Hom

Caveat
======

See Hom(Complex,Complex) (Complexes), for Hom
of two chain complexes.

See also
========

  * resolution -- projective resolution

Ways to use this method:
========================

  * "Hom(ChainComplex,Module)"
  * "Hom(ChainComplexMap,Module)"
  * Hom(Module,ChainComplex) -- the Hom
    functor
  * "Hom(Module,ChainComplexMap)"

homeDirectory -- the home directory of the user
***********************************************

Synopsis
========

  * Usage:
        homeDirectory
  * Outputs:
      * a string, the home directory of the user

Description
===========

In file operations, file names beginning with ~/ will have it replaced with the
home directory.

+------------------+
|i1 : homeDirectory|
|                  |
|o1 = /home/m2user/|
+------------------+

For the programmer
==================

The object homeDirectory, is a string.

Homogeneous -- a Strategy option value
**************************************

Description
===========

Homogeneous -- a strategy used with the keyword Strategy.

This is an alternate Gröbner basis algorithm that can be used if the submodule
is homogeneous, and the ring is a (quotient of) a polynomial ring over a field.

See also
========

  * gb(...,Strategy=>...) -- compute a Gröbner basis

Functions with optional argument named Homogeneous:
===================================================

  * "isIsomorphic(...,Homogeneous=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules

For the programmer
==================

The object Homogeneous, is a symbol.

homogenize -- homogenize with respect to a variable
***************************************************

Description
===========

homogenize(m,v) -- homogenize the ring element, vector, matrix, or module m
using the variable v in the ring of m.
homogenize(m,v,w) -- homogenize m using the variable v, so that the result is
homogeneous with respect to the given list w of integers provided as weights
for the variables.

+-----------------------------------------+
|i1 : R = ZZ/101[x,y,z,Degrees => {1,2,3}]|
|                                         |
|o1 = R                                   |
|                                         |
|o1 : PolynomialRing                      |
+-----------------------------------------+
|i2 : f = 1 + y + z^2                     |
|                                         |
|      2                                  |
|o2 = z  + y + 1                          |
|                                         |
|o2 : R                                   |
+-----------------------------------------+
|i3 : homogenize(f,x)                     |
|                                         |
|      6    4     2                       |
|o3 = x  + x y + z                        |
|                                         |
|o3 : R                                   |
+-----------------------------------------+
|i4 : homogenize(f,x,{1,0,-1})            |
|                                         |
|      2 2                                |
|o4 = x z  + y + 1                        |
|                                         |
|o4 : R                                   |
+-----------------------------------------+

The weights that may be used are limited (roughly) to the range -2^30 .. 2^30.

Caveat
======

If the homogenization overflows the monomial, this is not reported as an error.

Ways to use homogenize:
=======================

  * "homogenize(Ideal,RingElement)"
  * "homogenize(Matrix,RingElement)"
  * "homogenize(Matrix,RingElement,List)"
  * "homogenize(Module,RingElement)"
  * "homogenize(Module,RingElement,List)"
  * "homogenize(RingElement,RingElement)"
  * "homogenize(RingElement,RingElement,List)"
  * "homogenize(Vector,RingElement)"
  * "homogenize(Vector,RingElement,List)"

For the programmer
==================

The object homogenize, is a method function.

homology -- general homology functor
************************************

Description
===========

Most applications of this functor are dispatched through HH. If it is intended
that i be of class ZZ, M be of class A, and N be of class B, then
the method for computing HH_i(M,N) can be installed with code of the following
form.
     homology(ZZ, A, B) := opts -> (i,M,N) -> ...

See also
========

  * cohomology -- general cohomology functor
  * HH -- general homology and cohomology functor
  * ScriptedFunctor -- the class of all scripted
    functors

Ways to use homology:
=====================

  * HH ChainComplex -- homology of a chain complex
  * HH ChainComplexMap -- homology of a chain
    complex map
  * HH_ZZ ChainComplex -- homology of a chain
    complex
  * HH_ZZ ChainComplexMap -- homology of a
    chain complex map
  * HH_ZZ Sequence (missing documentation)
  * homology(Matrix,Matrix) -- homology
    of a pair of maps
  * homology(SheafMap,SheafMap) (missing documentation)

For the programmer
==================

The object homology, is a method function with options.

homology(Matrix,Matrix) -- homology of a pair of maps
*****************************************************

Synopsis
========

  * Function: homology,
  * Usage:
        M = homology(f,g)
  * Inputs:
      * f
      * g
  * Outputs:
      * M, computes the homology module (kernel f)/(image g).

Description
===========

Here g and f should be composable maps with f*g equal to zero.

In the following example, we ensure that the source of f and the target of f
are exactly the same, taking even the degrees into account, and we ensure that
f is homogeneous.

+------------------------------------------+
|i1 : R = QQ[x]/x^5;                       |
+------------------------------------------+
|i2 : f = map(R^1,R^1,{{x^3}}, Degree => 3)|
|                                          |
|o2 = | x3 |                               |
|                                          |
|             1      1                     |
|o2 : Matrix R  <-- R                      |
+------------------------------------------+
|i3 : M = homology(f,f)                    |
|                                          |
|o3 = subquotient (| x2 |, | x3 |)         |
|                                          |
|                               1          |
|o3 : R-module, subquotient of R           |
+------------------------------------------+
|i4 : prune M                              |
|                                          |
|o4 = cokernel {2} | x |                   |
|                                          |
|                            1             |
|o4 : R-module, quotient of R              |
+------------------------------------------+

Ways to use this method:
========================

  * homology(Matrix,Matrix) -- homology
    of a pair of maps

homomorphisms (maps) between modules -- including elements of modules
*********************************************************************

+------------------------------+
|i1 : R = QQ[x,y];             |
+------------------------------+
|i2 : M = image vars R         |
|                              |
|o2 = image | x y |            |
|                              |
|                             1|
|o2 : R-module, submodule of R |
+------------------------------+
|i3 : N = coker presentation M |
|                              |
|o3 = cokernel {1} | -y |      |
|              {1} | x  |      |
|                              |
|                            2 |
|o3 : R-module, quotient of R  |
+------------------------------+
|i4 : f = map(M,N,1)           |
|                              |
|o4 = {1} | 1 0 |              |
|     {1} | 0 1 |              |
|                              |
|o4 : Matrix M <-- N           |
+------------------------------+
|i5 : isWellDefined f          |
|                              |
|o5 = true                     |
+------------------------------+
|i6 : isIsomorphism f          |
|                              |
|o6 = true                     |
+------------------------------+
|i7 : g = map(M,cover M,1)     |
|                              |
|o7 = {1} | 1 0 |              |
|     {1} | 0 1 |              |
|                              |
|                   2          |
|o7 : Matrix M <-- R           |
+------------------------------+
|i8 : isWellDefined g          |
|                              |
|o8 = true                     |
+------------------------------+
|i9 : isIsomorphism g          |
|                              |
|o9 = false                    |
+------------------------------+
|i10 : h = map(cover M,M,1)    |
|                              |
|o10 = {1} | 1 0 |             |
|      {1} | 0 1 |             |
|                              |
|              2               |
|o10 : Matrix R  <-- M         |
+------------------------------+
|i11 : isWellDefined h         |
|                              |
|o11 = false                   |
+------------------------------+

html -- convert to HTML format
******************************

Synopsis
========

  * Usage:
        html x
  * Inputs:
      * x, a thing, any Macaulay2 object
  * Outputs:
      * a string, the HTML rendering of x

Description
===========

html x converts x to HTML format.

The return value is a string that is suitable for use in a .html file readable
by a browser. See hypertext, elements are translated into the
corresponding HTML elements. When no HTML conversion is available, see tex,
is called. $\LaTeX$ can be rendered in the browser using MathJax or
$\KaTeX$.

See also
========

  * show -- display various objects in an external viewer
  * mathML -- convert to MathML format
  * html(TEX) (Text) -- conversion of $\TeX$ to html

For the programmer
==================

The object html, is a method function with a single argument.

httpHeaders(String) -- prepend http headers to a string
*******************************************************

Synopsis
========

  * Function: httpHeaders,
  * Usage:
        httpHeaders s
  * Inputs:
      * s, a string,
  * Outputs:
      * a string, the string obtained from s by prepending
        appropriate headers to it

Description
===========

This function is experimental, and is intended to support the development of
web servers.

+-------------------------------------------+
|i1 : httpHeaders "hi there"                |
|                                           |
|o1 = HTTP/1.1 200 OK                       |
|     Server: Macaulay2/1.24.11             |
|     Connection: close                     |
|     Content-Length: 8                     |
|     Content-type: text/html; charset=utf-8|
|                                           |
|     hi there                              |
+-------------------------------------------+

Ways to use this method:
========================

  * httpHeaders(String) -- prepend http headers
    to a string

hypertext -- prepare hypertext for display
******************************************

Synopsis
========

  * Usage:
        hypertext x
  * Inputs:
      * x, a list, a list of strings and hypertext mark-up lists
  * Outputs:
      * a markup list (Text), a new list of mark-up lists
        obtained from the old by making the format more suitable for ultimate
        display

Description
===========

Here is a list of some of the transformations that are performed.
  * occurrences of null, such as those that might have been produced by the
    insertion of an extra comma, are removed
  * sequences, such as those produced by extra sets of
    parentheses, are spliced, into the lists containing them
  * the contents of lists and sequences are merged into the mark-up lists
    containing them
  * mark-up lists of type TO (Text), occurring a mark-up list of type
    UL (Text), are converted to lists of type TOH (Text),
    so the headlines of the items will appear in the resulting menu
  * the targets of the links in mark-up lists of type TO, TOH, and TO2, are
    converted into document tags,
  * mark-up types, such as PARA (Text), are converted into lists of
    length 0 of that type
  * strings spanning multiple lines are wrapped into one long line after
    appropriately trimming the spaces at the beginning and end of each line
  * an error message is produced if something not recognizable as documentation
    is encountered
We may phase out this function in favor of performing the listed
transformations automatically when hypertext elements are created.

See also
========

  * Hypertext (Text) -- the class of markup lists used with
    hypertext

For the programmer
==================

The object hypertext, is a method function with a single argument.

id -- identity map
******************

Synopsis
========

  * Usage:
        id_F
  * Inputs:
      * F, a ring, a module, or a chain complex,
  * Outputs:
      * a ring map, a matrix, or a chain complex map,
        the identity map on F

Description
===========

+-------------------------------------------+
|i1 : R = QQ[a..d];                         |
+-------------------------------------------+
|i2 : id_R                                  |
|                                           |
|o2 = map (R, R, {a, b, c, d})              |
|                                           |
|o2 : RingMap R <-- R                       |
+-------------------------------------------+
|i3 : id_(R^3)                              |
|                                           |
|o3 = | 1 0 0 |                             |
|     | 0 1 0 |                             |
|     | 0 0 1 |                             |
|                                           |
|             3      3                      |
|o3 : Matrix R  <-- R                       |
+-------------------------------------------+
|i4 : C = res coker vars R                  |
|                                           |
|      1      4      6      4      1        |
|o4 = R  <-- R  <-- R  <-- R  <-- R  <-- 0  |
|                                           |
|     0      1      2      3      4      5  |
|                                           |
|o4 : ChainComplex                          |
+-------------------------------------------+
|i5 : id_C                                  |
|                                           |
|          1             1                  |
|o5 = 0 : R  <--------- R  : 0              |
|               | 1 |                       |
|                                           |
|          4                       4        |
|     1 : R  <------------------- R  : 1    |
|               {1} | 1 0 0 0 |             |
|               {1} | 0 1 0 0 |             |
|               {1} | 0 0 1 0 |             |
|               {1} | 0 0 0 1 |             |
|                                           |
|          6                           6    |
|     2 : R  <----------------------- R  : 2|
|               {2} | 1 0 0 0 0 0 |         |
|               {2} | 0 1 0 0 0 0 |         |
|               {2} | 0 0 1 0 0 0 |         |
|               {2} | 0 0 0 1 0 0 |         |
|               {2} | 0 0 0 0 1 0 |         |
|               {2} | 0 0 0 0 0 1 |         |
|                                           |
|          4                       4        |
|     3 : R  <------------------- R  : 3    |
|               {3} | 1 0 0 0 |             |
|               {3} | 0 1 0 0 |             |
|               {3} | 0 0 1 0 |             |
|               {3} | 0 0 0 1 |             |
|                                           |
|          1                 1              |
|     4 : R  <------------- R  : 4          |
|               {4} | 1 |                   |
|                                           |
|     5 : 0 <----- 0 : 5                    |
|              0                            |
|                                           |
|o5 : ChainComplexMap                       |
+-------------------------------------------+

Ways to use id:
===============

  * "id _ ChainComplex"
  * "id _ Module"
  * "id _ Ring"
  * id _ CoherentSheaf (missing documentation)

For the programmer
==================

The object id, is a scripted functor.

Ideal -- the class of all ideals
********************************

Description
===========

For basic information about ideals in Macaulay2, see ideals.

Common ways to make an ideal:
  * ideal -- make an ideal
  * annihilator (Saturation) -- the annihilator ideal
  * content -- the content of a polynomial
  * fittingIdeal -- Fitting ideal of a module
  * kernel(RingMap) -- kernel of a ringmap
  * minors -- ideal generated by minors
  * pfaffians -- ideal generated by Pfaffians
Common ways to get information about an ideal:
  * generators(Ideal) -- the generator matrix of
    an ideal
  * Ideal _* -- get the list of generators of an ideal
  * isSubset(Ideal,Ideal) -- whether one
    object is a subset of another
  * isPrime(Ideal) (MinimalPrimes) -- whether an
    ideal is prime
Common operations on ideals:
  * Ideal + Ideal -- sum of ideals
  * Ideal * Ideal -- product of ideals
  * Ideal == Ideal (missing documentation)
  * Ideal == ZZ (missing documentation)
  * Ideal ^ ZZ -- power of an ideal
  * trim(Ideal) -- minimize generators and relations
Gröbner bases, normal forms, free resolutions
  * gb -- compute a Gröbner basis
  * leadTerm -- get the greatest term
  * codim -- compute the codimension
  * dim -- compute the Krull dimension
  * Matrix % Ideal -- normal
    form of ring elements and matrices
  * resolution -- projective resolution
  * betti -- display or modify a Betti diagram
Numeric information about homogeneous ideals
  * degree
  * poincare -- assemble degrees of a ring, module, or ideal
    into a polynomial
  * hilbertFunction -- the Hilbert function
  * hilbertPolynomial -- compute the Hilbert
    polynomial
  * hilbertSeries -- compute the Hilbert series
  * genera (missing documentation)
  * euler (missing documentation)
Primary decomposition and components of an ideal
  * minimalPrimes (MinimalPrimes) -- minimal primes of an
    ideal
  * radical (MinimalPrimes) -- the radical of an ideal
  * associatedPrimes (PrimaryDecomposition) -- find
    associated primes
  * primaryDecomposition (PrimaryDecomposition), --
    irredundant primary decomposition of an ideal
  * topComponents (PrimaryDecomposition) -- compute top
    dimensional component of an ideal or module
  * saturate(Ideal,Ideal) (Saturation) -- saturation of ideal
    or submodule
  * Ideal _colon_ Ideal (Saturation), --
    ideal or submodule quotient
  * intersect -- compute an intersection
Ideals from geometry
  * Fano -- Fano scheme
  * Grassmannian -- the Grassmannian of
    linear subspaces of a vector space
  * monomialCurveIdeal -- make the ideal of a
    monomial curve
  * singularLocus -- singular locus
Common ways to use an ideal:
  * Ring / Ideal -- make a quotient ring

An ideal I is an immutable object, so if you want to cache information about
it, put it in the hash table I.cache.

See also
========

  * ideals

Types of ideal:
===============

  * MonomialIdeal -- the class of all monomial ideals
    handled by the engine

Functions and methods returning an ideal:
=========================================

  * "Ideal * Ring" -- see *, -- a binary operator, usually used for
    multiplication
  * "Ring * Ideal" -- see *, -- a binary operator, usually used for
    multiplication
  * "RingElement * Ideal" -- see *, -- a binary operator, usually
    used for multiplication
  * "annihilator(Ideal)" -- see annihilator (Saturation), --
    the annihilator ideal
  * "annihilator(Module)" -- see annihilator (Saturation), --
    the annihilator ideal
  * "annihilator(RingElement)" -- see annihilator (Saturation),
    -- the annihilator ideal
  * annihilator(CoherentSheaf) (Varieties)
    -- the annihilator ideal
  * "conductor(RingMap)" -- see conductor (IntegralClosure), --
    the conductor of a finite ring map
  * "content(RingElement)" -- see content, -- the content of a
    polynomial
  * "content(RingElement,RingElement)" -- see content, -- the
    content of a polynomial
  * "expectedReesIdeal(Module)" -- see expectedReesIdeal (ReesAlgebra),
    -- symmetric algebra ideal plus jacobian
    dual
  * Fano(ZZ,Ideal) -- Fano scheme
  * Fano(ZZ,Ideal,Ring) -- Fano scheme
  * fittingIdeal -- Fitting ideal of a module
  * graphIdeal(RingMap) -- the ideal of the
    graph of the regular map corresponding to a ring map
  * "Grassmannian" -- see Grassmannian(ZZ,ZZ),
    -- the Grassmannian of linear subspaces of a vector space
  * "homogenize(Ideal,RingElement)" -- see homogenize, --
    homogenize with respect to a variable
  * "icPIdeal(RingElement,RingElement,ZZ)" -- see icPIdeal (IntegralClosure),
    -- compute the integral closure in prime
    characteristic of a principal ideal
  * ideal -- make an ideal
  * Ideal * Ideal -- product of ideals
  * Ideal * RingElement (missing documentation)
  * Ideal + Ideal -- sum of ideals
  * Ideal ^ ZZ -- power of an ideal
  * ideal(List) -- make an ideal
  * "ideal(Sequence)" -- see ideal(List), -- make an
    ideal
  * ideal(Matrix) -- make an ideal
  * ideal(Module) -- converts a module to an ideal
  * "ideal(Number)" -- see ideal(RingElement), --
    make an ideal
  * ideal(RingElement) -- make an ideal
  * ideal(String) (Classic) -- make an ideal using
    classic Macaulay syntax
  * "integralClosure(Ideal)" -- see
    integralClosure(Ideal,RingElement,ZZ) (IntegralClosure),
    -- integral
    closure of an ideal in an affine domain
  * "integralClosure(Ideal,RingElement)" -- see
    integralClosure(Ideal,RingElement,ZZ) (IntegralClosure),
    -- integral
    closure of an ideal in an affine domain
  * "integralClosure(Ideal,ZZ)" -- see
    integralClosure(Ideal,RingElement,ZZ) (IntegralClosure),
    -- integral
    closure of an ideal in an affine domain
  * "intersect(Ideal)" -- see intersect(Ideal,Ideal),
    -- compute an intersection of a sequence of
    ideals or modules
  * intersect(Ideal,Ideal) -- compute an
    intersection of a sequence of ideals or modules
  * kernel(RingMap) -- kernel of a ringmap
  * "lift(Ideal,type of RingElement)" -- see lift, -- lift to
    another ring
  * "localize(Ideal,Ideal)" -- see localize (PrimaryDecomposition),
    -- localize an ideal at a prime ideal
  * minimalPresentation(Ideal), --
    compute a minimal presentation of the quotient ring defined by an ideal
  * "prune(Ideal)" -- see minimalPresentation(Ideal),
    -- compute a minimal presentation of the
    quotient ring defined by an ideal
  * "minimalReduction(Ideal)" -- see minimalReduction (ReesAlgebra),
    -- Find a minimal reduction of an ideal
  * minors(ZZ,Matrix) -- ideal generated by
    minors
  * "Ideal ** Ring" -- see Module ** Ring, -- tensor
    product
  * "Ring ** Ideal" -- see Module ** Ring, -- tensor
    product
  * "permanents(ZZ,Matrix)" -- see permanents, -- ideal
    generated by square permanents of a matrix
  * pfaffians -- ideal generated by Pfaffians
  * "preimage(RingMap,Ideal)" -- see preimage, -- preimage of a
    map
  * "primaryComponent(Ideal,Ideal)" -- see primaryComponent (PrimaryDecomposition),
    -- find a primary component
    corresponding to an associated prime
  * "Ideal : Ideal" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "Ideal : RingElement" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "Module : Module" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotient(Ideal,Ideal)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotient(Ideal,RingElement)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "radical(Ideal)" -- see radical (MinimalPrimes), -- the
    radical of an ideal
  * "reesIdeal(Ideal)" -- see reesIdeal (ReesAlgebra), --
    Compute the defining ideal of the Rees Algebra
  * "reesIdeal(Ideal,RingElement)" -- see reesIdeal (ReesAlgebra),
    -- Compute the defining ideal of the Rees Algebra
  * "reesIdeal(Module)" -- see reesIdeal (ReesAlgebra), --
    Compute the defining ideal of the Rees Algebra
  * "reesIdeal(Module,RingElement)" -- see reesIdeal (ReesAlgebra),
    -- Compute the defining ideal of the Rees Algebra
  * "regSeqInIdeal(Ideal)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * "regSeqInIdeal(Ideal,ZZ)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * "regSeqInIdeal(Ideal,ZZ,ZZ,ZZ)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * "removeLowestDimension(Ideal)" -- see removeLowestDimension (PrimaryDecomposition),
    -- remove components of lowest
    dimension
  * "RingMap Ideal" -- see RingMap RingElement, --
    apply a ring map
  * "saturate(Ideal)" -- see saturate (Saturation), --
    saturation of ideal or submodule
  * "saturate(Ideal,Ideal)" -- see saturate (Saturation), --
    saturation of ideal or submodule
  * "saturate(Ideal,RingElement)" -- see saturate (Saturation),
    -- saturation of ideal or submodule
  * "Schubert" -- see Schubert(ZZ,ZZ,VisibleList),
    -- find the Plücker ideal of a
    Schubert variety
  * specialFiberIdeal (ReesAlgebra) -- Special fiber
    of a blowup
  * "substitute(Ideal,List)" -- see substitute, --
    substituting values for variables
  * "substitute(Ideal,Matrix)" -- see substitute, --
    substituting values for variables
  * "substitute(Ideal,Ring)" -- see substitute, --
    substituting values for variables
  * "substitute(Ideal,RingFamily)" -- see substitute, --
    substituting values for variables
  * "symmetricAlgebraIdeal(Ideal)" -- see symmetricAlgebraIdeal (ReesAlgebra),
    -- Ideal of the symmetric algebra of an
    ideal or module
  * "symmetricAlgebraIdeal(Module)" -- see symmetricAlgebraIdeal (ReesAlgebra),
    -- Ideal of the symmetric algebra of an
    ideal or module
  * "symmetricKernel(Matrix)" -- see symmetricKernel (ReesAlgebra),
    -- Compute the Rees ring of the image of a
    matrix
  * "tangentCone" -- see tangentCone(Ideal) (TangentCone),
  * "topComponents(Ideal)" -- see topComponents (PrimaryDecomposition),
    -- compute top dimensional component
    of an ideal or module
  * "trim(Ideal)" -- see trim, -- minimize generators and relations
  * "truncate(List,Ideal)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * "truncate(List,Ring)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees

Methods that use an ideal:
==========================

  * "Number % Ideal" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "Ideal * Module" -- see *, -- a binary operator, usually used
    for multiplication
  * "Ideal * Vector" -- see *, -- a binary operator, usually used
    for multiplication
  * "Ideal + RingElement" -- see +, -- a unary or binary operator,
    usually used for addition
  * "analyticSpread(Ideal)" -- see analyticSpread (ReesAlgebra),
    -- Compute the analytic spread of a module or
    ideal
  * "analyticSpread(Ideal,RingElement)" -- see analyticSpread (ReesAlgebra),
    -- Compute the analytic spread of a module or
    ideal
  * "associatedGradedRing(Ideal)" -- see associatedGradedRing (ReesAlgebra),
    -- The normal cone of a subscheme
  * "associatedGradedRing(Ideal,RingElement)" -- see
    associatedGradedRing (ReesAlgebra), -- The normal cone
    of a subscheme
  * "normalCone(Ideal)" -- see associatedGradedRing (ReesAlgebra),
    -- The normal cone of a subscheme
  * "normalCone(Ideal,RingElement)" -- see associatedGradedRing (ReesAlgebra),
    -- The normal cone of a subscheme
  * "associatedPrimes(Ideal)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "basis(Ideal)" -- see basis, -- basis or generating set of all
    or part of a ring, ideal or module
  * "basis(InfiniteNumber,InfiniteNumber,Ideal)" -- see basis, --
    basis or generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,List,Ideal)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,ZZ,Ideal)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,Ideal)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(List,InfiniteNumber,Ideal)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,List,Ideal)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,ZZ,Ideal)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(ZZ,Ideal)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(ZZ,InfiniteNumber,Ideal)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(ZZ,List,Ideal)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(ZZ,ZZ,Ideal)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "betti(Ideal)" -- see betti, -- display or modify a Betti
    diagram
  * codim(Ideal) -- compute the codimension
  * "CoherentSheaf / Ideal" -- see CoherentSheaf / CoherentSheaf (Varieties),
    -- quotient of coherent sheaves
  * "comodule(Ideal)" -- see comodule, -- submodule to quotient
    module
  * "quotient(Ideal)" -- see comodule, -- submodule to quotient
    module
  * degree(Ideal)
  * "degrees(Ideal)" -- see degrees(Ring), -- degrees
    of generators
  * dim(Ideal) -- compute the Krull dimension
  * "distinguished(Ideal)" -- see distinguished (ReesAlgebra),
    -- Compute the distinguished subvarieties of a
    pullback, intersection or cone
  * "distinguished(Ideal,Ideal)" -- see distinguished (ReesAlgebra),
    -- Compute the distinguished subvarieties of a
    pullback, intersection or cone
  * "distinguished(RingMap,Ideal)" -- see distinguished (ReesAlgebra),
    -- Compute the distinguished subvarieties of a
    pullback, intersection or cone
  * "eliminate(List,Ideal)" -- see eliminate (Elimination),
  * "eliminate(RingElement,Ideal)" -- see eliminate (Elimination),
  * euler(Ideal) (Varieties)
  * eulers(Ideal) (Varieties)
  * "expectedReesIdeal(Ideal)" -- see expectedReesIdeal (ReesAlgebra),
    -- symmetric algebra ideal plus jacobian
    dual
  * "Ext(Ideal,Ideal)" -- see Ext(Module,Module),
    -- total Ext module
  * "Ext(Ideal,Module)" -- see Ext(Module,Module),
    -- total Ext module
  * "Ext(Ideal,Ring)" -- see Ext(Module,Module),
    -- total Ext module
  * "Ext(Module,Ideal)" -- see Ext(Module,Module),
    -- total Ext module
  * Ext(Ring,Ideal) (missing documentation)
  * "Ext^ZZ(Matrix,Ideal)" -- see Ext^ZZ(Matrix,Module),
    -- map between Ext modules
  * "Ext^ZZ(Ideal,Matrix)" -- see Ext^ZZ(Module,Matrix),
    -- map between Ext modules
  * "Ext^ZZ(Ideal,Ideal)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * "Ext^ZZ(Ideal,Module)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * "Ext^ZZ(Ideal,Ring)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * "Ext^ZZ(Module,Ideal)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * Ext^ZZ(Ring,Ideal) (missing documentation)
  * "flattenRing(Ideal)" -- see flattenRing, -- write a ring
    as a (quotient of a) polynomial ring
  * "gb(Ideal)" -- see gb, -- compute a Gröbner basis
  * "gbRemove(Ideal)" -- see gbRemove, -- remove Gröbner basis
  * "gbSnapshot(Ideal)" -- see gbSnapshot, -- the Gröbner
    basis matrix as so far computed
  * genera(Ideal) (Varieties)
  * "generator(Ideal)" -- see generator, -- provide a single
    generator
  * "Ideal _ ZZ" -- see generators of ideals and modules,
  * generators(Ideal) -- the generator matrix of
    an ideal
  * "genus(Ideal)" -- see genus(CoherentSheaf) (Varieties),
  * "groebnerBasis(Ideal)" -- see groebnerBasis, --
    Gröbner basis, as a matrix
  * "hilbertFunction(Ideal)" -- see hilbertFunction, --
    the Hilbert function
  * "hilbertFunction(List,Ideal)" -- see hilbertFunction,
    -- the Hilbert function
  * "hilbertFunction(ZZ,Ideal)" -- see hilbertFunction,
    -- the Hilbert function
  * hilbertPolynomial(Ideal) -- compute
    the Hilbert polynomial of the quotient of the ambient ring by the ideal
  * hilbertSeries(Ideal) -- compute the
    Hilbert series of the quotient of the ambient ring by the ideal
  * "Hom(Ideal,Ideal)" -- see Hom, -- module of homomorphisms
  * "Hom(Ideal,Module)" -- see Hom, -- module of homomorphisms
  * "Hom(Ideal,Ring)" -- see Hom, -- module of homomorphisms
  * "Hom(Module,Ideal)" -- see Hom, -- module of homomorphisms
  * "Hom(Ring,Ideal)" -- see Hom, -- module of homomorphisms
  * Ideal * CoherentSheaf (missing documentation)
  * Ideal * ZZ (missing documentation)
  * Ideal + Number (missing documentation)
  * /// Function \ Ideal /// -- see Ideal / Function,
    -- apply a function to generators of an ideal
  * Ideal / Function -- apply a function to generators
    of an ideal
  * Ideal / Ideal -- quotient module
  * Ideal == Ideal (missing documentation)
  * Ideal == Module (missing documentation)
  * Ideal == Ring (missing documentation)
  * Ideal == ZZ (missing documentation)
  * Ideal ^ Array -- bracket power of an ideal
  * Ideal _* -- get the list of generators of an ideal
  * "idealizer(Ideal,RingElement)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * "independentSets(Ideal)" -- see independentSets, --
    some size-maximal independent subsets of variables modulo an ideal
  * installHilbertFunction(Ideal,RingElement) (missing documentation)
  * integralClosure(Ideal,RingElement,ZZ) (IntegralClosure)
    -- integral
    closure of an ideal in an affine domain
  * "intersectInP(Ideal,Ideal)" -- see intersectInP (ReesAlgebra),
    -- Compute distinguished varieties for an
    intersection in A^n or P^n
  * "inverseSystem(Ideal)" -- see inverseSystem (InverseSystems),
    -- Inverse systems with equivariance
  * "inverseSystem(ZZ,Ideal)" -- see inverseSystem (InverseSystems),
    -- Inverse systems with equivariance
  * "irreducibleCharacteristicSeries(Ideal)" -- see
    irreducibleCharacteristicSeries, --
    irreducible characteristic series of an ideal
  * "isHomogeneous(Ideal)" -- see isHomogeneous, --
    whether something is homogeneous (graded)
  * "isIdeal(Ideal)" -- see isIdeal, -- whether something is an
    ideal
  * "isLinearType(Ideal)" -- see isLinearType (ReesAlgebra),
    -- Determine whether module has linear type
  * "isLinearType(Ideal,RingElement)" -- see isLinearType (ReesAlgebra),
    -- Determine whether module has linear type
  * "isMember(Number,Ideal)" -- see isMember(RingElement,Ideal),
    -- test membership in an ideal
  * isMember(RingElement,Ideal), --
    test membership in an ideal
  * "isMonomialIdeal(Ideal)" -- see isMonomialIdeal, --
    whether something is a monomial ideal
  * "isPrimary(Ideal)" -- see isPrimary (PrimaryDecomposition),
    -- determine whether a submodule is primary
  * "isPrimary(Ideal,Ideal)" -- see isPrimary (PrimaryDecomposition),
    -- determine whether a submodule is
    primary
  * isPrime(Ideal) (MinimalPrimes) -- whether an
    ideal is prime
  * "isReduction(Ideal,Ideal)" -- see isReduction (ReesAlgebra),
    -- Determine whether an ideal is a reduction
  * "isReduction(Ideal,Ideal,RingElement)" -- see isReduction (ReesAlgebra),
    -- Determine whether an ideal is a reduction
  * "isSquareFree(Ideal)" -- see isSquareFree, -- whether
    something is square free monomial ideal
  * isSubset(Ideal,Ideal) -- whether one
    object is a subset of another
  * "isSubset(Ideal,Module)" -- see isSubset(Module,Module),
    -- whether one object is a subset of another
  * "isSubset(Module,Ideal)" -- see isSubset(Module,Module),
    -- whether one object is a subset of another
  * "isSupportedInZeroLocus(Ideal,GradedModule)" -- see
    isSupportedInZeroLocus (Saturation), -- whether
    support of a module is contained in the zero locus of the (irrelevant)
    ideal
  * "isSupportedInZeroLocus(Ideal,Ideal)" -- see isSupportedInZeroLocus (Saturation),
    -- whether support of a module is
    contained in the zero locus of the (irrelevant) ideal
  * "isSupportedInZeroLocus(Ideal,Module)" -- see isSupportedInZeroLocus (Saturation),
    -- whether support of a module is
    contained in the zero locus of the (irrelevant) ideal
  * jacobian(Ideal) -- the Jacobian matrix of the
    generators of an ideal
  * "kernelOfLocalization(Module,Ideal)" -- see kernelOfLocalization (PrimaryDecomposition),
    -- the kernel of the
    localization map
  * leadTerm(Ideal) -- get the ideal of greatest
    terms
  * leadTerm(ZZ,Ideal) -- get the ideal of
    lead polynomials
  * "lift(Ideal,type of QQ)" -- see lift, -- lift to another ring
  * "lift(Ideal,type of ZZ)" -- see lift, -- lift to another ring
  * "Matrix % Ideal" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "RingElement % Ideal" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "mingens(Ideal)" -- see mingens(Module), --
    minimal generator matrix
  * "minimalBetti(Ideal)" -- see minimalBetti, -- minimal
    betti numbers of (the minimal free resolution of) a homogeneous ideal or
    module
  * "decompose(Ideal)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(Ideal)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "Module / Ideal" -- see Module / Module, -- quotient
    module
  * Module == Ideal (missing documentation)
  * "Ideal _ List" -- see Module _ List, -- map from
    free module to some generators
  * module(Ideal) (missing documentation)
  * monomialIdeal(Ideal) -- monomial ideal of
    lead monomials of a Gröbner basis
  * "monomialSubideal(Ideal)" -- see monomialSubideal,
    -- find the largest monomial ideal in an ideal
  * "multidegree(Ideal)" -- see multidegree, -- multidegree
  * "multiplicity(Ideal)" -- see multiplicity (ReesAlgebra),
    -- Compute the Hilbert-Samuel multiplicity of an ideal
  * "multiplicity(Ideal,RingElement)" -- see multiplicity (ReesAlgebra),
    -- Compute the Hilbert-Samuel multiplicity of an
    ideal
  * Number + Ideal (missing documentation)
  * numgens(Ideal) -- number of generators of an
    ideal
  * "poincare(Ideal)" -- see poincare, -- assemble degrees of a
    ring, module, or ideal into a polynomial
  * "primaryDecomposition(Ideal)" -- see primaryDecomposition (PrimaryDecomposition),
    -- irredundant primary
    decomposition of an ideal
  * "Module : Ideal" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotient(Module,Ideal)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "radicalContainment(Ideal,Ideal)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * "radicalContainment(RingElement,Ideal)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * "random(List,Ideal)" -- see random(ZZ,Ideal),
    -- get a random homogeneous element from a graded ideal
  * random(ZZ,Ideal) -- get a random homogeneous
    element from a graded ideal
  * "randomKRationalPoint(Ideal)" -- see randomKRationalPoint,
    -- Pick a random K rational point on the scheme X
    defined by I
  * "reductionNumber(Ideal,Ideal)" -- see reductionNumber (ReesAlgebra),
    -- Reduction number of one ideal with respect
    to another
  * "reesAlgebra(Ideal)" -- see reesAlgebra (ReesAlgebra), --
    Compute the defining ideal of the Rees Algebra
  * "reesAlgebra(Ideal,RingElement)" -- see reesAlgebra (ReesAlgebra),
    -- Compute the defining ideal of the Rees Algebra
  * "regularity(Ideal)" -- see regularity, -- compute the
    Castelnuovo-Mumford regularity
  * resolution(Ideal) -- compute a projective
    resolution of (the quotient ring corresponding to) an ideal
  * "ring(Ideal)" -- see ring, -- get the associated ring of an
    object
  * Ring / Ideal -- make a quotient ring
  * Ring == Ideal (missing documentation)
  * RingElement + Ideal (missing documentation)
  * "saturate(Module,Ideal)" -- see saturate (Saturation), --
    saturation of ideal or submodule
  * "saturate(Vector,Ideal)" -- see saturate (Saturation), --
    saturation of ideal or submodule
  * "singularLocus(Ideal)" -- see singularLocus, --
    singular locus
  * "specialFiber(Ideal)" -- see specialFiber (ReesAlgebra),
    -- Special fiber of a blowup
  * "specialFiber(Ideal,RingElement)" -- see specialFiber (ReesAlgebra),
    -- Special fiber of a blowup
  * "specialFiberIdeal(Ideal)" -- see specialFiberIdeal (ReesAlgebra),
    -- Special fiber of a blowup
  * "specialFiberIdeal(Ideal,RingElement)" -- see specialFiberIdeal (ReesAlgebra),
    -- Special fiber of a blowup
  * "statePolytope(Ideal)" -- see statePolytope (Polyhedra),
    -- computes the state polytope of a homogeneous
    ideal
  * "substitute(Ideal,Option)" -- see substitute, --
    substituting values for variables
  * support(Ideal) -- list of variables occurring in
    the generators of an ideal
  * tangentCone(Ideal) (TangentCone)
  * "toDual(ZZ,Ideal)" -- see toDual (InverseSystems), -- finds
    the inverse system to an ideal up to a given degree
  * Tor_ZZ(Ideal,Matrix) (missing documentation)
  * Tor_ZZ(Matrix,Ideal) (missing documentation)
  * "Tor_ZZ(Ideal,Ideal)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * "Tor_ZZ(Ideal,Module)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * "Tor_ZZ(Ideal,Ring)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * "Tor_ZZ(Module,Ideal)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * Tor_ZZ(Ring,Ideal) (missing documentation)
  * "truncate(ZZ,Ideal)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * variety(Ideal) (Varieties) -- the closed
    projective subvariety defined by an ideal
  * Vector % Ideal (missing documentation)
  * "versalEmbedding(Ideal)" -- see versalEmbedding (ReesAlgebra),
    -- Compute a versal embedding
  * "whichGm(Ideal)" -- see whichGm (ReesAlgebra), -- Largest Gm
    satisfied by an ideal
  * ZZ == Ideal (missing documentation)

For the programmer
==================

The object Ideal, is a type, with ancestor classes
HashTable < Thing.

ideal -- make an ideal
**********************

Ways to use ideal:
==================

  * ideal(List) -- make an ideal
  * "ideal(Sequence)" -- see ideal(List), -- make an
    ideal
  * ideal(Matrix) -- make an ideal
  * ideal(Module) -- converts a module to an ideal
  * ideal(MonomialIdeal) -- converts a
    monomial ideal to an ideal
  * "ideal(QuotientRing)" -- see ideal(Ring), -- returns
    the defining ideal
  * ideal(Ring) -- returns the defining ideal
  * "ideal(Number)" -- see ideal(RingElement), --
    make an ideal
  * ideal(RingElement) -- make an ideal
  * ideal(String) (Classic) -- make an ideal using
    classic Macaulay syntax
  * ideal(Variety) (Varieties) -- returns the
    defining ideal

For the programmer
==================

The object ideal, is a method function with a single argument.

Ideal * Ideal -- product of ideals
**********************************

Synopsis
========

  * Operator: *,
  * Usage:
        I * J
  * Inputs:
      * I
      * J, in the same ring as I
  * Outputs:
      * the product of the two ideals I and J

Description
===========

+---------------------------------------------+
|i1 : R = QQ[t][a..d];                        |
+---------------------------------------------+
|i2 : I = ideal(a,(t+1)*c) * ideal(a^2,b^2)   |
|                                             |
|             3     2          2           2  |
|o2 = ideal (a , a*b , (t + 1)a c, (t + 1)b c)|
|                                             |
|o2 : Ideal of R                              |
+---------------------------------------------+
The generators produced are not generally minimal.  Use trim(Ideal),
or mingens(Ideal), to find a smaller
generating set.

See also
========

  * ideals

Ways to use this method:
========================

  * Ideal * Ideal -- product of ideals

Ideal + Ideal -- sum of ideals
******************************

Synopsis
========

  * Operator: +,
  * Usage:
        I + J
  * Inputs:
      * I
      * J, in the same ring as I
  * Outputs:
      * the sum of the two ideals I and J

Description
===========

+------------------------------------------+
|i1 : R = QQ[t][a..d];                     |
+------------------------------------------+
|i2 : I = ideal(a,(t+1)*c) + ideal(a^2,b^2)|
|                                          |
|                          2   2           |
|o2 = ideal (a, (t + 1)c, a , b )          |
|                                          |
|o2 : Ideal of R                           |
+------------------------------------------+
The generators produced are not generally minimal.  Use trim(Ideal),
or mingens(Ideal), to find a smaller
generating set.
+----------------------------+
|i3 : trim I                 |
|                            |
|                          2 |
|o3 = ideal (a, (t + 1)c, b )|
|                            |
|o3 : Ideal of R             |
+----------------------------+

See also
========

  * ideals

Ways to use this method:
========================

  * Ideal + Ideal -- sum of ideals

Ideal / Function -- apply a function to generators of an ideal
**************************************************************

Synopsis
========

  * Operator: /,
  * Usage:
        I/f
        f\I
  * Inputs:
      * I
      * f
  * Outputs:
      * a list, obtained by applying the function f to each
        generator of I

Description
===========

The operator /, is left associative, which means that w / f / g is
interpreted as (w / f) / g. The operator \, is right associative, so g
\ f \ w is interpreted as g \ (f \ w). Both operators have parsing precedence
lower than that of @@, which means that the previous two expressions
are equivalent to w / g @@ f and g @@ f \ w, respectively. See precedence of operators.

+-----------------------------------------------------------------------+
|i1 : R = ZZ[a..d];                                                     |
+-----------------------------------------------------------------------+
|i2 : I = ideal"abc-d3,ab-d-1,a2+b2+c3-14d-3"                           |
|                                                                       |
|                     3                3    2    2                      |
|o2 = ideal (a*b*c - d , a*b - d - 1, c  + a  + b  - 14d - 3)           |
|                                                                       |
|o2 : Ideal of R                                                        |
+-----------------------------------------------------------------------+
|i3 : I/size                                                            |
|                                                                       |
|o3 = {2, 3, 5}                                                         |
|                                                                       |
|o3 : List                                                              |
+-----------------------------------------------------------------------+
|i4 : (f->f+a*b-1)\I                                                    |
|                                                                       |
|               3                           3    2          2           |
|o4 = {a*b*c - d  + a*b - 1, 2a*b - d - 2, c  + a  + a*b + b  - 14d - 4}|
|                                                                       |
|o4 : List                                                              |
+-----------------------------------------------------------------------+
|i5 : I/leadTerm/support/set//sum                                       |
|                                                                       |
|o5 = set {c, b, a}                                                     |
|                                                                       |
|o5 : Set                                                               |
+-----------------------------------------------------------------------+

Ways to use this method:
========================

  * Ideal / Function -- apply a function to generators
    of an ideal

Ideal / Ideal -- quotient module
********************************

Synopsis
========

  * Operator: /,
  * Usage:
        I/J
  * Inputs:
      * I
      * J, in the same ring as I
  * Outputs:
      * a module, The quotient module (I+J)/J

Description
===========

+---------------------------------------------------+
|i1 : R = QQ[a,b,c]                                 |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : I = ideal vars R                              |
|                                                   |
|o2 = ideal (a, b, c)                               |
|                                                   |
|o2 : Ideal of R                                    |
+---------------------------------------------------+
|i3 : M = I / I^2                                   |
|                                                   |
|o3 = subquotient (| a b c |, | a2 ab ac b2 bc c2 |)|
|                                                   |
|                               1                   |
|o3 : R-module, subquotient of R                    |
+---------------------------------------------------+
There is a difference between typing I/J and (I+J)/J in Macaulay2, although
conceptually they are the same module. The former has as its generating set the
generators of I, while the latter has as its (redundant) generators the
generators of I and J.  Generally, the former method is preferable.
+---------------------------------------------------------------------+
|i4 : gens M                                                          |
|                                                                     |
|o4 = | a b c |                                                       |
|                                                                     |
|             1      3                                                |
|o4 : Matrix R  <-- R                                                 |
+---------------------------------------------------------------------+
|i5 : N = (I + I^2)/I^2                                               |
|                                                                     |
|o5 = subquotient (| a b c a2 ab ac b2 bc c2 |, | a2 ab ac b2 bc c2 |)|
|                                                                     |
|                               1                                     |
|o5 : R-module, subquotient of R                                      |
+---------------------------------------------------------------------+
|i6 : gens N                                                          |
|                                                                     |
|o6 = | a b c a2 ab ac b2 bc c2 |                                     |
|                                                                     |
|             1      9                                                |
|o6 : Matrix R  <-- R                                                 |
+---------------------------------------------------------------------+

See also
========

  * subquotient modules -- the way Macaulay2
    represents modules
  * generators -- provide matrix or list of generators

Ways to use this method:
========================

  * Ideal / Ideal -- quotient module

Ideal ^ Array -- bracket power of an ideal
******************************************

Synopsis
========

  * Operator: ^,
  * Usage:
        I^e
  * Inputs:
      * I
      * e, array of positive integers
  * Outputs:
      * the ideal I^e

Description
===========

The bracket power of an ideal is defined to be the ideal generated by the image
of the generators under the ring homomorphism given by sending a variable to
the corresponding power. The array may either be a singleton, as follows:
+-------------------------------------+
|i1 : R = QQ[a..d];                   |
+-------------------------------------+
|i2 : I = ideal(a^2*b, a*b^2,c^3,d^5);|
|                                     |
|o2 : Ideal of R                      |
+-------------------------------------+
|i3 : I^[3]                           |
|                                     |
|             6 3   3 6   9   15      |
|o3 = ideal (a b , a b , c , d  )     |
|                                     |
|o3 : Ideal of R                      |
+-------------------------------------+
One may also give an array that is the same length as the number of variables
in the ring, as follows:
+---------------------------------+
|i4 : I^[2,3,4,5]                 |
|                                 |
|             4 3   2 6   12   25 |
|o4 = ideal (a b , a b , c  , d  )|
|                                 |
|o4 : Ideal of R                  |
+---------------------------------+
If your ring is a tower, then the bracket power will raise the outermost
variables to powers.
+----------------------+
|i5 : S = QQ[x,y];     |
+----------------------+
|i6 : T = S[z,w];      |
+----------------------+
|i7 : I = ideal gens T;|
|                      |
|o7 : Ideal of T       |
+----------------------+
|i8 : I^[3]            |
|                      |
|             3   3    |
|o8 = ideal (z , w )   |
|                      |
|o8 : Ideal of T       |
+----------------------+
|i9 : I^[2,3]          |
|                      |
|             2   3    |
|o9 = ideal (z , w )   |
|                      |
|o9 : Ideal of T       |
+----------------------+
No check is made to determine whether the function given by exponentiating the
generators is a ring homomorphism.  Of course, this only is an issue when
taking bracket powers of ideals in a quotient ring.  One important case where
the bracket power is useful is when studying Frobenius powers of ideals, which
corresponds to the image of the ideal under the Frobenius automorphism.
+---------------------------------------------+
|i10 : R = ZZ/5[a..d];                        |
+---------------------------------------------+
|i11 : I = minors(2,matrix {{a,b,c},{b,c,d}});|
|                                             |
|o11 : Ideal of R                             |
+---------------------------------------------+
|i12 : S = R/I;                               |
+---------------------------------------------+
|i13 : J = ideal vars S                       |
|                                             |
|o13 = ideal (a, b, c, d)                     |
|                                             |
|o13 : Ideal of S                             |
+---------------------------------------------+
|i14 : J^[5]                                  |
|                                             |
|              5   3          3   5           |
|o14 = ideal (a , a c*d, a*b*d , d )          |
|                                             |
|o14 : Ideal of S                             |
+---------------------------------------------+

See also
========

  * ideals

Ways to use this method:
========================

  * Ideal ^ Array -- bracket power of an ideal
  * "MonomialIdeal ^ Array"

Ideal ^ ZZ -- power of an ideal
*******************************

Synopsis
========

  * Operator: ^,
  * Usage:
        I^n
  * Inputs:
      * I
      * n, at least zero
  * Outputs:
      * the ideal I^n

Description
===========

+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..d];                                                           |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(a^2, b^2-c*d);                                                |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : I^3                                                                     |
|                                                                             |
|             6   4 2    4      2 4     2 2       2 2 2   6     4        2 2 2|
|o3 = ideal (a , a b  - a c*d, a b  - 2a b c*d + a c d , b  - 3b c*d + 3b c d |
|     ------------------------------------------------------------------------|
|        3 3                                                                  |
|     - c d )                                                                 |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
The generators produced are often not minimal.  Use trim(Ideal), or
mingens(Ideal), to find a smaller generating set.
+-----------------------------------------------------------------------------+
|i4 : trim I^3                                                                |
|                                                                             |
|             6     4        2 2 2    3 3   2 4     2 2       2 2 2   4 2     |
|o4 = ideal (b  - 3b c*d + 3b c d  - c d , a b  - 2a b c*d + a c d , a b  -   |
|     ------------------------------------------------------------------------|
|      4      6                                                               |
|     a c*d, a )                                                              |
|                                                                             |
|o4 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

See also
========

  * ideals

Ways to use this method:
========================

  * Ideal ^ ZZ -- power of an ideal
  * "MonomialIdeal ^ ZZ"

Ideal _* -- get the list of generators of an ideal
**************************************************

Synopsis
========

  * Operator: _*,
  * Usage:
        I_*
  * Inputs:
      * I
  * Outputs:
      * the list of generators of I

Description
===========

+--------------------------------------+
|i1 : R = QQ[a..c]                     |
|                                      |
|o1 = R                                |
|                                      |
|o1 : PolynomialRing                   |
+--------------------------------------+
|i2 : I = ideal (a,b,c);               |
|                                      |
|o2 : Ideal of R                       |
+--------------------------------------+
|i3 : J = I^2                          |
|                                      |
|             2             2        2 |
|o3 = ideal (a , a*b, a*c, b , b*c, c )|
|                                      |
|o3 : Ideal of R                       |
+--------------------------------------+
|i4 : J_*                              |
|                                      |
|       2             2        2       |
|o4 = {a , a*b, a*c, b , b*c, c }      |
|                                      |
|o4 : List                             |
+--------------------------------------+

Ways to use this method:
========================

  * Ideal _* -- get the list of generators of an ideal

ideal(List) -- make an ideal
****************************

Synopsis
========

  * Function: ideal,
  * Usage:
        ideal L
  * Inputs:
      * L, or a sequence, of ring elements,
  * Outputs:
      * an ideal, which is generated by the list, or
        sequence, of ring elements,

Description
===========

+--------------------------------------------+
|i1 : R = ZZ/101[w,x,y,z];                   |
+--------------------------------------------+
|i2 : ideal{x^2-w*y, x*y-w*z, x*z-y^2}       |
|                                            |
|             2                      2       |
|o2 = ideal (x  - w*y, x*y - w*z, - y  + x*z)|
|                                            |
|o2 : Ideal of R                             |
+--------------------------------------------+
|i3 : ideal(y^2-x*z,x^2*y-z^2,x^3-y*z)       |
|                                            |
|             2         2     2   3          |
|o3 = ideal (y  - x*z, x y - z , x  - y*z)   |
|                                            |
|o3 : Ideal of R                             |
+--------------------------------------------+
|i4 : E = ZZ/2[x,y, SkewCommutative => true];|
+--------------------------------------------+
|i5 : ideal(x^2,x*y)                         |
|                                            |
|o5 = ideal (0, x*y)                         |
|                                            |
|o5 : Ideal of E                             |
+--------------------------------------------+
|i6 : W = QQ[x,dx, WeylAlgebra => {x => dx}];|
+--------------------------------------------+
|i7 : ideal(dx*x+x*dx)                       |
|                                            |
|o7 = ideal(2x*dx + 1)                       |
|                                            |
|o7 : Ideal of W                             |
+--------------------------------------------+
|i8 : I = ideal(12,18)                       |
|                                            |
|o8 = ideal (12, 18)                         |
|                                            |
|o8 : Ideal of ZZ                            |
+--------------------------------------------+
|i9 : mingens I                              |
|                                            |
|o9 = | 6 |                                  |
|                                            |
|              1       1                     |
|o9 : Matrix ZZ  <-- ZZ                      |
+--------------------------------------------+

An empty list or sequence of generators will yield an ideal of ZZ,
which can be promoted to another ring, if desired.

+-------------------+
|i10 : ideal ()     |
|                   |
|o10 = ideal ()     |
|                   |
|o10 : Ideal of ZZ  |
+-------------------+
|i11 : promote(oo,R)|
|                   |
|o11 = ideal ()     |
|                   |
|o11 : Ideal of R   |
+-------------------+

See also
========

  * Ideal -- the class of all ideals
  * PolynomialRing -- the class of all ordered monoid
    rings

Ways to use this method:
========================

  * ideal(List) -- make an ideal
  * "ideal(Sequence)"

ideal(Matrix) -- make an ideal
******************************

Synopsis
========

  * Function: ideal,
  * Usage:
        ideal M
  * Inputs:
      * M, whose entries, are ring elements,
  * Outputs:
      * an ideal, which is generated by all the entries in M

Description
===========

+--------------------------------------------------------------------------+
|i1 : R = ZZ/7[w,x,y,z];                                                   |
+--------------------------------------------------------------------------+
|i2 : f = vars R                                                           |
|                                                                          |
|o2 = | w x y z |                                                          |
|                                                                          |
|             1      4                                                     |
|o2 : Matrix R  <-- R                                                      |
+--------------------------------------------------------------------------+
|i3 : ideal f                                                              |
|                                                                          |
|o3 = ideal (w, x, y, z)                                                   |
|                                                                          |
|o3 : Ideal of R                                                           |
+--------------------------------------------------------------------------+
|i4 : g = matrix{{x^2-w*y, x*y-w*z, x*z-y^2},{y^2-x*z,x^2*y-z^2,x^3-y*z}}  |
|                                                                          |
|o4 = | x2-wy xy-wz  -y2+xz |                                              |
|     | y2-xz x2y-z2 x3-yz  |                                              |
|                                                                          |
|             2      3                                                     |
|o4 : Matrix R  <-- R                                                      |
+--------------------------------------------------------------------------+
|i5 : ideal g                                                              |
|                                                                          |
|             2         2                    2     2     2         3       |
|o5 = ideal (x  - w*y, y  - x*z, x*y - w*z, x y - z , - y  + x*z, x  - y*z)|
|                                                                          |
|o5 : Ideal of R                                                           |
+--------------------------------------------------------------------------+

The functions minors, pfaffians,
and fitting ideal, are typically more useful
methods of creating an ideal, from a matrix.

See also
========

  * entries -- lists the entries of a matrix
  * flatten -- flatten a nested list or a matrix

Ways to use this method:
========================

  * ideal(Matrix) -- make an ideal

ideal(Module) -- converts a module to an ideal
**********************************************

Synopsis
========

  * Function: ideal,
  * Usage:
        ideal M
  * Inputs:
      * M, which is a submodule of a free module of rank 1
  * Outputs:
      * an ideal, given by the generators of M

Description
===========

+----------------------------------------------------------+
|i1 : R = QQ[w,x,y,z];                                     |
+----------------------------------------------------------+
|i2 : f = map(R^1,R^3, matrix{{x^2-w*y, x*y-w*z, x*z-y^2}})|
|                                                          |
|o2 = | x2-wy xy-wz -y2+xz |                               |
|                                                          |
|             1      3                                     |
|o2 : Matrix R  <-- R                                      |
+----------------------------------------------------------+
|i3 : image f                                              |
|                                                          |
|o3 = image | x2-wy xy-wz -y2+xz |                         |
|                                                          |
|                             1                            |
|o3 : R-module, submodule of R                             |
+----------------------------------------------------------+
|i4 : ideal image f                                        |
|                                                          |
|             2                      2                     |
|o4 = ideal (x  - w*y, x*y - w*z, - y  + x*z)              |
|                                                          |
|o4 : Ideal of R                                           |
+----------------------------------------------------------+

See also
========

  * generators(Module) -- the generator matrix
    of a module
  * ambient -- ambient free module of a subquotient, or ambient
    ring
  * isSubmodule -- whether a module is evidently a
    submodule of a free module
  * isIdeal -- whether something is an ideal

Ways to use this method:
========================

  * ideal(Module) -- converts a module to an ideal

ideal(MonomialIdeal) -- converts a monomial ideal to an ideal
*************************************************************

Synopsis
========

  * Function: ideal,
  * Usage:
        ideal I
  * Inputs:
      * I
  * Outputs:
      * an ideal, which is generated by the monomials in I

Description
===========

+-------------------------------------------+
|i1 : R = QQ[x,y,z];                        |
+-------------------------------------------+
|i2 : I = monomialIdeal(x*y^2, x^2*z, y^2*z)|
|                                           |
|                       2   2    2          |
|o2 = monomialIdeal (x*y , x z, y z)        |
|                                           |
|o2 : MonomialIdeal of R                    |
+-------------------------------------------+
|i3 : ideal I                               |
|                                           |
|               2   2    2                  |
|o3 = ideal (x*y , x z, y z)                |
|                                           |
|o3 : Ideal of R                            |
+-------------------------------------------+

Most operations between ideals, and monomial ideals,
automatically perform the necessary conversions, so one rarely
needs to apply the function ideal to a monomial ideal.
+-------------------------------------------------------------------------+
|i4 : I * ideal I                                                         |
|                                                                         |
|             2 4   3 2      4    3 2    4 2   2 2 2     4    2 2 2   4 2 |
|o4 = ideal (x y , x y z, x*y z, x y z, x z , x y z , x*y z, x y z , y z )|
|                                                                         |
|o4 : Ideal of R                                                          |
+-------------------------------------------------------------------------+
|i5 : I + ideal(x*y+y*z)                                                  |
|                                                                         |
|               2   2    2                                                |
|o5 = ideal (x*y , x z, y z, x*y + y*z)                                   |
|                                                                         |
|o5 : Ideal of R                                                          |
+-------------------------------------------------------------------------+

See also
========

  * monomialIdeal -- make a monomial ideal
  * generators(Ideal) -- the generator matrix of
    an ideal

Ways to use this method:
========================

  * ideal(MonomialIdeal) -- converts a
    monomial ideal to an ideal

ideal(Ring) -- returns the defining ideal
*****************************************

Synopsis
========

  * Function: ideal,
  * Usage:
        ideal R
  * Inputs:
      * R
  * Outputs:
      * an ideal, which is the defining ideal of R

Description
===========

A quotient ring, is a the quotient of its ambient,
see ring, by its defining ideal.  Other rings have no ambient
ring, and the defining ideal is its zero ideal.
+-----------------------------------------------------------------------------+
|i1 : S = ZZ/2[x,y,z];                                                        |
+-----------------------------------------------------------------------------+
|i2 : ideal S                                                                 |
|                                                                             |
|o2 = ideal ()                                                                |
|                                                                             |
|o2 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i3 : R = S/(y^2-x*z,x^2*y-z^2)                                               |
|                                                                             |
|o3 = R                                                                       |
|                                                                             |
|o3 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i4 : ideal R                                                                 |
|                                                                             |
|             2         2     2                                               |
|o4 = ideal (y  + x*z, x y + z )                                              |
|                                                                             |
|o4 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i5 : T = R/(x^3-y*z)                                                         |
|                                                                             |
|o5 = T                                                                       |
|                                                                             |
|o5 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i6 : ideal T                                                                 |
|                                                                             |
|            3                                                                |
|o6 = ideal(x  + y*z)                                                         |
|                                                                             |
|o6 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i7 : ambient T                                                               |
|                                                                             |
|o7 = R                                                                       |
|                                                                             |
|o7 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i8 : sing = singularLocus T                                                  |
|                                                                             |
|o8 = sing                                                                    |
|                                                                             |
|o8 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i9 : ideal sing                                                              |
|                                                                             |
|             3         2         2     2   2   3              4   2    2     |
|o9 = ideal (x  + y*z, y  + x*z, x y + z , z , x  + y*z, x*z, x , x y, x z,   |
|     ------------------------------------------------------------------------|
|      3                                                                      |
|     x )                                                                     |
|                                                                             |
|o9 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i10 : ambient sing                                                           |
|                                                                             |
|o10 = S                                                                      |
|                                                                             |
|o10 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * ambient -- ambient free module of a subquotient, or ambient
    ring
  * singularLocus -- singular locus

Ways to use this method:
========================

  * "ideal(QuotientRing)"
  * ideal(Ring) -- returns the defining ideal

ideal(RingElement) -- make an ideal
***********************************

Synopsis
========

  * Function: ideal,
  * Usage:
        ideal r
  * Inputs:
      * r
  * Outputs:
      * an ideal, which is generated by the ring element,
        r

Description
===========

+-------------------+
|i1 : ideal 7       |
|                   |
|o1 = ideal 7       |
|                   |
|o1 : Ideal of ZZ   |
+-------------------+
|i2 : R = ZZ/2[x,y];|
+-------------------+
|i3 : f = x^2+y^2;  |
+-------------------+
|i4 : ideal f       |
|                   |
|            2    2 |
|o4 = ideal(x  + y )|
|                   |
|o4 : Ideal of R    |
+-------------------+

The zero ideal with one generator can be made:

+---------------+
|i5 : ideal 0_R |
|               |
|o5 = ideal 0   |
|               |
|o5 : Ideal of R|
+---------------+

Alternatively, the zero ideal with no generators can be made in one of these
ways:

+------------------------+
|i6 : ideal id_(R^0)     |
|                        |
|o6 = ideal ()           |
|                        |
|o6 : Ideal of R         |
+------------------------+
|i7 : promote(ideal(), R)|
|                        |
|o7 = ideal ()           |
|                        |
|o7 : Ideal of R         |
+------------------------+

See promote, id _ Module, and ideal(Sequence).

Ways to use this method:
========================

  * "ideal(Number)"
  * ideal(RingElement) -- make an ideal

identity -- the identity function
*********************************

Description
===========

identity x -- returns x.

This is the identity function.

For the programmer
==================

The object identity, is a compiled function.

if -- condition testing
***********************

Description
===========

if p then x else y computes p, which must yield the value true, or
false.  If true, then the value of x is provided, else the value
of y is provided.

if p then x computes p, which must yield the value true, or
false.  If true, then the value of x is provided, else null,
is provided.

For the programmer
==================

The object if, is a keyword.

ii -- the square root of -1
***************************

Synopsis
========

  * Usage:
        ii
  * Outputs:
      * a complex number, the square root of -1, converted to a
        numeric value of the correct precision, when necessary.

Description
===========

+--------------------------+
|i1 : ii                   |
|                          |
|o1 = ii                   |
|                          |
|o1 : Constant             |
+--------------------------+
|i2 : ii+1p100             |
|                          |
|o2 = 1+ii                 |
|                          |
|o2 : CC (of precision 100)|
+--------------------------+
|i3 : numeric ii           |
|                          |
|o3 = ii                   |
|                          |
|o3 : CC (of precision 53) |
+--------------------------+
|i4 : numeric_100 ii       |
|                          |
|o4 = ii                   |
|                          |
|o4 : CC (of precision 100)|
+--------------------------+
Here is the simplest way to convert ii to a numeric value:
+-------------------------+
|i5 : +ii                 |
|                         |
|o5 = ii                  |
|                         |
|o5 : CC (of precision 53)|
+-------------------------+

See also
========

  * numeric -- convert to floating point

For the programmer
==================

The object ii, is an instance of the type Constant.

image -- image of a map
***********************

Description
===========

image h -- yields the image of the homomorphism h.

The result will be a submodule of the target of h

If h is a ring element, it is interpreted as a one by one matrix.

Ways to use image:
==================

  * "image(ChainComplexMap)"
  * "image(GradedModuleMap)"
  * "image(Matrix)"
  * "image(RingElement)"
  * image(SheafMap) (missing documentation)

For the programmer
==================

The object image, is a method function.

imaginaryPart -- imaginary part
*******************************

Synopsis
========

  * Usage:
        imaginaryPart z
  * Inputs:
      * z, an integer, rational, real or complex number
  * Outputs:
      * the imaginary part of the complex number z.

Description
===========

+----------------------------+
|i1 : imaginaryPart(3/4)     |
|                            |
|o1 = 0                      |
+----------------------------+
|i2 : imaginaryPart(1.5+2*ii)|
|                            |
|o2 = 2                      |
|                            |
|o2 : RR (of precision 53)   |
+----------------------------+

See also
========

  * CC -- the class of all complex numbers
  * realPart -- real part

Ways to use imaginaryPart:
==========================

  * "imaginaryPart(InexactNumber)"
  * "imaginaryPart(Number)"
  * "imaginaryPart(QQ)"
  * "imaginaryPart(ZZ)"

For the programmer
==================

The object imaginaryPart, is a method function.

ImmutableType -- the class of immutable types
*********************************************

Description
===========

All types are implemented as hash tables.  Most types are mutable, so that
additional methods for handling their instances can be added at any time.
However, if a type has an ancestor where the methods can be stored, then
mutability is not needed.

When a type is used to represent a mathematical object, then immutability is
desirable, in order to make the strict equality operator work on it.  For
example, a module M is a type, with its elements are its instances, but we
would like to be able to compare two modules quickly, and form sets of modules.
This is possible, because we have implemented modules as immutable types, and
we have put the methods for adding and subtracting elements of M into the class
Vector.
+------------------------------------------------------------------------+
|i1 : F = ZZ^3                                                           |
|                                                                        |
|       3                                                                |
|o1 = ZZ                                                                 |
|                                                                        |
|o1 : ZZ-module, free                                                    |
+------------------------------------------------------------------------+
|i2 : class F                                                            |
|                                                                        |
|o2 = Module                                                             |
|                                                                        |
|o2 : Type                                                               |
+------------------------------------------------------------------------+
|i3 : parent class F                                                     |
|                                                                        |
|o3 = ImmutableType                                                      |
|                                                                        |
|o3 : Type                                                               |
+------------------------------------------------------------------------+
|i4 : showStructure class F                                              |
|                                                                        |
|o4 = Thing : HashTable : ImmutableType : Module                         |
|                                                                        |
|o4 : Descent                                                            |
+------------------------------------------------------------------------+
|i5 : showStructure F                                                    |
|                                                                        |
|                                    3                                   |
|o5 = Thing : BasicList : Vector : ZZ                                    |
|                                                                        |
|o5 : Descent                                                            |
+------------------------------------------------------------------------+
|i6 : v = F_0 + 3*F_2                                                    |
|                                                                        |
|o6 = | 1 |                                                              |
|     | 0 |                                                              |
|     | 3 |                                                              |
|                                                                        |
|       3                                                                |
|o6 : ZZ                                                                 |
+------------------------------------------------------------------------+
|i7 : F === ZZ^3                                                         |
|                                                                        |
|o7 = true                                                               |
+------------------------------------------------------------------------+
|i8 : set (ZZ^3, ZZ^2, ZZ^3)                                             |
|                                                                        |
|            2    3                                                      |
|o8 = set {ZZ , ZZ }                                                     |
|                                                                        |
|o8 : Set                                                                |
+------------------------------------------------------------------------+
|i9 : peek F                                                             |
|                                                                        |
|o9 = Module of Vector{cache => CacheTable{...2...}                     }|
|                      numgens => 3                                      |
|                      RawFreeModule => free(rank 3 degrees = {1, 1, 1}) |
|                      ring => ZZ                                        |
+------------------------------------------------------------------------+
Another advantage of immutability of modules is that there is no particular
reason, aside from efficiency, to avoid creating a given module multiple times,
as one copy of the module is as good as another.
+---------------------+
|i10 : ZZ^3_0 + ZZ^3_2|
|                     |
|o10 = | 1 |          |
|      | 0 |          |
|      | 1 |          |
|                     |
|        3            |
|o10 : ZZ             |
+---------------------+

See also
========

  * showStructure -- display parent structure
  * parent -- parent type of an object
  * class -- class of an object

Types of immutable type:
========================

  * Module -- the class of all modules

Methods that use an immutable type:
===================================

  * "ofClass(ImmutableType)" -- see ofClass, -- English phrases
    for types

For the programmer
==================

The object ImmutableType, is a type, with
ancestor classes HashTable, < Thing.

in -- a keyword used in for-loops
*********************************

See also
========

  * for -- for loops

For the programmer
==================

The object in, is a keyword.

incomparable -- a result indicating incomparability
***************************************************

Description
===========

incomparable a symbol that may be returned by ?, when the two things
being compared are incomparable.

For the programmer
==================

The object incomparable, is a symbol.

independentSets -- some size-maximal independent subsets of variables modulo an ideal
*************************************************************************************

Synopsis
========

  * Usage:
        independentSets J
  * Inputs:
      * J, an ideal, or a monomial ideal,
  * Optional inputs,:
      * Limit => an integer, default value infinity, the maximum
        number of independent sets to be found
  * Outputs:
      * a list,  of products of variables.  The support of any one
        of these products is a maximal independent subset of variables modulo J

Description
===========

An independent set of variables of an ideal J in a polynomial ring R is a set
of variables that are algebraically independent modulo J (i.e. there is no
polynomial in J involving only these sets of variables.

If the Krull dimension of R/J is d, then a maximal independent set is an
independent set having size d.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..h];                                                           |
+-----------------------------------------------------------------------------+
|i2 : I = minors(2,genericMatrix(R,a,2,4))                                    |
|                                                                             |
|o2 = ideal (- b*c + a*d, - b*e + a*f, - d*e + c*f, - b*g + a*h, - d*g + c*h, |
|     ------------------------------------------------------------------------|
|     - f*g + e*h)                                                            |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : inI = ideal leadTerm I                                                  |
|                                                                             |
|o3 = ideal (f*g, d*g, b*g, d*e, b*e, b*c)                                    |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : independentSets I                                                       |
|                                                                             |
|o4 = {a*b*d*f*h, a*c*d*f*h, a*c*e*f*h, a*c*e*g*h}                            |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : independentSets inI                                                     |
|                                                                             |
|o5 = {a*b*d*f*h, a*c*d*f*h, a*c*e*f*h, a*c*e*g*h}                            |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

The independent sets returned correspond one for one with the minimal primes of
smallest codimension of the ideal of lead terms of J.
+-----------------------------------------------------------------------------+
|i6 : I = ideal"abc,bcd,cde,adf,cgh,b3f,a3g"                                  |
|                                                                             |
|                                                3    3                       |
|o6 = ideal (a*b*c, b*c*d, c*d*e, a*d*f, c*g*h, b f, a g)                     |
|                                                                             |
|o6 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i7 : minimalPrimes I                                                         |
|                                                                             |
|o7 = {ideal (c, b, a), ideal (f, c, a), ideal (g, d, b), ideal (g, e, b, a), |
|     ------------------------------------------------------------------------|
|     ideal (g, f, c), ideal (g, f, d, a), ideal (g, f, e, b), ideal (h, d, b,|
|     ------------------------------------------------------------------------|
|     a), ideal (h, e, b, a), ideal (h, f, d, a)}                             |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : independentSets I                                                       |
|                                                                             |
|o8 = {a*b*d*e*h, a*c*e*f*h, b*d*e*g*h, d*e*f*g*h}                            |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
The optional Limit argument is useful if you need only one, or several such
independent sets.
+-------------------------------------+
|i9 : L = independentSets(I, Limit=>1)|
|                                     |
|o9 = {a*b*d*e*h}                     |
|                                     |
|o9 : List                            |
+-------------------------------------+

Often, you want the list of the variables in a maximal independent set, or the
list of those not in the set.
+------------------------------------------------+
|i10 : support L_0                               |
|                                                |
|o10 = {a, b, d, e, h}                           |
|                                                |
|o10 : List                                      |
+------------------------------------------------+
|i11 : rsort toList(set gens R - set support L_0)|
|                                                |
|o11 = {c, f, g}                                 |
|                                                |
|o11 : List                                      |
+------------------------------------------------+

This function is useful as a subroutine to primary decomposition algorithms.

See also
========

  * PrimaryDecomposition -- primary
    decomposition and associated primes routines for ideals and modules
  * minimalPrimes (MinimalPrimes) -- minimal primes of an
    ideal
  * support -- list of variables occurring in a polynomial or
    matrix
  * rsort -- sort a list or matrix in reverse order

Ways to use independentSets:
============================

  * "independentSets(Ideal)"
  * "independentSets(MonomialIdeal)"

For the programmer
==================

The object independentSets, is a method function with options.

indeterminate -- an indeterminate number
****************************************

Description
===========

indeterminate -- a representation of an indeterminate number, such as might
result from multiplying 0 by infinity.

For the programmer
==================

The object indeterminate, is an indeterminate number.

IndeterminateNumber -- the class of all indeterminate numbers
*************************************************************

Description
===========

Indeterminate numbers result, for example, from multiplying 0 by infinity.
There is only one instance of this class.

Methods that use an indeterminate number:
=========================================

  * "numeric(IndeterminateNumber)" -- see numeric, -- convert to
    floating point
  * "numeric(ZZ,IndeterminateNumber)" -- see numeric, -- convert
    to floating point

Protected objects of class IndeterminateNumber:
===============================================

  * indeterminate -- an indeterminate number

For the programmer
==================

The object IndeterminateNumber, is a type,
with ancestor classes Number, < Thing.

index -- numeric index of a ring variable
*****************************************

Synopsis
========

  * Usage:
        index v
  * Inputs:
      * v, a ring element,
  * Outputs:
      * an integer, the integer index, starting at 0, of v, if it is
        a variable. If v is not a variable, then null, is returned

Description
===========

Variables are indexed in the following way: the first variable has index 0, the
second index 1, and so on, until n-1, where n is the number of generators of R,
the ring of v.  Then, if the coefficient ring is a polynomial ring, those
variables are numbered starting at n, and so on.
+-----------------------+
|i1 : R = ZZ/101[a..d,t]|
|                       |
|o1 = R                 |
|                       |
|o1 : PolynomialRing    |
+-----------------------+
|i2 : index a           |
|                       |
|o2 = 0                 |
+-----------------------+
|i3 : index t           |
|                       |
|o3 = 4                 |
+-----------------------+
+---------------------------------------------+
|i4 : A = ZZ[a..d]; B = A[r,s,t]; C = B[x,y,z]|
|                                             |
|o6 = C                                       |
|                                             |
|o6 : PolynomialRing                          |
+---------------------------------------------+
|i7 : index x                                 |
|                                             |
|o7 = 0                                       |
+---------------------------------------------+
|i8 : index z                                 |
|                                             |
|o8 = 2                                       |
+---------------------------------------------+
|i9 : index r                                 |
|                                             |
|o9 = 0                                       |
+---------------------------------------------+
Notice that r is an element of B, and so indices are taken from that ring. If
we consider r as an element of C, we get a different answer.  Variables of
coefficient rings of coefficient rings have an index too.
+------------------+
|i10 : index(r*1_C)|
|                  |
|o10 = 3           |
+------------------+
|i11 : index(b*1_C)|
|                  |
|o11 = 7           |
+------------------+

The symbol index is also as a key used in Monoids, to store a
table that is used to map generator names to the position of the generator in
the list of generators.

See also
========

  * indices -- indices of a polynomial; also components for a
    direct sum
  * support -- list of variables occurring in a polynomial or
    matrix
  * Ring _ ZZ -- get a ring variable by index

Ways to use index:
==================

  * "index(RingElement)"

For the programmer
==================

The object index, is a method function.

indexComponents -- specify keys for components of a direct sum
**************************************************************

Description
===========

indexComponents -- a symbol used as a key in a direct sum under which to store
a hash table in which to register preferred keys used to index the components
of the direct sum.

See also
========

  * directSum -- direct sum of modules or maps
  * components -- list the components of a direct sum
  * indices -- indices of a polynomial; also components for a
    direct sum

For the programmer
==================

The object indexComponents, is a symbol.

IndexedVariable -- the class of all indexed variables
*****************************************************

Description
===========

Indexed variables provide the possibility of producing polynomial rings R[x_0,
x_1, ..., x_(n-1)] in n variables, where n is not known in advance.  If x is an
symbol, and i is an integer, then x_i produces an indexed variable. After this
has been done, an assignment x_i=v will assign another value to it.  A new
sequence of indexed variables of length n assigned to the symbol x can be
produced with x_1 .. x_n and that sequence can be used in constructing a
polynomial ring.
+------------------------------+
|i1 : ZZ/101[t_0 .. t_4]       |
|                              |
|      ZZ                      |
|o1 = ---[t ..t ]              |
|     101  0   4               |
|                              |
|o1 : PolynomialRing           |
+------------------------------+
|i2 : (t_0 -  2*t_1)^3         |
|                              |
|      3     2          2     3|
|o2 = t  - 6t t  + 12t t  - 8t |
|      0     0 1      0 1     1|
|                              |
|      ZZ                      |
|o2 : ---[t ..t ]              |
|     101  0   4               |
+------------------------------+
Warning: the values of the indexed variables t_i are stored in a global
location, behind the scenes, so may not get garbage collected, even if t is a
local variable.

Functions and methods returning an indexed variable:
====================================================

  * MonoidElement _ Thing (missing documentation)
  * RingElement _ Thing (missing documentation)

Methods that use an indexed variable:
=====================================

  * "IndexedVariable <- Thing" -- see <-, -- assignment with left
    side evaluated
  * "IndexedVariable ? IndexedVariable" -- see ?, -- comparison
    operator
  * "Symbol ? IndexedVariable" -- see ?, -- comparison operator
  * "baseName(IndexedVariable)" -- see baseName, -- the base
    name of a generator
  * IndexedVariable .. IndexedVariable
    -- sequences of consecutive indexed variables
  * IndexedVariable ..< IndexedVariable
    -- sequences of consecutive indexed variables
  * IndexedVariable _ Ring -- get a ring
    variable by name
  * lift(IndexedVariable,type of MonoidElement) (missing documentation)
  * promote(IndexedVariable,type of RingElement) (missing documentation)
  * value(IndexedVariable) -- retrieve the
    value of an indexed variable

For the programmer
==================

The object IndexedVariable, is a type, with
ancestor classes BasicList, < Thing.

IndexedVariable .. IndexedVariable -- sequences of consecutive indexed variables
********************************************************************************

Synopsis
========

  * Operator: ..,
  * Usage:
        s .. t
  * Inputs:
      * s
      * t
  * Outputs:
      * the sequence of indexed variables with the same base and with
        consecutive subscripts, inclusive

Description
===========

+----------------------------------------------+
|i1 : x_1                                      |
|                                              |
|o1 = x                                        |
|      1                                       |
|                                              |
|o1 : IndexedVariable                          |
+----------------------------------------------+
|i2 : x_1 .. x_10                              |
|                                              |
|o2 = (x , x , x , x , x , x , x , x , x , x  )|
|       1   2   3   4   5   6   7   8   9   10 |
|                                              |
|o2 : Sequence                                 |
+----------------------------------------------+
|i3 : x_(a,1) .. x_(b,3)                       |
|                                              |
|o3 = (x   , x   , x   , x   , x   , x   )     |
|       a,1   a,2   a,3   b,1   b,2   b,3      |
|                                              |
|o3 : Sequence                                 |
+----------------------------------------------+

Ways to use this method:
========================

  * IndexedVariable .. IndexedVariable
    -- sequences of consecutive indexed variables

IndexedVariable ..< IndexedVariable -- sequences of consecutive indexed variables
*********************************************************************************

Synopsis
========

  * Operator: ..<,
  * Usage:
        s ..< t
  * Inputs:
      * s
      * t
  * Outputs:
      * the sequence of indexed variables with the same base and with
        consecutive subscripts, not including the endpoint

Description
===========

+-----------------------------------------------------+
|i1 : x_1                                             |
|                                                     |
|o1 = x                                               |
|      1                                              |
|                                                     |
|o1 : IndexedVariable                                 |
+-----------------------------------------------------+
|i2 : x_(a,1) ..< z_(c,3)                             |
|                                                     |
|o2 = (x   , x   , x   , x   , y   , y   , y   , y   )|
|       a,1   a,2   b,1   b,2   a,1   a,2   b,1   b,2 |
|                                                     |
|o2 : Sequence                                        |
+-----------------------------------------------------+

Ways to use this method:
========================

  * IndexedVariable ..< IndexedVariable
    -- sequences of consecutive indexed variables

IndexedVariable _ Ring -- get a ring variable by name
*****************************************************

Synopsis
========

  * Operator: _,
  * Usage:
        v_R
  * Inputs:
      * v
      * R
  * Outputs:
      * a ring element, the variable of R whose name is the
        indexed variable v

Description
===========

+---------------------+
|i1 : R = QQ[t_1..t_4]|
|                     |
|o1 = R               |
|                     |
|o1 : PolynomialRing  |
+---------------------+
|i2 : symbol t_1      |
|                     |
|o2 = t               |
|      1              |
|                     |
|o2 : IndexedVariable |
+---------------------+
|i3 : oo_R            |
|                     |
|o3 = t               |
|      1              |
|                     |
|o3 : R               |
+---------------------+

See also
========

  * Ring _ ZZ -- get a ring variable by index
  * String _ Ring -- get a ring variable by name

Ways to use this method:
========================

  * IndexedVariable _ Ring -- get a ring
    variable by name

IndexedVariableTable
********************

Description
===========

This class is used as part of the implementation of indexed variables.  Objects
of this class contain the values of the indexed variables that share the same
base.
+---------------------------------------+
|i1 : p_1 = a                           |
|                                       |
|o1 = a                                 |
|                                       |
|o1 : Symbol                            |
+---------------------------------------+
|i2 : p_2 = b                           |
|                                       |
|o2 = b                                 |
|                                       |
|o2 : Symbol                            |
+---------------------------------------+
|i3 : p                                 |
|                                       |
|o3 = p                                 |
|                                       |
|o3 : IndexedVariableTable              |
+---------------------------------------+
|i4 : peek p                            |
|                                       |
|o4 = IndexedVariableTable{1 => a      }|
|                          2 => b       |
|                          symbol$ => p |
+---------------------------------------+

See also
========

  * IndexedVariable -- the class of all indexed
    variables

Methods that use an indexed variable table:
===========================================

  * "baseName(IndexedVariableTable)" -- see baseName, -- the
    base name of a generator
  * "IndexedVariableTable _ Thing"
  * "IndexedVariableTable _ Thing = Thing"
  * IndexedVariableTable .. IndexedVariableTable (missing documentation)
  * IndexedVariableTable .. Thing (missing documentation)
  * IndexedVariableTable ..< IndexedVariableTable (missing documentation)
  * IndexedVariableTable ..< Thing (missing documentation)
  * Thing .. IndexedVariableTable (missing documentation)
  * Thing ..< IndexedVariableTable (missing documentation)

For the programmer
==================

The object IndexedVariableTable, is a type,
with ancestor classes MutableHashTable, <
HashTable < Thing.

indices -- indices of a polynomial; also components for a direct sum
********************************************************************

Description
===========

indices has two uses in Macaulay2: indices of a direct sum, or indices of a
polynomial.  Additionally, the symbol is used as a key in a direct sum under
which to store a list of the preferred  keys used to index the components of
the direct sum.

See also
========

  * directSum -- direct sum of modules or maps
  * components -- list the components of a direct sum
  * indexComponents -- specify keys for components of a
    direct sum
  * index -- numeric index of a ring variable
  * support -- list of variables occurring in a polynomial or
    matrix

Ways to use indices:
====================

  * indices(HashTable) (missing documentation)
  * "indices(Matrix)" -- see indices(RingElement),
    -- indices of variables occurring in a polynomial
  * indices(RingElement) -- indices of
    variables occurring in a polynomial

For the programmer
==================

The object indices, is a method function.

indices(RingElement) -- indices of variables occurring in a polynomial
**********************************************************************

Synopsis
========

  * Function: indices,
  * Usage:
        indices f
  * Inputs:
      * f, or a matrix,over a polynomial ring
  * Outputs:
      * a list, of integers, the indices of the variables
        occurring in the polynomial or matrix

Description
===========

The first variable in a polynomial ring has index 0, the second has index 1,
etc. This function returns a list (in ascending order) of the indices of all of
the variables that occur in f.
+---------------------------------+
|i1 : R = QQ[a..g]                |
|                                 |
|o1 = R                           |
|                                 |
|o1 : PolynomialRing              |
+---------------------------------+
|i2 : F = a^3+b^2*c+3*f^10*d-1+e-e|
|                                 |
|         10    3    2            |
|o2 = 3d*f   + a  + b c - 1       |
|                                 |
|o2 : R                           |
+---------------------------------+
|i3 : indices F                   |
|                                 |
|o3 = {0, 1, 2, 3, 5}             |
|                                 |
|o3 : List                        |
+---------------------------------+
|i4 : index a                     |
|                                 |
|o4 = 0                           |
+---------------------------------+
|i5 : support F                   |
|                                 |
|o5 = {a, b, c, d, f}             |
|                                 |
|o5 : List                        |
+---------------------------------+
The same works for matrices.
+-----------------------------------+
|i6 : M = matrix"a+b,c+e;2a-e,3b-c4"|
|                                   |
|o6 = | a+b  c+e    |               |
|     | 2a-e -c4+3b |               |
|                                   |
|             2      2              |
|o6 : Matrix R  <-- R               |
+-----------------------------------+
|i7 : indices M                     |
|                                   |
|o7 = {0, 1, 2, 4}                  |
|                                   |
|o7 : List                          |
+-----------------------------------+
|i8 : support M                     |
|                                   |
|o8 = {a, b, c, e}                  |
|                                   |
|o8 : List                          |
+-----------------------------------+
This use of indices, has no relationship with the use for
specifying parts of a direct sum

See also
========

  * index -- numeric index of a ring variable
  * support -- list of variables occurring in a polynomial or
    matrix
  * indices -- indices of a polynomial; also components for a
    direct sum
  * Ring _ ZZ -- get a ring variable by index

Ways to use this method:
========================

  * "indices(Matrix)"
  * indices(RingElement) -- indices of
    variables occurring in a polynomial

inducedMap -- compute an induced map
************************************

See also
========

  * inducesWellDefinedMap -- whether a map is
    well defined

Ways to use inducedMap:
=======================

  * inducedMap(CoherentSheaf,CoherentSheaf) (missing documentation)
  * "inducedMap(ChainComplex,ChainComplex)" -- see
    inducedMap(Module,Module), -- compute the
    map induced by the identity
  * inducedMap(Module,Module), --
    compute the map induced by the identity
  * inducedMap(Module,Module,Matrix)
    -- compute the induced map
  * "inducedMap(Module,Nothing,Matrix)" -- see
    inducedMap(Module,Module,Matrix),
    -- compute the induced map
  * "inducedMap(Nothing,Module,Matrix)" -- see
    inducedMap(Module,Module,Matrix),
    -- compute the induced map
  * "inducedMap(Nothing,Nothing,Matrix)" -- see
    inducedMap(Module,Module,Matrix),
    -- compute the induced map

For the programmer
==================

The object inducedMap, is a method function with options.

inducedMap(...,Degree=>...) -- specify the degree of a map
**********************************************************

Description
===========

Degree => n -- an option to inducedMap, that provides the
degree of the map produced.

Further information
===================

  * Default value: null
  * Function: inducedMap, -- compute an induced map
  * Option key: Degree, -- specify the degree of a map

Functions with optional argument named Degree:
==============================================

  * "basis(...,Degree=>...)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * cohomology(...,Degree=>...) (missing documentation)
  * "map(...,Degree=>...)" -- see Degree, -- specify the degree
    of a map
  * inducedMap(...,Degree=>...)
    -- specify the degree of a
    map
  * "matrix(...,Degree=>...)" -- see matrix(List), --
    create a matrix from a doubly-nested list of ring elements or matrices

inducedMap(...,Verify=>...) -- verify that a map is well-defined
****************************************************************

Description
===========

Verify => true -- an option for inducedMap, which requests
verification that the induced map produced is well defined.

Further information
===================

  * Default value: true,
  * Function: inducedMap, -- compute an induced map
  * Option key: Verify, -- an optional argument

Functions with optional argument named Verify:
==============================================

  * ^(Number,Ring,Verify=>...) (missing documentation)
  * "extend(...,Verify=>...)" -- see
    extend(ChainComplex,ChainComplex,Matrix),
    -- extend a module map to
    a chain map, if possible
  * inducedMap(...,Verify=>...)
    -- verify that a map is
    well-defined
  * "lift(...,Verify=>...)" -- see lift, -- lift to another ring

inducedMap(Module,Module) -- compute the map induced by the identity
********************************************************************

Synopsis
========

  * Function: inducedMap,
  * Usage:
        inducedMap(M,N)
  * Inputs:
      * M
      * N
  * Optional inputs,:
      * Degree, => ...,
        default value null, specify the degree of a map
      * Verify, => ...,
        default value true, verify that a map is well-defined
  * Outputs:
      * the homomorphism M <-- N induced by the identity.

Description
===========

The modules M and N must both be subquotient modules,
of the same ambient free module F. If M = M1/M2 and N = N1/N2, where
M1, M2, N1, N2 are all submodules of F, then return the map induced by F --> F.
If the optional argument Verify is given, check that the result defines a well
defined homomorphism.

In this example, we make the inclusion map between two submodules of R^3.  M is
defined by two elements and N is generated by one element in M
+-----------------------------------------------------+
|i1 : R = ZZ/32003[x,y,z];                            |
+-----------------------------------------------------+
|i2 : P = R^3;                                        |
+-----------------------------------------------------+
|i3 : M = image(x*P_{1}+y*P_{2} | z*P_{0})            |
|                                                     |
|o3 = image | 0 z |                                   |
|           | x 0 |                                   |
|           | y 0 |                                   |
|                                                     |
|                             3                       |
|o3 : R-module, submodule of R                        |
+-----------------------------------------------------+
|i4 : N = image(x^4*P_{1} + x^3*y*P_{2} + x*y*z*P_{0})|
|                                                     |
|o4 = image | xyz |                                   |
|           | x4  |                                   |
|           | x3y |                                   |
|                                                     |
|                             3                       |
|o4 : R-module, submodule of R                        |
+-----------------------------------------------------+
|i5 : h = inducedMap(M,N)                             |
|                                                     |
|o5 = | x3 |                                          |
|     | xy |                                          |
|                                                     |
|o5 : Matrix M <-- N                                  |
+-----------------------------------------------------+
|i6 : source h == N                                   |
|                                                     |
|o6 = true                                            |
+-----------------------------------------------------+
|i7 : target h == M                                   |
|                                                     |
|o7 = true                                            |
+-----------------------------------------------------+
|i8 : ambient M == ambient N                          |
|                                                     |
|o8 = true                                            |
+-----------------------------------------------------+

See also
========

  * inducesWellDefinedMap -- whether a map is
    well defined
  * subquotient -- make a subquotient module

Ways to use this method:
========================

  * "inducedMap(ChainComplex,ChainComplex)"
  * inducedMap(Module,Module), --
    compute the map induced by the identity

inducedMap(Module,Module,Matrix) -- compute the induced map
***********************************************************

Synopsis
========

  * Function: inducedMap,
  * Usage:
        inducedMap(M,N,f)
  * Inputs:
      * M
      * N
      * f, a homomorphism P <-- Q
  * Optional inputs,:
      * Degree, => ...,
        default value null, specify the degree of a map
      * Verify, => ...,
        default value true, verify that a map is well-defined
  * Outputs:
      * the homomorphism M <-- N induced by f.

Description
===========

The modules M and N must both be subquotient modules,
where M and P have the same ambient module, and N and Q have the same
ambient module. If the optional argument Verify is given, check that the result
defines a well defined homomorphism.

In this example, the module K2 is mapped via g into K1, and we construct the
induced map from K2 to K1.
+---------------------------------------------------------------+
|i1 : R = ZZ/32003[x,y,z]                                       |
|                                                               |
|o1 = R                                                         |
|                                                               |
|o1 : PolynomialRing                                            |
+---------------------------------------------------------------+
|i2 : g1 = matrix{{x,y,z}}                                      |
|                                                               |
|o2 = | x y z |                                                 |
|                                                               |
|             1      3                                          |
|o2 : Matrix R  <-- R                                           |
+---------------------------------------------------------------+
|i3 : g2 = matrix{{x^2,y^2,z^2}}                                |
|                                                               |
|o3 = | x2 y2 z2 |                                              |
|                                                               |
|             1      3                                          |
|o3 : Matrix R  <-- R                                           |
+---------------------------------------------------------------+
|i4 : K1 = ker g1                                               |
|                                                               |
|o4 = image {1} | -y 0  -z |                                    |
|           {1} | x  -z 0  |                                    |
|           {1} | 0  y  x  |                                    |
|                                                               |
|                             3                                 |
|o4 : R-module, submodule of R                                  |
+---------------------------------------------------------------+
|i5 : K2 = ker g2                                               |
|                                                               |
|o5 = image {2} | -y2 0   -z2 |                                 |
|           {2} | x2  -z2 0   |                                 |
|           {2} | 0   y2  x2  |                                 |
|                                                               |
|                             3                                 |
|o5 : R-module, submodule of R                                  |
+---------------------------------------------------------------+
|i6 : f = map(ambient K1, ambient K2, {{x,0,0},{0,y,0},{0,0,z}})|
|                                                               |
|o6 = {1} | x 0 0 |                                             |
|     {1} | 0 y 0 |                                             |
|     {1} | 0 0 z |                                             |
|                                                               |
|             3      3                                          |
|o6 : Matrix R  <-- R                                           |
+---------------------------------------------------------------+
|i7 : h = inducedMap(K1,K2,f)                                   |
|                                                               |
|o7 = {2} | xy 0  0  |                                          |
|     {2} | 0  yz 0  |                                          |
|     {2} | 0  0  xz |                                          |
|                                                               |
|o7 : Matrix K1 <-- K2                                          |
+---------------------------------------------------------------+
If we omit the first argument, then it is understood to be the target of f, and
if we omit the second argument, it is understood to be the source of f.
+-----------------------------------+
|i8 : h1 = inducedMap(target f,K2,f)|
|                                   |
|o8 = {1} | -xy2 0    -xz2 |        |
|     {1} | x2y  -yz2 0    |        |
|     {1} | 0    y2z  x2z  |        |
|                                   |
|             3                     |
|o8 : Matrix R  <-- K2              |
+-----------------------------------+
|i9 : h2 = inducedMap(,K2,f)        |
|                                   |
|o9 = {1} | -xy2 0    -xz2 |        |
|     {1} | x2y  -yz2 0    |        |
|     {1} | 0    y2z  x2z  |        |
|                                   |
|             3                     |
|o9 : Matrix R  <-- K2              |
+-----------------------------------+
|i10 : h1 == h2                     |
|                                   |
|o10 = true                         |
+-----------------------------------+
In this example, we cannot omit the second argument, since in that case the
resulting object is not a homomorphism.

See also
========

  * inducesWellDefinedMap -- whether a map is
    well defined
  * subquotient -- make a subquotient module

Ways to use this method:
========================

  * inducedMap(Module,Module,Matrix)
    -- compute the induced map
  * "inducedMap(Module,Nothing,Matrix)"
  * "inducedMap(Nothing,Module,Matrix)"
  * "inducedMap(Nothing,Nothing,Matrix)"

inducesWellDefinedMap -- whether a map is well defined
******************************************************

Description
===========

inducesWellDefinedMap(M,N,f) -- tells whether the matrix f would induce a well
defined map from N to M.

See also
========

  * inducedMap -- compute an induced map

Ways to use inducesWellDefinedMap:
==================================

  * "inducesWellDefinedMap(Module,Module,Matrix)"
  * "inducesWellDefinedMap(Module,Nothing,Matrix)"
  * "inducesWellDefinedMap(Nothing,Module,Matrix)"
  * "inducesWellDefinedMap(Nothing,Nothing,Matrix)"

For the programmer
==================

The object inducesWellDefinedMap, is a
method function.

InexactField -- the class of inexact fields
*******************************************

Description
===========

An inexact field is one whose elements are real or complex numbers, represented
floating point approximations of varying accuracy or precision.

+-------------------------------------+
|i1 : numeric_100 pi                  |
|                                     |
|o1 = 3.141592653589793238462643383279|
|                                     |
|o1 : RR (of precision 100)           |
+-------------------------------------+
|i2 : ring oo                         |
|                                     |
|o2 = RR                              |
|       100                           |
|                                     |
|o2 : RealField                       |
+-------------------------------------+
|i3 : class oo                        |
|                                     |
|o3 = RealField                       |
|                                     |
|o3 : Type                            |
+-------------------------------------+
|i4 : parent oo                       |
|                                     |
|o4 = InexactField                    |
|                                     |
|o4 : Type                            |
+-------------------------------------+

Types of inexact field:
=======================

  * ComplexField -- the class of all complex fields
  * RealField -- the class of all real fields

Methods that use an inexact field:
==================================

  * "dim(InexactField)" -- see dim(Ring), -- compute the
    Krull dimension
  * "norm(InexactField,MutableMatrix)" -- see norm,
  * "precision(InexactField)" -- see precision,

For the programmer
==================

The object InexactField, is a type, with
ancestor classes EngineRing, < Ring <
Type < MutableHashTable < HashTable
< Thing.

InexactFieldFamily -- the class of all families of inexact fields
*****************************************************************

Description
===========

All real numbers have the same class, see RR, but the rings they belong
to depends on the number of binary digits of precision used to represent them.
Similarly for complex numbers, which all belong to the class CC.
Thus RR, and CC, are regarded not as inexact fields, but as
families of inexact fields.

+-------------------------------------------------------------------+
|i1 : x = 1/3.                                                      |
|                                                                   |
|o1 = .3333333333333333                                             |
|                                                                   |
|o1 : RR (of precision 53)                                          |
+-------------------------------------------------------------------+
|i2 : class x                                                       |
|                                                                   |
|o2 = RR                                                            |
|                                                                   |
|o2 : InexactFieldFamily                                            |
+-------------------------------------------------------------------+
|i3 : ring x                                                        |
|                                                                   |
|o3 = RR                                                            |
|       53                                                          |
|                                                                   |
|o3 : RealField                                                     |
+-------------------------------------------------------------------+
|i4 : x = 1/3.p200                                                  |
|                                                                   |
|o4 = .3333333333333333333333333333333333333333333333333333333333334|
|                                                                   |
|o4 : RR (of precision 200)                                         |
+-------------------------------------------------------------------+
|i5 : class x                                                       |
|                                                                   |
|o5 = RR                                                            |
|                                                                   |
|o5 : InexactFieldFamily                                            |
+-------------------------------------------------------------------+
|i6 : ring x                                                        |
|                                                                   |
|o6 = RR                                                            |
|       200                                                         |
|                                                                   |
|o6 : RealField                                                     |
+-------------------------------------------------------------------+

See also
========

  * InexactField -- the class of inexact fields

Methods that use an inexact field family:
=========================================

  * "default(InexactFieldFamily)" -- see default, -- default
    member of a family
  * "InexactFieldFamily Array" -- see Ring Array, -- the
    standard way to make a polynomial ring
  * "InexactFieldFamily List" -- see Ring List, -- make a
    local polynomial ring
  * "InexactFieldFamily Monoid" -- see Ring Monoid, -- make
    a polynomial ring

Protected objects of class InexactFieldFamily:
==============================================

  * CC -- the class of all complex numbers
  * RR -- the class of all real numbers
  * RRi -- the class of all real intervals

For the programmer
==================

The object InexactFieldFamily, is a type,
with ancestor classes RingFamily, < Type
< MutableHashTable < HashTable <
Thing.

InexactNumber
*************

Description
===========

This type of number is intended to serve as a parent class for those types of
numbers that are inexactly represented in the computer.

Types of inexact number:
========================

  * CC -- the class of all complex numbers
  * RR -- the class of all real numbers
  * RRi -- the class of all real intervals

Methods that use an inexact number:
===================================

  * "Constant * InexactNumber" -- see *, -- a binary operator,
    usually used for multiplication
  * "InexactNumber * Constant" -- see *, -- a binary operator,
    usually used for multiplication
  * "Constant + InexactNumber" -- see +, -- a unary or binary
    operator, usually used for addition
  * "InexactNumber + Constant" -- see +, -- a unary or binary
    operator, usually used for addition
  * "Constant - InexactNumber" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "InexactNumber - Constant" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "Constant / InexactNumber" -- see Constant,
  * "Constant ^ InexactNumber" -- see Constant,
  * "InexactNumber / Constant" -- see Constant,
  * "InexactNumber ^ Constant" -- see Constant,
  * Constant == InexactNumber (missing documentation)
  * "imaginaryPart(InexactNumber)" -- see imaginaryPart,
    -- imaginary part
  * InexactNumber % RingElement (missing documentation)
  * InexactNumber * RingElement (missing documentation)
  * InexactNumber + RingElement (missing documentation)
  * InexactNumber - RingElement (missing documentation)
  * InexactNumber / RingElement (missing documentation)
  * InexactNumber // RingElement (missing documentation)
  * InexactNumber == Constant (missing documentation)
  * InexactNumber == RingElement (missing documentation)
  * InexactNumber ? Constant (missing documentation)
  * lift(Module,type of InexactNumber) (missing documentation)
  * lift(MutableMatrix,type of InexactNumber) (missing documentation)
  * lift(Vector,type of InexactNumber) (missing documentation)
  * "precision(InexactNumber)" -- see precision,
  * "quotientRemainder(InexactNumber,RingElement)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder
  * "quotientRemainder(RingElement,InexactNumber)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder
  * "realPart(InexactNumber)" -- see realPart, -- real part
  * RingElement % InexactNumber (missing documentation)
  * RingElement * InexactNumber (missing documentation)
  * RingElement + InexactNumber (missing documentation)
  * RingElement - InexactNumber (missing documentation)
  * RingElement / InexactNumber (missing documentation)
  * RingElement // InexactNumber (missing documentation)
  * RingElement == InexactNumber (missing documentation)

For the programmer
==================

The object InexactNumber, is a type, with
ancestor classes Number, < Thing.

InexactNumber'
**************

Description
===========

This class is the common parent of the classes of complex fields and real
fields.

Types of InexactNumber':
========================

  * CC_* (missing documentation)
  * RR_* (missing documentation)
  * RRi_* (missing documentation)

Methods that use an object of class InexactNumber':
===================================================

  * lift(Module,type of InexactNumber') (missing documentation)
  * lift(MutableMatrix,type of InexactNumber') (missing documentation)
  * lift(Vector,type of InexactNumber') (missing documentation)
  * promote(Constant,type of InexactNumber') (missing documentation)

For the programmer
==================

The object InexactNumber', is a type.

InfiniteNumber -- the class of all infinite numbers
***************************************************

Methods that use an infinite number:
====================================

  * "InfiniteNumber + InfiniteNumber" -- see +, -- a unary or binary
    operator, usually used for addition
  * "InfiniteNumber + Number" -- see +, -- a unary or binary operator,
    usually used for addition
  * "Number + InfiniteNumber" -- see +, -- a unary or binary operator,
    usually used for addition
  * "- InfiniteNumber" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "InfiniteNumber - InfiniteNumber" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "InfiniteNumber - Number" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "Number - InfiniteNumber" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "InfiniteNumber // Number" -- see //, -- a binary operator,
    usually used for quotient
  * "InfiniteNumber // RR" -- see //, -- a binary operator, usually
    used for quotient
  * "Number // InfiniteNumber" -- see //, -- a binary operator,
    usually used for quotient
  * "> InfiniteNumber" -- see > ZZ (Varieties),
  * ">= InfiniteNumber" -- see >= ZZ (Varieties),
  * "basis(InfiniteNumber,InfiniteNumber,Ideal)" -- see basis, --
    basis or generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,InfiniteNumber,Matrix)" -- see basis, --
    basis or generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,InfiniteNumber,Module)" -- see basis, --
    basis or generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,InfiniteNumber,Ring)" -- see basis, --
    basis or generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,List,Ideal)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,List,Matrix)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,List,Module)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,List,Ring)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,ZZ,Ideal)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,ZZ,Matrix)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,ZZ,Module)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,ZZ,Ring)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,InfiniteNumber,Ideal)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,InfiniteNumber,Matrix)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,InfiniteNumber,Module)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,InfiniteNumber,Ring)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(ZZ,InfiniteNumber,Ideal)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(ZZ,InfiniteNumber,Matrix)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(ZZ,InfiniteNumber,Module)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(ZZ,InfiniteNumber,Ring)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * CC + InfiniteNumber (missing documentation)
  * CC - InfiniteNumber (missing documentation)
  * CC ? InfiniteNumber (missing documentation)
  * InfiniteNumber * CC (missing documentation)
  * InfiniteNumber * Matrix (missing documentation)
  * InfiniteNumber + CC (missing documentation)
  * InfiniteNumber - CC (missing documentation)
  * InfiniteNumber / CC (missing documentation)
  * InfiniteNumber // CC (missing documentation)
  * InfiniteNumber // InfiniteNumber (missing documentation)
  * InfiniteNumber == InfiniteNumber (missing documentation)
  * InfiniteNumber == Number (missing documentation)
  * InfiniteNumber == RR (missing documentation)
  * InfiniteNumber ? CC (missing documentation)
  * InfiniteNumber ? RR (missing documentation)
  * InfiniteNumber ^ InfiniteNumber (missing documentation)
  * "integrate(Function,InfiniteNumber,InfiniteNumber)" -- see integrate,
    -- numerical integration
  * "integrate(Function,InfiniteNumber,Number)" -- see integrate,
    -- numerical integration
  * "integrate(Function,Number,InfiniteNumber)" -- see integrate,
    -- numerical integration
  * "isFinite(InfiniteNumber)" -- see isFinite, -- whether a
    number is finite
  * "isInfinite(InfiniteNumber)" -- see isInfinite, --
    whether a number is infinite
  * "isReal(InfiniteNumber)" -- see isReal, -- whether a number
    is real
  * map(CoherentSheaf,CoherentSheaf,Matrix,InfiniteNumber) (missing
    documentation)
  * Matrix * InfiniteNumber (missing documentation)
  * "norm(InfiniteNumber,Matrix)" -- see norm,
  * "norm(InfiniteNumber,Number)" -- see norm,
  * "norm(InfiniteNumber,RingElement)" -- see norm,
  * Number == InfiniteNumber (missing documentation)
  * "numeric(InfiniteNumber)" -- see numeric, -- convert to
    floating point
  * "numeric(InfiniteNumber,Constant)" -- see numeric, --
    convert to floating point
  * "numeric(ZZ,InfiniteNumber)" -- see numeric, -- convert to
    floating point
  * "part(InfiniteNumber,InfiniteNumber,RingElement)" -- see part,
    -- select terms of a polynomial by degree(s) or weight(s)
  * "part(InfiniteNumber,InfiniteNumber,VisibleList,RingElement)" -- see
    part, -- select terms of a polynomial by degree(s) or weight(s)
  * "part(InfiniteNumber,ZZ,RingElement)" -- see part, -- select
    terms of a polynomial by degree(s) or weight(s)
  * "part(InfiniteNumber,ZZ,VisibleList,RingElement)" -- see part,
    -- select terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,InfiniteNumber,RingElement)" -- see part, -- select
    terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,InfiniteNumber,VisibleList,RingElement)" -- see part,
    -- select terms of a polynomial by degree(s) or weight(s)
  * part(InfiniteNumber,InfiniteNumber,Number) (missing documentation)
  * part(InfiniteNumber,ZZ,Number) (missing documentation)
  * part(ZZ,InfiniteNumber,Number) (missing documentation)
  * RR == InfiniteNumber (missing documentation)
  * RR ? InfiniteNumber (missing documentation)
  * truncate(BettiTally,InfiniteNumber,InfiniteNumber) (missing documentation)
  * truncate(BettiTally,InfiniteNumber,ZZ) (missing documentation)
  * truncate(BettiTally,ZZ,InfiniteNumber) (missing documentation)
  * truncate(InfiniteNumber,Thing) (missing documentation)
  * "truncateOutput(InfiniteNumber)" -- see truncateOutput,

Protected objects of class InfiniteNumber:
==========================================

  * infinity -- infinity

For the programmer
==================

The object InfiniteNumber, is a type, with
ancestor classes Number, < Thing.

infinity -- infinity
********************

For the programmer
==================

The object infinity, is an infinite number.

info -- convert hypertext to info format
****************************************

Description
===========

This function is used internally when preparing documentation.

Ways to use info:
=================

  * info(Nothing) (missing documentation)
  * info(String) (missing documentation)

For the programmer
==================

The object info, is a method function with a single argument.

information about a map of modules
**********************************

usual information: source, target, ring.

Inhomogeneous -- a Strategy option value
****************************************

Description
===========

Inhomogeneous -- a strategy used with the keyword Strategy.

This is the default Gröbner basis algorithm used if the submodule is
inhomogeneous, and the ring is a (quotient of) a polynomial ring over a field.

See also
========

  * gb(...,Strategy=>...) -- compute a Gröbner basis

For the programmer
==================

The object Inhomogeneous, is a symbol.

initial help
************

Welcome to Macaulay2

Try entering '2+2' at your next input prompt, which begins with i. The two
output prompts begin with o.  The first one, with the equal sign, '=', gives
the value computed from your input, and the second one, with the colon, ':',
tells what type of thing the value is.

Type one of these commands to get started reading the documentation:

copyright                         -- the copyright

help "Macaulay2"                  -- top node of the documentation.

help "reading the documentation"  --

help "getting started"            --

help "a first Macaulay2 session"  --

help x                            -- show documentation for x

help about x                      -- show documentation about x

help about (x,Body=>true)         -- show documentation mentioning x

? f                               -- display brief documentation for a function
f

printWidth = 80                   -- set print width to 80 characters

viewHelp                          -- view documentation in a browser

viewHelp x                        -- view documentation on x in browser

To read the documentation in info form, in case you happen to be running
Macaulay2 in a terminal window, replace help, by infoHelp,
in any of the commands above.

insert -- copy a list, inserting an element
*******************************************

Synopsis
========

  * Usage:
        insert(i, x, L)
  * Inputs:
      * i, an integer,
      * x, a thing,
      * L, a basic list,
  * Outputs:
      * L2, a basic list, a copy of L in which x has been
        inserted into position i

Description
===========

+------------------------------------------------------+
|i1 : L = 0..10                                        |
|                                                      |
|o1 = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10)               |
|                                                      |
|o1 : Sequence                                         |
+------------------------------------------------------+
|i2 : insert(4, "hi", L)                               |
|                                                      |
|o2 = (0, 1, 2, 3, hi, 4, 5, 6, 7, 8, 9, 10)           |
|                                                      |
|o2 : Sequence                                         |
+------------------------------------------------------+
|i3 : insert(0, "hi", L)                               |
|                                                      |
|o3 = (hi, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10)           |
|                                                      |
|o3 : Sequence                                         |
+------------------------------------------------------+
|i4 : insert(11, "hi", L)                              |
|                                                      |
|o4 = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, hi)           |
|                                                      |
|o4 : Sequence                                         |
+------------------------------------------------------+
|i5 : insert(-1, "hi", L)                              |
|                                                      |
|o5 = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, hi)           |
|                                                      |
|o5 : Sequence                                         |
+------------------------------------------------------+
|i6 : apply({-1,-3,-5}, i -> L = insert(i, "hi", L)); L|
|                                                      |
|o7 = (0, 1, 2, 3, 4, 5, 6, 7, 8, hi, 9, hi, 10, hi)   |
|                                                      |
|o7 : Sequence                                         |
+------------------------------------------------------+

See also
========

  * delete -- delete some elements of a list
  * mingle -- mingle elements of several lists
  * switch -- copy a list, switching two elements
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use insert:
===================

  * "insert(ZZ,Thing,BasicList)"

For the programmer
==================

The object insert, is a method function.

installAssignmentMethod -- install methods assignment to the value of an operator
*********************************************************************************

Synopsis
========

  * Usage:
        installAssignmentMethod(op,X,Y,f)
  * Inputs:
      * op, a keyword, the symbol for a binary operator
      * X, a type, the type of the left-hand operand
      * Y, a type, the type of the right-hand operand
      * f, a function, the method function that will perform
        the assignment
  * Consequences:
      * If the operator to be used is **, say, then op should be symbol **.
        After installing the assignment method, assignments of the form x**y=v
        will be handled by evaluating f(x,y,v).

Description
===========

If the operator is a unary operator, just omit X and its comma.

We illustrate this function by defining a type of mutable list whose elements
can be both extracted and replaced using the operator _.  We also install a
method for net, so objects of the class can be printed.

+-----------------------------------------------------------------------------+
|i1 : M = new Type of MutableList                                             |
|                                                                             |
|o1 = M                                                                       |
|                                                                             |
|o1 : Type                                                                    |
+-----------------------------------------------------------------------------+
|i2 : net M := m -> peek m                                                    |
|                                                                             |
|o2 = FunctionClosure[stdio:2:9-2:20]                                         |
|                                                                             |
|o2 : FunctionClosure                                                         |
+-----------------------------------------------------------------------------+
|i3 : M _ ZZ := (x,i) -> x#i                                                  |
|                                                                             |
|o3 = FunctionClosure[stdio:3:10-3:22]                                        |
|                                                                             |
|o3 : FunctionClosure                                                         |
+-----------------------------------------------------------------------------+
|i4 : installAssignmentMethod(symbol _, M, ZZ, (x,i,v) -> x#i = v);           |
+-----------------------------------------------------------------------------+
|i5 : y = new M from (a..z)                                                   |
|                                                                             |
|o5 = M{a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w,  |
|                                                                             |
|o5 : M                                                                       |
|-----------------------------------------------------------------------------|
|x, y, z}                                                                     |
+-----------------------------------------------------------------------------+
|i6 : y_12                                                                    |
|                                                                             |
|o6 = m                                                                       |
|                                                                             |
|o6 : Symbol                                                                  |
+-----------------------------------------------------------------------------+
|i7 : y_12 = foo                                                              |
|                                                                             |
|o7 = foo                                                                     |
|                                                                             |
|o7 : Symbol                                                                  |
+-----------------------------------------------------------------------------+
|i8 : y                                                                       |
|                                                                             |
|o8 = M{a, b, c, d, e, f, g, h, i, j, k, l, foo, n, o, p, q, r, s, t, u, v, w,|
|                                                                             |
|o8 : M                                                                       |
|-----------------------------------------------------------------------------|
|x, y, z}                                                                     |
+-----------------------------------------------------------------------------+
|i9 : y_12                                                                    |
|                                                                             |
|o9 = foo                                                                     |
|                                                                             |
|o9 : Symbol                                                                  |
+-----------------------------------------------------------------------------+
For sample applications of this facility, see Symbol _ Thing = Thing,
and MutableMatrix _ Sequence = Thing.

Caveat
======

The syntax involved here is not pleasant, so we may change it to something
briefer, something involving yet another assignment operator, distinct from =
and :=.

See also
========

  * MutableList -- the class of all mutable lists
  * BasicList # ZZ -- get value from list, hash table,
    database, or string

Ways to use installAssignmentMethod:
====================================

  * "installAssignmentMethod(Symbol,HashTable,Function)"
  * "installAssignmentMethod(Symbol,HashTable,HashTable,Function)"
  * "installAssignmentMethod(Symbol,HashTable,HashTable,Option)"
  * "installAssignmentMethod(Symbol,HashTable,Option)"

For the programmer
==================

The object installAssignmentMethod, is a
method function.

installing augmented assignment methods
***************************************

In most cases, the default behavior of augmented assignment,
gives the desired result.  But in some situations, it may be useful
to override this behavior and install a custom method for a given type.

Consider the following example.

+---------------------------------------------------+
|i1 : Foo = new SelfInitializingType of MutableList;|
+---------------------------------------------------+
|i2 : net Foo := x -> net x#0;                      |
+---------------------------------------------------+
|i3 : Foo + Foo := (x, y) -> Foo {x#0 + y#0};       |
+---------------------------------------------------+
|i4 : x = Foo {1}                                   |
|                                                   |
|o4 = 1                                             |
|                                                   |
|o4 : Foo                                           |
+---------------------------------------------------+
|i5 : y = Foo {2}                                   |
|                                                   |
|o5 = 2                                             |
|                                                   |
|o5 : Foo                                           |
+---------------------------------------------------+
|i6 : x += y                                        |
|                                                   |
|o6 = 3                                             |
|                                                   |
|o6 : Foo                                           |
+---------------------------------------------------+

Note that an intermediate Foo object was created and then assigned to x.
Instead, it would be more efficient if x was modified directly.

+--------------------------------------------------------------+
|i7 : installMethod(symbol +=, Foo, (x, y) -> (x#0 += y#0; x));|
+--------------------------------------------------------------+
|i8 : x += y                                                   |
|                                                              |
|o8 = 5                                                        |
|                                                              |
|o8 : Foo                                                      |
+--------------------------------------------------------------+

In some cases, it may be useful to fall back on the default behavior of the
given operator.  When this is desired, the installed method should return the
Default, symbol.

+---------------------------------------------------------------------+
|i9 : Bar = new SelfInitializingType of List;                         |
+---------------------------------------------------------------------+
|i10 : net Bar := x -> net x#0#0;                                     |
+---------------------------------------------------------------------+
|i11 : Bar * Bar := (x, y) -> Bar {{x#0#0 * y#0#0}};                  |
+---------------------------------------------------------------------+
|i12 : installMethod(symbol *=, Bar, (x, y) -> if isMutable x#0 then (|
|              print "using custom method";                           |
|              x#0#0 *= y#0#0; x) else Default)                       |
|                                                                     |
|o12 = FunctionClosure[stdio:12:30-14:39]                             |
|                                                                     |
|o12 : FunctionClosure                                                |
+---------------------------------------------------------------------+
|i13 : x = Bar {new MutableList from {3}}                             |
|                                                                     |
|o13 = 3                                                              |
|                                                                     |
|o13 : Bar                                                            |
+---------------------------------------------------------------------+
|i14 : y = Bar {{4}}                                                  |
|                                                                     |
|o14 = 4                                                              |
|                                                                     |
|o14 : Bar                                                            |
+---------------------------------------------------------------------+
|i15 : x *= y                                                         |
|using custom method                                                  |
|                                                                     |
|o15 = 12                                                             |
|                                                                     |
|o15 : Bar                                                            |
+---------------------------------------------------------------------+
|i16 : y *= x                                                         |
|                                                                     |
|o16 = 48                                                             |
|                                                                     |
|o16 : Bar                                                            |
+---------------------------------------------------------------------+

See also
========

  * augmented assignment
  * installing methods

installMethod -- install methods
********************************

Description
===========

Most users will use a different way of installing methods.

installMethod(M,f)     -- installs a function f as a nullary method under the
name M.  This is a replacement for the syntax M () := f, which hasn't yet been
made to work.  As currently implemented, this is also the same as
nullaryMethods#(1:M) = f.

installMethod(M,A,f)     -- installs a function f as a unary method for the
class A under the name M.  This is the same as M A := f if M is a function.  As
currently implemented, this is also the same as A#M = f.

installMethod(M,A,B,f)   -- installs a function f as a binary method for
classes A and B under the name M.  This is the same as M(A,B) := f if M is a
function, or the same as A M B := f if M is a binary operator. As currently
implemented, this is also the same as Y#(M,A,B) = f, where Y is the younger of
A and B.

installMethod(M,A,B,C,f) -- installs a function f as a ternary method for
classes A, B, and C under the name M. This is the same as M(A,B,C) := f if f is
a function.  As currently implemented, this is also the same as Y#(M,A,B,C) =
f, where Y is the youngest of A, B, and C.

See also
========

  * # -- length or access to elements
  * lookup -- look up methods
  * new -- new objects and new types

For the programmer
==================

The object installMethod, is a compiled function.

instances(Type)
***************

Synopsis
========

  * Function: instances,
  * Usage:
        instances X
  * Inputs:
      * X
  * Outputs:
      * a hashtable listing global symbols whose values are instances of type X

Description
===========

+------------------------------------------+
|i1 : 20!                                  |
|                                          |
|o1 = 2432902008176640000                  |
+------------------------------------------+
|i2 : instances ZZ                         |
|                                          |
|o2 = HashTable{allowableThreads => 5     }|
|               debugLevel => 0            |
|               defaultPrecision => 53     |
|               engineDebugLevel => 0      |
|               errorDepth => 0            |
|               gbTrace => 0               |
|               interpreterDepth => 1      |
|               lineNumber => 2            |
|               loadDepth => 3             |
|               maxAllowableThreads => 7   |
|               maxExponent => 1073741823  |
|               minExponent => -1073741824 |
|               numTBBThreads => 0         |
|               o1 => 2432902008176640000  |
|               oo => 2432902008176640000  |
|               printingAccuracy => -1     |
|               printingLeadLimit => 5     |
|               printingPrecision => 6     |
|               printingTimeLimit => 20    |
|               printingTrailLimit => 5    |
|               printWidth => 77           |
|               recursionLimit => 300      |
|                                          |
|o2 : HashTable                            |
+------------------------------------------+

Ways to use this method:
========================

  * instances(Type)

integrate -- numerical integration
**********************************

Synopsis
========

  * Usage:
        integrate(f, a, b)
  * Inputs:
      * f, a function,
      * a, a number, or an infinite number,
      * b, a number, or an infinite number,
  * Outputs:
      * a real number,

Description
===========

Integrate f from a to b numerically, using Gaussian quadrature (see
https://en.wikipedia.org/wiki/Gaussian_quadrature ).

+--------------------------+
|i1 : integrate(sin, 0, pi)|
|                          |
|o1 = 2                    |
|                          |
|o1 : RR (of precision 53) |
+--------------------------+

For half-infinite intervals, 20-point Gauss-Laguerre quadrature (see
https://en.wikipedia.org/wiki/Gauss-Laguerre_quadrature ) is used.

+-----------------------------------------+
|i2 : integrate(x -> exp(-x), 0, infinity)|
|                                         |
|o2 = .9999999999999998                   |
|                                         |
|o2 : RR (of precision 53)                |
+-----------------------------------------+

For infinite intervals, 20-point Gauss-Hermite quadrature (see
https://en.wikipedia.org/wiki/Gauss-Hermite_quadrature ) is used.

+---------------------------------------------------+
|i3 : integrate(x -> exp(-x^2), -infinity, infinity)|
|                                                   |
|o3 = 1.772453850905516                             |
|                                                   |
|o3 : RR (of precision 53)                          |
+---------------------------------------------------+

Ways to use integrate:
======================

  * "integrate(Function,InfiniteNumber,InfiniteNumber)"
  * "integrate(Function,InfiniteNumber,Number)"
  * "integrate(Function,Number,InfiniteNumber)"
  * "integrate(Function,Number,Number)"

For the programmer
==================

The object integrate, is a method function.

interpreterDepth -- nesting depth of the interpreter
****************************************************

See also
========

  * commandInterpreter -- the top level command
    interpreter

For the programmer
==================

The object interpreterDepth, is an integer.

intersect -- compute an intersection
************************************

Description
===========

This function calculates the intersection of a list or sequence of compatible
objects.

See also
========

  * intersection -- compute an intersection
  * M0nbar -- calculations for divisors and curves on the
    moduli space of stable n-pointed genus zero curves
  * NAGtypes -- Common types used in Numerical Algebraic
    Geometry
  * Polyhedra -- for computations with convex polyhedra,
    cones, and fans

Ways to use intersect:
======================

  * "intersect(List)"
  * "intersect(Sequence)"
  * "intersect(Ideal)" -- see intersect(Ideal,Ideal),
    -- compute an intersection of a sequence of
    ideals or modules
  * intersect(Ideal,Ideal) -- compute an
    intersection of a sequence of ideals or modules
  * "intersect(Module)" -- see intersect(Ideal,Ideal),
    -- compute an intersection of a sequence of
    ideals or modules
  * "intersect(Module,Module)" -- see intersect(Ideal,Ideal),
    -- compute an intersection of a sequence of
    ideals or modules
  * intersect(RRi) -- computes intersection of input
    intervals
  * intersect(RRi,RRi) (missing documentation)
  * "intersect(Set,Set)" -- see intersection(Set,Set),
    -- set intersection

For the programmer
==================

The object intersect, is an associative binary method function.

intersect(Ideal,Ideal) -- compute an intersection of a sequence of ideals or modules
************************************************************************************

Synopsis
========

  * Function: intersect,
  * Usage:
        intersect(M, N)
        intersect(M, N, ..., P)
  * Inputs:
      * an ideal, or a module,
      * an ideal, or a module, submodules of the
        same module or ideals in the same ring
  * Optional inputs,:
      * Strategy => a thing, default value null, specifies the
        algorithm
      * MinimalGenerators => a Boolean value, default value
        true, indicates whether the output should be trimmed,
  * Outputs:
      * an ideal, or a module, the intersection of
        the sequence of objects

Description
===========

This function calculates the intersection of submodules of the same free
module, or of ideals in the same ring.

The following example computes the intersection of a sequence of ideals.

+----------------------------------------------------------------------+
|i1 : R = ZZ/101[a..d];                                                |
+----------------------------------------------------------------------+
|i2 : I = intersect(ideal(a, b), ideal(b, c), ideal(c, d), ideal(d, a))|
|                                                                      |
|o2 = ideal (b*d, a*c)                                                 |
|                                                                      |
|o2 : Ideal of R                                                       |
+----------------------------------------------------------------------+

The following example computes the intersection of a list of modules.

+----------------------------------+
|i3 : R=ZZ[x, y, z];               |
+----------------------------------+
|i4 : M=image matrix{{3*x}, {3*x}};|
+----------------------------------+
|i5 : N=image matrix{{5*y}, {5*y}};|
+----------------------------------+
|i6 : P=image matrix{{7*z}, {7*z}};|
+----------------------------------+
|i7 : intersect{M, N, P}           |
|                                  |
|o7 = image | 105xyz |             |
|           | 105xyz |             |
|                                  |
|                             2    |
|o7 : R-module, submodule of R     |
+----------------------------------+

The command intersect, does not accept subrings. To intersect
an ideal with a subring, use selectInSubring, along with
the elimination ordering, see Eliminate.

Multiple strategies are implemented via hooks, and can be
listed using the function hooks. More strategies may be added
using addHook.

+--------------------------------------------------------------+
|i8 : hooks(intersect, Ideal, Ideal)                           |
|                                                              |
|o8 = {0 => (intersect, Ideal, Ideal, Strategy => Default)    }|
|     {1 => (intersect, Ideal, Ideal, Strategy => Elimination)}|
|     {2 => (intersect, Ideal, Ideal, Strategy => Monomial)   }|
|                                                              |
|o8 : NumberedVerticalList                                     |
+--------------------------------------------------------------+
|i9 : hooks(intersect, Module, Module)                         |
|                                                              |
|o9 = {0 => (intersect, Module, Module, Strategy => Default)}  |
|                                                              |
|o9 : NumberedVerticalList                                     |
+--------------------------------------------------------------+

By default, the strategies are attempted in the reverse order in which the were
added, until one is successful. To run a specific strategy instead, use the
optional argument Strategy.

+----------------------------------------------------------------------+
|i10 : intersect(ideal(x, y), (ideal(x, y, z))^2, Strategy => Monomial)|
|                                                                      |
|                        2        2                                    |
|o10 = ideal (y*z, x*z, y , x*y, x )                                   |
|                                                                      |
|o10 : Ideal of R                                                      |
+----------------------------------------------------------------------+

See also
========

  * selectInSubring -- select columns in a subring

Ways to use this method:
========================

  * "intersect(Ideal)"
  * intersect(Ideal,Ideal) -- compute an
    intersection of a sequence of ideals or modules
  * "intersect(Module)"
  * "intersect(Module,Module)"

intersect(RRi) -- computes intersection of input intervals
**********************************************************

Synopsis
========

  * Function: intersect,
  * Usage:
        J = intersection(I,...)
        J = intersection(I,...,Precision => prec)
  * Inputs:
      * I, a real interval,
  * Optional inputs,:
      * Precision => an integer, default value -1, specifies the
        desired precision of the output, a value of -1 uses the minimum
        precision of the inputs.
  * Outputs:
      * J, a real interval,

Description
===========

Returns the intersection of any number of input intervals.

See also
========

  * intersect -- compute an intersection
  * intersection(RRi,RRi) -- computes
    intersection of input intervals

Ways to use this method:
========================

  * intersect(RRi) -- computes intersection of input
    intervals

intersection -- compute an intersection
***************************************

Description
===========

When a more efficient algorithm is available for computing the intersection of
all inputs simultaneously rather than iteratively, for instance for
intersecting Module,s, a specialized function that takes a list
or sequence may be installed on (symbol intersect, Type).

+-----------------------------------------------------------------------------+
|i1 : code lookup(symbol intersect, Module)                                   |
|                                                                             |
|o1 = ../../../../../Macaulay2/m2/option.m2:15:14-18:8: --source code:        |
|       (opts,f) -> args -> (                                                 |
|            -- Common code for functions created with >> to process options a|
|            uncurry(f, override (opts,args))                                 |
|            )                                                                |
|     | symbol  class            value                                        |
|     | ------  -----            -----                                        |
|     | f       FunctionClosure  FunctionClosure[../../../../../Macaulay2/m2/i|
|     | opts    OptionTable      OptionTable{MinimalGenerators => true}       |
|     |                                      Strategy => null                 |
|     | -- function f:                                                        |
|     | ../../../../../Macaulay2/m2/intersect.m2:86:42-86:108: --source code: |
|     | Module.intersect = moduleIntersectOpts >> opts -> L -> intersectHelper|
|     | -- option table opts:                                                 |
|     | OptionTable{MinimalGenerators => true}                                |
|     |             Strategy => null                                          |
|-----------------------------------------------------------------------------|
|nd arguments.                                                                |
|                                                                             |
|                                                                             |
|            location of symbol                                               |
|            ------------------                                               |
|ntersect..  ../../../../../Macaulay2/m2/option.m2:15:8-15:9                  |
|            ../../../../../Macaulay2/m2/option.m2:15:3-15:7                  |
|                                                                             |
|                                                                             |
|                                                                             |
|(L, (intersect, Module, Module), opts)                                       |
+-----------------------------------------------------------------------------+

See also
========

  * intersect -- compute an intersection

Ways to use intersection:
=========================

  * "intersection(Cone,Cone)" -- see intersection (Polyhedra),
    -- computes the intersection of cones, and
    polyhedra
  * "intersection(Cone,Polyhedron)" -- see intersection (Polyhedra),
    -- computes the intersection of cones, and
    polyhedra
  * "intersection(List)" -- see intersection (Polyhedra), --
    computes the intersection of cones, and polyhedra
  * "intersection(Polyhedron,Cone)" -- see intersection (Polyhedra),
    -- computes the intersection of cones, and
    polyhedra
  * "intersection(Polyhedron,Polyhedron)" -- see intersection (Polyhedra),
    -- computes the intersection of cones, and
    polyhedra
  * intersection(Matrix) (Polyhedra), --
    Deprecated variant of {\tt coneFromHData}
  * intersection(Matrix,Matrix) (Polyhedra)
    -- Deprecated variants of
    {\tt polyhedronFromHData} and {\tt coneFromHData}
  * "intersection(Matrix,Matrix,Matrix,Matrix)" -- see
    intersection(Matrix,Matrix) (Polyhedra),
    -- Deprecated variants of {\tt polyhedronFromHData} and {\tt coneFromHData}
  * intersection(RRi,RRi) -- computes
    intersection of input intervals
  * intersection(Set,Set) -- set
    intersection

For the programmer
==================

The object intersection, is a method function with options.

intersection(RRi,RRi) -- computes intersection of input intervals
*****************************************************************

Synopsis
========

  * Function: intersection,
  * Usage:
        K = intersection(I,J)
        K = intersection(I,J,Precision => prec)
  * Inputs:
      * I, a real interval,
      * J, a real interval,
  * Optional inputs,:
      * Precision => an integer, default value -1, specifies the
        desired precision of the output, a value of -1 uses the minimum
        precision of the inputs.
  * Outputs:
      * K, a real interval,

Description
===========

Returns the intersection of the two input intervals or an empty interval if
they do not intersect.

See also
========

  * intersect(RRi) -- computes intersection of input
    intervals

Ways to use this method:
========================

  * intersection(RRi,RRi) -- computes
    intersection of input intervals

intersection(Set,Set) -- set intersection
*****************************************

Synopsis
========

  * Function: intersection,
  * Usage:
        x * y
  * Inputs:
      * x
      * y
  * Outputs:
      * the intersection of x and y

Description
===========

+------------------------------+
|i1 : set {1,2,3} * set {2,3,4}|
|                              |
|o1 = set {2, 3}               |
|                              |
|o1 : Set                      |
+------------------------------+
+--------------------------------------------------+
|i2 : intersect(set{1,2,3}, set{2,3,4}, set{2,4,6})|
|                                                  |
|o2 = set {2}                                      |
|                                                  |
|o2 : Set                                          |
+--------------------------------------------------+

See also
========

  * Set -- the class of all sets

Ways to use this method:
========================

  * intersection(Set,Set) -- set
    intersection

interval -- construct an interval
*********************************

Synopsis
========

  * Usage:
        I = interval(n)
        I = interval(l,r)
        I = interval([l,r])
        I = interval(n,Precition => prec)
        I = interval(l,r,Precition => prec)
        I = interval([l,r],Precition => prec)
  * Inputs:
      * n, a number,
      * l, a number,
      * r, a number,
  * Optional inputs,:
      * Precision => an integer, default value -1, specifies the
        desired precision of the output, a value of -1 uses the
        defaultPrecision, or the minimum precisions of the
        inputs.
  * Outputs:
      * I, a real interval,

Description
===========

Returns an interval as small as possible containing n or from l to r.  Note
that if l is to the right of r, the constructed interval is empty.

See also
========

  * span(List) -- construct smallest interval
  * span(Sequence) -- construct smallest interval
  * toRRi -- construct an interval

Ways to use interval:
=====================

  * "interval(Array)"
  * "interval(QQ)"
  * "interval(QQ,QQ)"
  * "interval(QQ,RR)"
  * "interval(QQ,ZZ)"
  * "interval(RR)"
  * "interval(RR,QQ)"
  * "interval(RR,RR)"
  * "interval(RR,ZZ)"
  * "interval(ZZ)"
  * "interval(ZZ,QQ)"
  * "interval(ZZ,RR)"
  * "interval(ZZ,ZZ)"

For the programmer
==================

The object interval, is a method function with options.

inverse -- compute the inverse
******************************

Ways to use inverse:
====================

  * inverse(Matrix) -- compute the inverse
  * "inverse(MutableMatrix)" -- see inverse(Matrix),
    -- compute the inverse
  * "inverse(RingMap)" -- see inverse(Matrix), --
    compute the inverse
  * inverse(SheafMap) (missing documentation)

For the programmer
==================

The object inverse, is a method function.

inverse(Matrix) -- compute the inverse
**************************************

Synopsis
========

  * Function: inverse,
  * Usage:
        inverse f
  * Inputs:
      * f, a matrix, a mutable matrix, or
        a ring map,
  * Outputs:
      * a matrix, a mutable matrix, or a
        ring map, the inverse of f

Code
====

../../../../../Macaulay2/m2/methods.m2:685:49-694:27: --source code:
cacheValue = key -> f -> new CacheFunction from (x -> (
          c := try x.cache else x.cache = new CacheTable;
          if c#?key then (
               val := c#key;
               if class val === CacheFunction then (
                    remove(c,key);
                    c#key = val x)
               else val
               )
          else c#key = f x))
| symbol  class            value
| ------  -----            -----
| f       FunctionClosure  FunctionClosure[../../../../../Macaulay2/m2/matrix1.
| key     Symbol           inverse
| -- function f:
| ../../../../../Macaulay2/m2/matrix1.m2:616:5-622:19: --source code:
|      m -> (
|       if hasEngineLinearAlgebra ring m and isBasicMatrix m then
|           basicInverse m
|       else (
|               (quo,rem) := quotientRemainder(id_(target m), m);
|               if rem != 0 then error "matrix not invertible";
|               quo))
-------------------------------------------------------------------------------
     location of symbol
     ------------------
m2.  ../../../../../Macaulay2/m2/methods.m2:685:20-685:21
     ../../../../../Macaulay2/m2/methods.m2:685:13-685:16

Ways to use this method:
========================

  * inverse(Matrix) -- compute the inverse
  * "inverse(MutableMatrix)"
  * "inverse(RingMap)"

inverseErf -- inverse error function
************************************

Synopsis
========

  * Usage:
        inverseErf y
  * Inputs:
      * y, a real number,
  * Outputs:
      * a real number, the inverse error function of y;

Description
===========

The inverse of erf.

+-------------------------+
|i1 : erf 2               |
|                         |
|o1 = .9953222650189527   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+
|i2 : inverseErf oo       |
|                         |
|o2 = 1.999999999999999   |
|                         |
|o2 : RR (of precision 53)|
+-------------------------+

See also
========

  * erf -- error function
  * erfc -- complementary error function

Ways to use inverseErf:
=======================

  * "inverseErf(RR)"
  * "inverseErf(RRi)"

For the programmer
==================

The object inverseErf, is a method function.

InverseMethod -- compute reciprocals
************************************

Description
===========

InverseMethod -- a key used under which is stored a method for computing
multiplicative inverses.

Internal routines for computing powers call upon that method when the exponent
is negative.

For the programmer
==================

The object InverseMethod, is a symbol.

inversePermutation -- inverse permutation
*****************************************

Synopsis
========

  * Usage:
        y = inversePermutation x
  * Inputs:
      * x, a list, a list of length n whose elements are the
        numbers 0, 1, 2, ..., n-1, in some order, representing the permutation
        defined by sending i to x#i
  * Outputs:
      * y, a list, the list representing the inverse permutation
        of x

Description
===========

+-------------------------------+
|i1 : x = {1,2,3,4,5,0}         |
|                               |
|o1 = {1, 2, 3, 4, 5, 0}        |
|                               |
|o1 : List                      |
+-------------------------------+
|i2 : y = inversePermutation x  |
|                               |
|o2 = {5, 0, 1, 2, 3, 4}        |
|                               |
|o2 : List                      |
+-------------------------------+
|i3 : all(#x, i -> x#(y#i) == i)|
|                               |
|o3 = true                      |
+-------------------------------+
|i4 : all(#x, i -> y#(x#i) == i)|
|                               |
|o4 = true                      |
+-------------------------------+

We compose permutations with _; see VisibleList _ List.

+-----------------------+
|i5 : x_x_x             |
|                       |
|o5 = {3, 4, 5, 0, 1, 2}|
|                       |
|o5 : List              |
+-----------------------+
|i6 : x_x_x_x_x_x       |
|                       |
|o6 = {0, 1, 2, 3, 4, 5}|
|                       |
|o6 : List              |
+-----------------------+
|i7 : x_y               |
|                       |
|o7 = {0, 1, 2, 3, 4, 5}|
|                       |
|o7 : List              |
+-----------------------+
|i8 : y_x               |
|                       |
|o8 = {0, 1, 2, 3, 4, 5}|
|                       |
|o8 : List              |
+-----------------------+

For the programmer
==================

The object inversePermutation, is a function closure.

inverseRegularizedBeta -- inverse of the regularized beta function
******************************************************************

Synopsis
========

  * Usage:
        inverseRegularizedBeta(y, a, b)
  * Inputs:
      * y, a real number,
      * a, a real number,
      * b, a real number,
  * Outputs:
      * a real number,

Description
===========

This is the inverse of regularizedBeta, with respect to
the first argument.

+-------------------------------------+
|i1 : regularizedBeta(1/2, 3, 4)      |
|                                     |
|o1 = .6562499999999997               |
|                                     |
|o1 : RR (of precision 53)            |
+-------------------------------------+
|i2 : inverseRegularizedBeta(oo, 3, 4)|
|                                     |
|o2 = .4999999999999996               |
|                                     |
|o2 : RR (of precision 53)            |
+-------------------------------------+

See also
========

  * Beta -- Beta function
  * regularizedBeta -- regularized beta function

Ways to use inverseRegularizedBeta:
===================================

  * "inverseRegularizedBeta(RR,RR,RR)"

For the programmer
==================

The object inverseRegularizedBeta, is a
method function.

inverseRegularizedGamma -- inverse of the upper regularized gamma function
**************************************************************************

Synopsis
========

  * Usage:
        inverseRegularizedGamma(s, q)
  * Inputs:
      * s, a real number,
      * q, a real number,
  * Outputs:
      * a real number,

Description
===========

This is the inverse of regularizedGamma, with respect
to the second argument.

+-----------------------------------+
|i1 : regularizedGamma(3, 7)        |
|                                   |
|o1 = .02963616388052177            |
|                                   |
|o1 : RR (of precision 53)          |
+-----------------------------------+
|i2 : inverseRegularizedGamma(3, oo)|
|                                   |
|o2 = 7                             |
|                                   |
|o2 : RR (of precision 53)          |
+-----------------------------------+

See also
========

  * Gamma -- Gamma function
  * regularizedGamma -- upper regularized gamma
    function

Ways to use inverseRegularizedGamma:
====================================

  * "inverseRegularizedGamma(RR,RR)"

For the programmer
==================

The object inverseRegularizedGamma, is a
method function.

Invoking the program
********************

On systems with a command line interface, the following commands can be used to
start the program.  When the program starts up, the initialization file,
init.m2, will be loaded.

M2 -- starts the program.

M2 file1 file2 ...  -- starts the program, reading and executing the specified
files.

The options that can be provided on the command line may be displayed by
running M2 --help.
+-----------------------------------------------------------------------------+
|i1 : assert(0 == run (commandLine#0 | " --help"));                           |
|usage:                                                                       |
|    M2-binary [option ...] [file ...]                                        |
|options:                                                                     |
|    --help             print this brief help message and exit                |
|    --no-backtrace     print no backtrace after error                        |
|    --copyright        display full copyright message                        |
|    --no-debug         do not enter debugger upon error                      |
|    --debug n          debug warning message n by signalling an error        |
|    --int              don't handle interrupts                               |
|    --notify           notify when loading files during initialization       |
|                       and when evaluating command line arguments            |
|    --prefix DIR       set prefixDirectory                                   |
|    --print-width n    set printWidth=n (the default is the window width)    |
|    --restarted        used internally to indicate this is a restart         |
|    --read-only-files  disallow file and socket creation and writing         |
|    --script           as first argument, interpret second argument as name o|
|                       implies --stop, --no-debug, --silent and -q           |
|                       see scriptCommandLine                                 |
|    --silent           no startup banner                                     |
|    --stop             exit on error                                         |
|    --texmacs          TeXmacs session mode                                  |
|    --version          print version number and exit                         |
|    --webapp           WebApp session mode                                   |
|    --no-core          don't load the Core                                   |
|    --no-preload       don't load the preloaded packages                     |
|    --no-prompts       print no input prompts                                |
|    --no-randomize     don't set the random number seed based on the date    |
|    --no-readline      don't use readline                                    |
|    --no-threads       don't start any additional threads (or tasks)         |
|    --no-time          arrange for the current time to be always 0           |
|    --no-tty           do not treat stdin and stdout as tty's                |
|    -q                 don't load user's init.m2 file or use packages in home|
|    -E '...'           evaluate expression '...' before initialization       |
|    -e '...'           evaluate expression '...' after initialization        |
|    --srcdir '...'     add top source or build tree '...' to initial path    |
|    --check n          run tests to level n                                  |
|                           n=1: basic tests                                  |
|                           n=2: test Core                                    |
|                           n=3: test all packages                            |
|environment:                                                                 |
|    EDITOR             default text editor                                   |
|    GC_INITIAL_HEAP_SIZE      (gc: initial heap size in bytes)               |
|    GC_PRINT_STATS            (gc: turn on logging)                          |
|    GC_PRINT_VERBOSE_STATS    (gc: turn on more verbose logging)             |
|    GC_LOG_FILE               (gc: name of log file)                         |
|    GC_DUMP_REGULARLY         (gc: dump state regularly)                     |
|    GC_NPROCS                 (gc: number of threads to use, linux)          |
|-----------------------------------------------------------------------------|
|f a script                                                                   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
| directory                                                                   |
+-----------------------------------------------------------------------------+

To terminate the program, one may type exit, quit,
end, or the end of file character.

See also
========

  * prefixDirectory -- the prefix directory
  * prefixPath -- absolute locations of Macaulay2 files

irreducibleCharacteristicSeries -- irreducible characteristic series of an ideal
********************************************************************************

Synopsis
========

  * Usage:
        (ics,p) = irreducibleCharacteristicSeries I
  * Inputs:
      * I, an ideal,
  * Outputs:
      * ics, a list, a list of matrices, representing an
        irreducible characteristic series for I
      * p, a ring map, an isomorphism from the ring of I to the
        ring of the characteristic series. The ring retains the names and
        degrees of the variables, but reorders the variables and uses a default
        monomial ordering.

Description
===========

 As we see in the example below, an irreducible characteristic series for $I$
consists of a collection of triangular sets. Here, given a polynomial $f$,
write $lvar(f)$ for the largest variable appearing in $f$ (with respect to the
lexicographic order). In the example, $lvar(-y w+x^2) = y$ . A triangular set
consists of polynomials $f_1,\dots,f_r$ such that $lvar(f_1)< \dots <
lvar(f_r)$. In the example, $lvar(-x*y^2+z^3) = x < w = lvar(-w*y+z^2)$ . If
$T_1,\dots,T_s$ form an irreducible characteristic series for $I$ , and if
$J_i$ is the ideal generated by the largest variables of the elements of $T_i$
, then the algebraic set $V(I)$ defined by $I$ is the union of the sets $V(T_i)
\setminus V(I_i)$, for $i=1,\dots,s$. The minimal associated primes of $I$ can
thus be recovered from the irreducible characteristic series by saturation and
by throwing away superfluous primes. This is done by minimalPrimes (MinimalPrimes),
which uses this routine.

+-------------------------------------------------------------------------+
|i1 : R = QQ[w,x,y,z];                                                    |
+-------------------------------------------------------------------------+
|i2 : (L,p) = irreducibleCharacteristicSeries ideal(x^2-y*w,x^3-z*w^2)    |
|                                                                         |
|o2 = ({| zw2-x3 yw-x2 |, | x w |}, map (R, QQ[y..z, w..x], {y, z, w, x}))|
|                                                                         |
|o2 : Sequence                                                            |
+-------------------------------------------------------------------------+
|i3 : apply(L, m -> p m)                                                  |
|                                                                         |
|o3 = {| -x3+w2z -x2+wy |, | x w |}                                       |
|                                                                         |
|o3 : List                                                                |
+-------------------------------------------------------------------------+
|i4 : p^-1                                                                |
|                                                                         |
|o4 = map (QQ[y..z, w..x], R, {w, x, y, z})                               |
|                                                                         |
|o4 : RingMap QQ[y..z, w..x] <-- R                                        |
+-------------------------------------------------------------------------+

See also
========

  * minimalPrimes (MinimalPrimes) -- minimal primes of an
    ideal

Ways to use irreducibleCharacteristicSeries:
============================================

  * "irreducibleCharacteristicSeries(Ideal)"

For the programmer
==================

The object irreducibleCharacteristicSeries,
is a method function.

isAffineRing -- whether something is an affine ring
***************************************************

Synopsis
========

  * Usage:
        isAffineRing R
  * Inputs:
      * R, a ring,
  * Outputs:
      * a Boolean value, true, if R is an affine
        ring and false, otherwise

Description
===========

For our purposes, an affine ring is a quotient of a (not necessarily
commutative) polynomial ring, over a field.
+------------------------------------------------------+
|i1 : isAffineRing (ZZ[a,b,c,d])                       |
|                                                      |
|o1 = false                                            |
+------------------------------------------------------+
|i2 : isAffineRing (ZZ/101[a,b,c,d])                   |
|                                                      |
|o2 = true                                             |
+------------------------------------------------------+
|i3 : isAffineRing (ZZ/2[x,y,z]/(x^2-y*z))             |
|                                                      |
|o3 = true                                             |
+------------------------------------------------------+
|i4 : isAffineRing (QQ[x,dx, WeylAlgebra => {x => dx}])|
|                                                      |
|o4 = false                                            |
+------------------------------------------------------+

See also
========

  * coefficientRing -- get the coefficient ring
  * isField -- whether something is a field
  * ambient -- ambient free module of a subquotient, or ambient
    ring

Ways to use isAffineRing:
=========================

  * "isAffineRing(PolynomialRing)"
  * "isAffineRing(QuotientRing)"
  * "isAffineRing(Ring)"

For the programmer
==================

The object isAffineRing, is a method function.

isANumber -- whether a number is not not-a-number
*************************************************

Synopsis
========

  * Usage:
        isANumber x
  * Inputs:
      * x, a number,
  * Outputs:
      * a Boolean value, whether x is not not a number.

Description
===========

For a discussion of the notion of not-a-number in floating point arithmetic,
see http://en.wikipedia.org/wiki/NaN.

+-------------------------+
|i1 : isANumber 3.        |
|                         |
|o1 = true                |
+-------------------------+
|i2 : inf = 1/0.          |
|                         |
|o2 = infinity            |
|                         |
|o2 : RR (of precision 53)|
+-------------------------+
|i3 : isANumber inf       |
|                         |
|o3 = true                |
+-------------------------+
|i4 : nan = inf - inf     |
|                         |
|o4 = NotANumber          |
|                         |
|o4 : RR (of precision 53)|
+-------------------------+
|i5 : isANumber nan       |
|                         |
|o5 = false               |
+-------------------------+

See also
========

  * isFinite -- whether a number is finite
  * isInfinite -- whether a number is infinite

Ways to use isANumber:
======================

  * "isANumber(Number)"

For the programmer
==================

The object isANumber, is a compiled function.

isBorel -- whether an ideal is fixed by upper triangular changes of coordinates
*******************************************************************************

Ways to use isBorel:
====================

  * "isBorel(MonomialIdeal)"

For the programmer
==================

The object isBorel, is a method function.

isCommutative -- whether a ring is commutative
**********************************************

Synopsis
========

  * Usage:
        isCommutative R
  * Inputs:
      * R, a ring,
  * Outputs:
      * a Boolean value, true, if the ring,
        R is commutative and false, otherwise

Description
===========

+------------------------------------------------------+
|i1 : isCommutative(QQ[x,y])                           |
|                                                      |
|o1 = true                                             |
+------------------------------------------------------+
|i2 : isCommutative(QQ[x,y, SkewCommutative => true])  |
|                                                      |
|o2 = false                                            |
+------------------------------------------------------+
|i3 : isCommutative(QQ[x,dx, WeylAlgebra => {x => dx}])|
|                                                      |
|o3 = false                                            |
+------------------------------------------------------+

See also
========

  * WeylAlgebra, --
    specify differential operators in the ring
  * SkewCommutative -- an optional argument

Ways to use isCommutative:
==========================

  * "isCommutative(Ring)"
  * isCommutative(ChainComplexMap) (missing documentation)

For the programmer
==================

The object isCommutative, is a method function.

isConstant -- whether a ring element is constant
************************************************

Synopsis
========

  * Usage:
        isConstant f
  * Inputs:
      * f
  * Outputs:
      * whether f is constant, i.e., is in the coefficient ring

Description
===========

+-----------------------+
|i1 : isConstant 3      |
|                       |
|o1 = true              |
+-----------------------+
|i2 : QQ[a,b][x,y];     |
+-----------------------+
|i3 : isConstant (x+a-x)|
|                       |
|o3 = true              |
+-----------------------+
|i4 : isConstant x      |
|                       |
|o4 = false             |
+-----------------------+

Code
====

../../../../../Macaulay2/m2/rings.m2:102:26-102:66: --source code:
isConstant RingElement := r -> liftable(r, coefficientRing ring r)

See also
========

  * coefficientRing -- get the coefficient ring

Ways to use isConstant:
=======================

  * "isConstant(RingElement)"

For the programmer
==================

The object isConstant, is a method function.

isDirectSum -- whether something is a direct sum
************************************************

Description
===========

Works for modules, graded modules, etc.  The components of the sum can be
recovered with components.
+---------------------+
|i1 : isDirectSum ZZ^6|
|                     |
|o1 = false           |
+---------------------+
|i2 : F = ZZ^2 ++ ZZ^3|
|                     |
|       5             |
|o2 = ZZ              |
|                     |
|o2 : ZZ-module, free |
+---------------------+
|i3 : isDirectSum F   |
|                     |
|o3 = true            |
+---------------------+
|i4 : components F    |
|                     |
|        2    3       |
|o4 = {ZZ , ZZ }      |
|                     |
|o4 : List            |
+---------------------+

Ways to use isDirectSum:
========================

  * "isDirectSum(ChainComplex)"
  * "isDirectSum(GradedModule)"
  * "isDirectSum(Module)"

For the programmer
==================

The object isDirectSum, is a method function.

isEmpty
*******

Description
===========

This function is a method function, defined in the core so multiple packages
can add methods to it.

See also
========

  * Polyhedra -- for computations with convex polyhedra,
    cones, and fans
  * isEmpty(RRi) -- empty test for an interval

Ways to use isEmpty:
====================

  * "isEmpty(Polyhedron)" -- see isEmpty (Polyhedra), -- checks
    if a Polyhedron is empty
  * isEmpty(RRi) -- empty test for an interval

For the programmer
==================

The object isEmpty, is a method function.

isEmpty(RRi) -- empty test for an interval
******************************************

Synopsis
========

  * Function: isEmpty,
  * Usage:
        x = isEmpty(I)
  * Inputs:
      * I, a real interval,
  * Outputs:
      * x, a Boolean value,

Description
===========

Returns true if the input interval is empty, i.e., the left endpoint is to the
right of the right endpoint.

See also
========

  * isMember -- test membership in a list or set

Ways to use this method:
========================

  * isEmpty(RRi) -- empty test for an interval

isField -- whether something is a field
***************************************

Synopsis
========

  * Usage:
        isField R
  * Inputs:
      * R, a ring,
  * Outputs:
      * a Boolean value, true, if R was explicitly
        constructed as a field (no computation is done) and false,
        otherwise

Description
===========

This function recognizes basic fields, see Galois fields, and
fraction fields.
+---------------------------+
|i1 : isField QQ            |
|                           |
|o1 = true                  |
+---------------------------+
|i2 : isField CC_53         |
|                           |
|o2 = true                  |
+---------------------------+
|i3 : isField GF(2,3)       |
|                           |
|o3 = true                  |
+---------------------------+
|i4 : isField(frac(QQ[x,y]))|
|                           |
|o4 = true                  |
+---------------------------+
This function will not recognize other rings as fields.
+----------------------+
|i5 : R = QQ[x]/(x^2+1)|
|                      |
|o5 = R                |
|                      |
|o5 : QuotientRing     |
+----------------------+
|i6 : isUnit x         |
|                      |
|o6 = true             |
+----------------------+
|i7 : isField R        |
|                      |
|o7 = false            |
+----------------------+
|i8 : F = toField R    |
|                      |
|o8 = F                |
|                      |
|o8 : PolynomialRing   |
+----------------------+
|i9 : isField F        |
|                      |
|o9 = true             |
+----------------------+

See also
========

  * toField -- declare that a ring is a field
  * FractionField -- the class of all fraction fields
  * GaloisField -- the class of all Galois fields
  * QuotientRing -- the class of all quotient rings
  * isUnit -- whether a ring element is a unit

Ways to use isField:
====================

  * "isField(EngineRing)"
  * "isField(Ring)"

For the programmer
==================

The object isField, is a method function.

isFinite -- whether a number is finite
**************************************

Synopsis
========

  * Usage:
        isFinite x
  * Inputs:
      * x, a number,
  * Outputs:
      * a Boolean value, whether x is finite, i.e., is not an
        infinite real number, nor not a number.

Description
===========

+-------------------------+
|i1 : sqrt 2.             |
|                         |
|o1 = 1.414213562373095   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+
|i2 : isFinite oo         |
|                         |
|o2 = true                |
+-------------------------+
|i3 : i = 1/0.            |
|                         |
|o3 = infinity            |
|                         |
|o3 : RR (of precision 53)|
+-------------------------+
|i4 : isFinite oo         |
|                         |
|o4 = false               |
+-------------------------+
|i5 : i-i                 |
|                         |
|o5 = NotANumber          |
|                         |
|o5 : RR (of precision 53)|
+-------------------------+
|i6 : isFinite oo         |
|                         |
|o6 = false               |
+-------------------------+

See also
========

  * isANumber -- whether a number is not not-a-number
  * isInfinite -- whether a number is infinite

Ways to use isFinite:
=====================

  * "isFinite(Constant)"
  * "isFinite(InfiniteNumber)"
  * "isFinite(Number)"

For the programmer
==================

The object isFinite, is a method function.

isFinitePrimeField -- whether a ring is a finite prime field
************************************************************

Synopsis
========

  * Usage:
        isFinitePrimeField R
  * Inputs:
      * R, a ring,
  * Outputs:
      * a Boolean value, whether R is a finite prime field

Description
===========

+--------------------------------+
|i1 : isFinitePrimeField QQ      |
|                                |
|o1 = false                      |
+--------------------------------+
|i2 : isFinitePrimeField (ZZ/101)|
|                                |
|o2 = true                       |
+--------------------------------+

For the programmer
==================

The object isFinitePrimeField, is a function closure.

isFreeModule -- whether something is a free module
**************************************************

Synopsis
========

  * Usage:
        isFreeModule M
  * Inputs:
      * M, a thing,
  * Outputs:
      * a Boolean value, true, if the given
        representation of M is a free module and false, otherwise

Description
===========

This function checks if the module M is equal to its ambient,
free module by examining its matrix of generators,
and its matrix of relations.

To determine whether M is isomorphic to a free module, use prune,
M.
+------------------------------+
|i1 : R = ZZ/7[x,y];           |
+------------------------------+
|i2 : M = kernel vars R        |
|                              |
|o2 = image {1} | -y |         |
|           {1} | x  |         |
|                              |
|                             2|
|o2 : R-module, submodule of R |
+------------------------------+
|i3 : isFreeModule M           |
|                              |
|o3 = false                    |
+------------------------------+
|i4 : isFreeModule prune M     |
|                              |
|o4 = true                     |
+------------------------------+

See also
========

  * ambient -- ambient free module of a subquotient, or ambient
    ring
  * prune(Module) -- minimal
    presentation of a module

Ways to use isFreeModule:
=========================

  * "isFreeModule(Module)"
  * "isFreeModule(Thing)"

For the programmer
==================

The object isFreeModule, is a method function.

isGlobalSymbol -- whether a global symbol with a given name exists
******************************************************************

Synopsis
========

  * Usage:
        isGlobalSymbol s
  * Inputs:
      * s, a string,
  * Outputs:
      * a Boolean value, whether a global symbol with the name
        contained in the string
      * s
      *  has been defined

Description
===========

The search for the symbol runs through the dictionaries in the list
dictionaryPath.
+----------------------------+
|i1 : isGlobalSymbol "res"   |
|                            |
|o1 = true                   |
+----------------------------+
|i2 : isGlobalSymbol "resres"|
|                            |
|o2 = false                  |
+----------------------------+

See also
========

  * dictionaryPath
  * getGlobalSymbol -- create a global symbol in a
    global dictionary

For the programmer
==================

The object isGlobalSymbol, is a compiled function.

isIdeal -- whether something is an ideal
****************************************

Synopsis
========

  * Usage:
        isIdeal I
  * Inputs:
      * I, a thing,
  * Outputs:
      * a Boolean value, true, if I is either an
        ideal, a monomial ideal, or a
        module, which is a submodule of a free module of rank 1 with
        generators in degree 0 and false, otherwise

Description
===========

+------------------------------+
|i1 : S = QQ[x,y,z];           |
+------------------------------+
|i2 : I = ideal(x^2, y^2)      |
|                              |
|             2   2            |
|o2 = ideal (x , y )           |
|                              |
|o2 : Ideal of S               |
+------------------------------+
|i3 : isIdeal I                |
|                              |
|o3 = true                     |
+------------------------------+
|i4 : J = monomialIdeal I      |
|                              |
|                     2   2    |
|o4 = monomialIdeal (x , y )   |
|                              |
|o4 : MonomialIdeal of S       |
+------------------------------+
|i5 : isIdeal J                |
|                              |
|o5 = true                     |
+------------------------------+
|i6 : R = QQ[a..d]/(a*b*c*d);  |
+------------------------------+
|i7 : I = ideal(a^2,b^2) * R^1 |
|                              |
|o7 = image | a2 b2 |          |
|                              |
|                             1|
|o7 : R-module, submodule of R |
+------------------------------+
|i8 : isIdeal I                |
|                              |
|o8 = true                     |
+------------------------------+
|i9 : J = a^2 * R^2 + a*b * R^2|
|                              |
|o9 = image | a2 0  ab 0  |    |
|           | 0  a2 0  ab |    |
|                              |
|                             2|
|o9 : R-module, submodule of R |
+------------------------------+
|i10 : isIdeal J               |
|                              |
|o10 = false                   |
+------------------------------+

See also
========

  * ideal(Module) -- converts a module to an ideal

Ways to use isIdeal:
====================

  * "isIdeal(Ideal)"
  * "isIdeal(Module)"
  * "isIdeal(Thing)"

For the programmer
==================

The object isIdeal, is a method function.

isInfinite -- whether a number is infinite
******************************************

Synopsis
========

  * Usage:
        isInfinite x
  * Inputs:
      * x, a number,
  * Outputs:
      * a Boolean value, whether x is an infinite number

Description
===========

+-------------------------+
|i1 : isInfinite 3.       |
|                         |
|o1 = false               |
+-------------------------+
|i2 : inf = 1/0.          |
|                         |
|o2 = infinity            |
|                         |
|o2 : RR (of precision 53)|
+-------------------------+
|i3 : isInfinite inf      |
|                         |
|o3 = true                |
+-------------------------+
|i4 : nan = inf - inf     |
|                         |
|o4 = NotANumber          |
|                         |
|o4 : RR (of precision 53)|
+-------------------------+
|i5 : isInfinite nan      |
|                         |
|o5 = false               |
+-------------------------+

See also
========

  * isFinite -- whether a number is finite
  * isANumber -- whether a number is not not-a-number

Ways to use isInfinite:
=======================

  * "isInfinite(Constant)"
  * "isInfinite(InfiniteNumber)"
  * "isInfinite(Number)"

For the programmer
==================

The object isInfinite, is a method function.

isInjective -- whether a map is injective
*****************************************

Synopsis
========

  * Usage:
        isInjective f
  * Inputs:
      * f, a matrix, or a ring map,
  * Outputs:
      * a Boolean value, whether the kernel is zero

Description
===========

This function computes the kernel, and checks whether it is zero.
+---------------------------------------------+
|i1 : R = QQ[a..d];                           |
+---------------------------------------------+
|i2 : F = matrix{{a,b},{c,d}}                 |
|                                             |
|o2 = | a b |                                 |
|     | c d |                                 |
|                                             |
|             2      2                        |
|o2 : Matrix R  <-- R                         |
+---------------------------------------------+
|i3 : isInjective F                           |
|                                             |
|o3 = true                                    |
+---------------------------------------------+
|i4 : G = substitute(F, R/(det F))            |
|                                             |
|o4 = | a b |                                 |
|     | c d |                                 |
|                                             |
|                  R      2           R      2|
|o4 : Matrix (-----------)  <-- (-----------) |
|             - b*c + a*d        - b*c + a*d  |
+---------------------------------------------+
|i5 : isInjective G                           |
|                                             |
|o5 = false                                   |
+---------------------------------------------+

Similarly for ring maps:
+--------------------------------------------+
|i6 : S = QQ[r,s,t];                         |
+--------------------------------------------+
|i7 : phi = map(S,R,{r^3, r^2*s, r*s*t, s^3})|
|                                            |
|                  3   2           3         |
|o7 = map (S, R, {r , r s, r*s*t, s })       |
|                                            |
|o7 : RingMap S <-- R                        |
+--------------------------------------------+
|i8 : isInjective phi                        |
|                                            |
|o8 = false                                  |
+--------------------------------------------+
|i9 : S' = coimage phi                       |
|                                            |
|o9 = S'                                     |
|                                            |
|o9 : QuotientRing                           |
+--------------------------------------------+
|i10 : phi' = phi * map(R,S')                |
|                                            |
|                    3   2           3       |
|o10 = map (S, S', {r , r s, r*s*t, s })     |
|                                            |
|o10 : RingMap S <-- S'                      |
+--------------------------------------------+
|i11 : isInjective phi'                      |
|                                            |
|o11 = true                                  |
+--------------------------------------------+

Caveat
======

One could imagine a faster routine for this.  If you write one, please send it
to us!

See also
========

  * kernel -- kernel of a ringmap, matrix, or chain complex
  * isSurjective -- whether a map is surjective
  * coimage(RingMap) -- coimage of a map
  * determinant -- determinant of a matrix
  * substitution and maps between rings

Ways to use isInjective:
========================

  * "isInjective(Matrix)"
  * "isInjective(RingMap)"

For the programmer
==================

The object isInjective, is a method function.

isInputFile(File) -- whether a file is open for input
*****************************************************

Synopsis
========

  * Function: isInputFile,
  * Usage:
        isInputFile f
  * Inputs:
      * f
  * Outputs:
      * a Boolean value,  whether f is an open input file

Description
===========

+---------------------------------------+
|i1 : "test-file" << "hi there" << close|
|                                       |
|o1 = test-file                         |
|                                       |
|o1 : File                              |
+---------------------------------------+
|i2 : isInputFile oo                    |
|                                       |
|o2 = false                             |
+---------------------------------------+
|i3 : f = openIn "test-file"            |
|                                       |
|o3 = test-file                         |
|                                       |
|o3 : File                              |
+---------------------------------------+
|i4 : isInputFile f                     |
|                                       |
|o4 = true                              |
+---------------------------------------+
|i5 : isOpen f                          |
|                                       |
|o5 = true                              |
+---------------------------------------+
|i6 : get f                             |
|                                       |
|o6 = hi there                          |
+---------------------------------------+
|i7 : isInputFile f                     |
|                                       |
|o7 = false                             |
+---------------------------------------+
|i8 : isOpen f                          |
|                                       |
|o8 = false                             |
+---------------------------------------+
|i9 : removeFile "test-file"            |
+---------------------------------------+

See also
========

  * openIn -- open an input file
  * openInOut -- open an input output file
  * get -- get the contents of a file
  * isOpen -- whether a file or database is open
  * close -- close a file

Ways to use this method:
========================

  * isInputFile(File) -- whether a file is open
    for input

isIsomorphism -- whether a map is an isomorphism
************************************************

Description
===========

isIsomorphism f -- whether the map f of modules is an isomorphism.

Ways to use isIsomorphism:
==========================

  * "isIsomorphism(Matrix)"
  * isIsomorphism(SheafMap) (missing documentation)

For the programmer
==================

The object isIsomorphism, is a method function.

isListener(File) -- whether a file is open for listening
********************************************************

Synopsis
========

  * Function: isListener,
  * Usage:
        isListener f
  * Inputs:
      * f
  * Outputs:
      * a Boolean value,  whether f is an open listener

See also
========

  * openListener -- open a port for listening

Ways to use this method:
========================

  * isListener(File) -- whether a file is open for
    listening

isMember -- test membership in a list or set
********************************************

Synopsis
========

  * Usage:
        isMember(e,x)
  * Inputs:
      * e, a thing,
      * x, a list, a sequence, or a set,
  * Outputs:
      * a Boolean value, whether e is in the list, sequence, or
        set x;

Description
===========

+-----------------------------+
|i1 : isMember(c,{a,b,c,d,e}) |
|                             |
|o1 = true                    |
+-----------------------------+
|i2 : isMember(f,(a,b,c,d,e)) |
|                             |
|o2 = false                   |
+-----------------------------+
|i3 : isMember(3,set{1,2,5,6})|
|                             |
|o3 = false                   |
+-----------------------------+

This function may also be called using the synonym member.

See also
========

  * positions -- which elements of a list satisfy a condition
  * Set -- the class of all sets

Ways to use isMember:
=====================

  * "isMember(Thing,Set)"
  * "isMember(Thing,VisibleList)"
  * isMember(QQ,RRi) -- membership test in an
    interval
  * "isMember(RR,RRi)" -- see isMember(QQ,RRi),
    -- membership test in an interval
  * "isMember(ZZ,RRi)" -- see isMember(QQ,RRi),
    -- membership test in an interval
  * "isMember(Number,Ideal)" -- see isMember(RingElement,Ideal),
    -- test membership in an ideal
  * isMember(RingElement,Ideal), --
    test membership in an ideal

For the programmer
==================

The object isMember, is a method function.

isMember(QQ,RRi) -- membership test in an interval
**************************************************

Synopsis
========

  * Function: isMember,
  * Usage:
        isMember(x,I)
  * Inputs:
      * x, a rational number, an integer, or a real number,
      * I, a real interval,
  * Outputs:
      * a Boolean value,

Description
===========

Returns true if the input number is in the interval.

See also
========

  * isEmpty

Ways to use this method:
========================

  * isMember(QQ,RRi) -- membership test in an
    interval
  * "isMember(RR,RRi)"
  * "isMember(ZZ,RRi)"

isMember(RingElement,Ideal) -- test membership in an ideal
**********************************************************

Synopsis
========

  * Function: isMember,
  * Usage:
        isMember(r,I)
  * Inputs:
      * r, a ring element, or a number,
      * I, an ideal,
  * Outputs:
      * a Boolean value, whether r is in the ideal I;

Description
===========

+-------------------------------------------+
|i1 : R = QQ[x,y,z]                         |
|                                           |
|o1 = R                                     |
|                                           |
|o1 : PolynomialRing                        |
+-------------------------------------------+
|i2 : I = ideal(-x^3 + y, x^2*y - z)        |
|                                           |
|               3       2                   |
|o2 = ideal (- x  + y, x y - z)             |
|                                           |
|o2 : Ideal of R                            |
+-------------------------------------------+
|i3 : isMember(x*y^3 - z^2 + y^5 - z^3, I)  |
|                                           |
|o3 = true                                  |
+-------------------------------------------+
|i4 : J = ideal(x*z - y, x*y + 2*z^2, y - z)|
|                                           |
|                             2             |
|o4 = ideal (x*z - y, x*y + 2z , y - z)     |
|                                           |
|o4 : Ideal of R                            |
+-------------------------------------------+
|i5 : isMember(x^3*z - 2*y^2, J)            |
|                                           |
|o5 = false                                 |
+-------------------------------------------+

Ways to use this method:
========================

  * "isMember(Number,Ideal)"
  * isMember(RingElement,Ideal), --
    test membership in an ideal

isModule -- whether something is a module
*****************************************

Synopsis
========

  * Usage:
        isModule M
  * Inputs:
      * M, a thing,
  * Outputs:
      * a Boolean value, true, if M is a
        module, and false, otherwise

Description
===========

+------------------------------+
|i1 : R = QQ[a..d]/(a*b*c*d);  |
+------------------------------+
|i2 : isModule R               |
|                              |
|o2 = false                    |
+------------------------------+
|i3 : M = a^2 * R^2 + a*b * R^2|
|                              |
|o3 = image | a2 0  ab 0  |    |
|           | 0  a2 0  ab |    |
|                              |
|                             2|
|o3 : R-module, submodule of R |
+------------------------------+
|i4 : isModule M               |
|                              |
|o4 = true                     |
+------------------------------+

Ways to use isModule:
=====================

  * "isModule(Module)"
  * "isModule(Thing)"

For the programmer
==================

The object isModule, is a method function.

isMonomialIdeal -- whether something is a monomial ideal
********************************************************

Synopsis
========

  * Usage:
        isMonomialIdeal I
  * Inputs:
      * I, a thing,
  * Outputs:
      * a Boolean value, true, if I is either a
        monomial ideal, or an ideal,
        generated by monomials and false, otherwise

Description
===========

+------------------------------------------------+
|i1 : QQ[w,x,y,z];                               |
+------------------------------------------------+
|i2 : I = minors(2, matrix{{w,x,y},{x,y,z}})     |
|                                                |
|               2                        2       |
|o2 = ideal (- x  + w*y, - x*y + w*z, - y  + x*z)|
|                                                |
|o2 : Ideal of QQ[w..z]                          |
+------------------------------------------------+
|i3 : isMonomialIdeal I                          |
|                                                |
|o3 = false                                      |
+------------------------------------------------+
|i4 : J = ideal leadTerm I                       |
|                                                |
|             2        2                         |
|o4 = ideal (y , x*y, x )                        |
|                                                |
|o4 : Ideal of QQ[w..z]                          |
+------------------------------------------------+
|i5 : isMonomialIdeal J                          |
|                                                |
|o5 = true                                       |
+------------------------------------------------+
|i6 : K = monomialIdeal I                        |
|                                                |
|                     2        2                 |
|o6 = monomialIdeal (x , x*y, y )                |
|                                                |
|o6 : MonomialIdeal of QQ[w..z]                  |
+------------------------------------------------+
|i7 : isMonomialIdeal K                          |
|                                                |
|o7 = true                                       |
+------------------------------------------------+

See also
========

  * monomialIdeal -- make a monomial ideal

Ways to use isMonomialIdeal:
============================

  * "isMonomialIdeal(Ideal)"
  * "isMonomialIdeal(Module)"
  * "isMonomialIdeal(MonomialIdeal)"
  * "isMonomialIdeal(Thing)"

For the programmer
==================

The object isMonomialIdeal, is a method function.

isNormal
********

Description
===========

This function is a method function, defined in the core so multiple packages
can add methods to it.

See also
========

  * isNormal(Polyhedron) (Polyhedra) -- checks
    if a polytope is normal in the ambient lattice
  * isNormal(Ring) (IntegralClosure) -- determine if
    a reduced ring is normal
  * isNormal(RingElement) (AssociativeAlgebras)
    -- Determines if an element
    of a noncommutative ring is normal
  * null -- the unique member of the empty class

Ways to use isNormal:
=====================

  * isNormal(Polyhedron) (Polyhedra) -- checks
    if a polytope is normal in the ambient lattice
  * isNormal(Ring) (IntegralClosure) -- determine if
    a reduced ring is normal
  * isNormal(RingElement) (missing documentation)

For the programmer
==================

The object isNormal, is a method function.

isOpen -- whether a file or database is open
********************************************

Synopsis
========

  * Usage:
        isOpen f
  * Inputs:
      * f, a file, or a database,
  * Outputs:
      * a Boolean value,  whether f is an open file or open
        database

Description
===========

An open file is either an input file, an output file, an input output file, or
a listener.

+----------------------------------+
|i1 : f = "test-file" << "hi there"|
|                                  |
|o1 = test-file                    |
|                                  |
|o1 : File                         |
+----------------------------------+
|i2 : isOpen f                     |
|                                  |
|o2 = true                         |
+----------------------------------+
|i3 : close f                      |
|                                  |
|o3 = test-file                    |
|                                  |
|o3 : File                         |
+----------------------------------+
|i4 : isOpen f                     |
|                                  |
|o4 = false                        |
+----------------------------------+
|i5 : get "test-file"              |
|                                  |
|o5 = hi there                     |
+----------------------------------+
|i6 : removeFile "test-file"       |
+----------------------------------+

See also
========

  * openIn -- open an input file
  * openInOut -- open an input output file
  * openListener -- open a port for listening
  * close -- close a file
  * get -- get the contents of a file
  * removeFile -- remove a file

Ways to use isOpen:
===================

  * "isOpen(Database)"
  * "isOpen(File)"

For the programmer
==================

The object isOpen, is a compiled function.

isOutputFile(File) -- whether a file is open for output
*******************************************************

Synopsis
========

  * Function: isOutputFile,
  * Usage:
        isOutputFile f
  * Inputs:
      * f
  * Outputs:
      * a Boolean value,  whether f is an open output file

Description
===========

+----------------------------------+
|i1 : f = "test-file" << "hi there"|
|                                  |
|o1 = test-file                    |
|                                  |
|o1 : File                         |
+----------------------------------+
|i2 : isOutputFile f               |
|                                  |
|o2 = true                         |
+----------------------------------+
|i3 : close f                      |
|                                  |
|o3 = test-file                    |
|                                  |
|o3 : File                         |
+----------------------------------+
|i4 : isOutputFile f               |
|                                  |
|o4 = false                        |
+----------------------------------+
|i5 : get "test-file"              |
|                                  |
|o5 = hi there                     |
+----------------------------------+
|i6 : removeFile "test-file"       |
+----------------------------------+

See also
========

  * openOut -- open an output file
  * openInOut -- open an input output file
  * close -- close a file
  * get -- get the contents of a file
  * removeFile -- remove a file

Ways to use this method:
========================

  * isOutputFile(File) -- whether a file is open
    for output

isPolynomialRing -- whether something is a polynomial ring
**********************************************************

Synopsis
========

  * Usage:
        isPolynomialRing R
  * Inputs:
      * R, a thing,
  * Outputs:
      * a Boolean value, true, if R is a
        polynomial ring, and false, otherwise

Description
===========

+----------------------------------------------------------+
|i1 : isPolynomialRing CC                                  |
|                                                          |
|o1 = false                                                |
+----------------------------------------------------------+
|i2 : isPolynomialRing(ZZ/7[x,y])                          |
|                                                          |
|o2 = true                                                 |
+----------------------------------------------------------+
|i3 : isPolynomialRing(QQ[x,dx, WeylAlgebra => {x => dx}]) |
|                                                          |
|o3 = true                                                 |
+----------------------------------------------------------+
|i4 : isPolynomialRing(GF(2)[x,y, SkewCommutative => true])|
|                                                          |
|o4 = true                                                 |
+----------------------------------------------------------+
|i5 : isPolynomialRing(ZZ/101[x,y,z]/(x^2-y*z))            |
|                                                          |
|o5 = false                                                |
+----------------------------------------------------------+

Ways to use isPolynomialRing:
=============================

  * "isPolynomialRing(PolynomialRing)"
  * "isPolynomialRing(Thing)"

For the programmer
==================

The object isPolynomialRing, is a method function.

isPrime -- whether a integer or polynomial is prime
***************************************************

Synopsis
========

  * Usage:
        isPrime f
  * Inputs:
      * f, an integer, or an element in a polynomial ring,
  * Outputs:
      * a Boolean value, true, if f is either a
        prime integer or an irreducible polynomial and false,
        otherwise

Description
===========

+-----------------------------------------------------------------------------+
|i1 : ZZ/2[t];                                                                |
+-----------------------------------------------------------------------------+
|i2 : isPrime(t^2+t+1)                                                        |
|                                                                             |
|o2 = true                                                                    |
+-----------------------------------------------------------------------------+
|i3 : isPrime(t^2+1)                                                          |
|                                                                             |
|o3 = false                                                                   |
+-----------------------------------------------------------------------------+
|i4 : isPrime 101                                                             |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+
|i5 : isPrime 1581741965468191654681185746811965468118567481185674811856695018|
|                                                                             |
|o5 = true                                                                    |
|-----------------------------------------------------------------------------|
|56749                                                                        |
+-----------------------------------------------------------------------------+
|i6 : isPrime 1581741965468191654681185746811965468118567481185674811856695018|
|                                                                             |
|o6 = false                                                                   |
|-----------------------------------------------------------------------------|
|56749^2                                                                      |
+-----------------------------------------------------------------------------+

Since factor, returns factors guaranteed only to be pseudoprimes,
it may be useful to check their primality, as follows.

+-----------------------------------------------------------------------------+
|i7 : f = factor 28752093487520394720397634653456                             |
|                                                                             |
|      4                                                                      |
|o7 = 2 109*1831*3014311519*2987077659845341                                  |
|                                                                             |
|o7 : Expression of class Product                                             |
+-----------------------------------------------------------------------------+
|i8 : peek'_2 f                                                               |
|                                                                             |
|o8 = Product{Power{2, 4}, Power{109, 1}, Power{1831, 1}, Power{3014311519,   |
|     ------------------------------------------------------------------------|
|     1}, Power{2987077659845341, 1}}                                         |
+-----------------------------------------------------------------------------+
|i9 : first \ toList f                                                        |
|                                                                             |
|o9 = {2, 109, 1831, 3014311519, 2987077659845341}                            |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+
|i10 : isPrime \ oo                                                           |
|                                                                             |
|o10 = {true, true, true, true, true}                                         |
|                                                                             |
|o10 : List                                                                   |
+-----------------------------------------------------------------------------+

Primality testing for integers is handled by FLINT.

See also
========

  * factor -- factor a ring element or a ZZ-module
  * isPseudoprime -- whether an integer is
    probably prime
  * isPrime(Ideal) (MinimalPrimes) -- whether an
    ideal is prime

Ways to use isPrime:
====================

  * "isPrime(ZZ)"
  * isPrime(Ideal) (MinimalPrimes) -- whether an
    ideal is prime
  * isPrime(RingElement) (missing documentation)

For the programmer
==================

The object isPrime, is a method function with options.

isPrimitive -- whether an element is a primitive element of a finite field
**************************************************************************

Description
===========

isPrimitive(f) -- Given an element f in a quotient of a polynomial ring R over
a finite field Kwhich is itself a finite field, with the ring being finite
dimensional over the field, determine if f generates the multiplicative group
of this field.
+---------------------------+
|i1 : R = ZZ/5[t]/(t^2+t+1);|
+---------------------------+
|i2 : isPrimitive t         |
|                           |
|o2 = false                 |
+---------------------------+
|i3 : isPrimitive (t-1)     |
|                           |
|o3 = true                  |
+---------------------------+

For the programmer
==================

The object isPrimitive, is a function closure.

isPseudoprime(ZZ) -- whether an integer is probably prime
*********************************************************

Synopsis
========

  * Function: isPseudoprime,
  * Usage:
        isPseudoprime x
  * Inputs:
      * x, an integer,
  * Outputs:
      * a Boolean value,

Description
===========

Performs some trial division and then some probabilistic primality tests. If
$x$ is definitely composite, the function returns false, otherwise it is
declared probably prime, i.e. prime for most practical purposes, and the
function returns true. The chance of declaring a composite number prime is very
small. Subsequent calls to the same function do not increase the probability of
the number being prime.  In fact, there are no known numbers which are
composite, and for which this function returns true, although it is expected
that there are an infinite number of such primes.

This function calls a function in the FLINT, library.

+---------------------------------------+
|i1 : n = 1166513229502037              |
|                                       |
|o1 = 1166513229502037                  |
+---------------------------------------+
|i2 : isPseudoprime n                   |
|                                       |
|o2 = true                              |
+---------------------------------------+
|i3 : isPrime n                         |
|                                       |
|o3 = true                              |
+---------------------------------------+
|i4 : n1 = nextPrime(n+1)               |
|                                       |
|o4 = 1166513229502141                  |
+---------------------------------------+
|i5 : factor(n1^2*n)                    |
|                                       |
|                                      2|
|o5 = 1166513229502037*1166513229502141 |
|                                       |
|o5 : Expression of class Product       |
+---------------------------------------+

These functions handle numbers larger than this.  For example,

+-----------------------------------------------------------------------------+
|i6 : m = 15817419654681916546811857468119654681185674811856748118566950185674|
|                                                                             |
|o6 = 158174196546819165468118574681196546811856748118567481185669501856749   |
|-----------------------------------------------------------------------------|
|9                                                                            |
+-----------------------------------------------------------------------------+
|i7 : isPseudoprime m                                                         |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+
|i8 : isPrime m                                                               |
|                                                                             |
|o8 = true                                                                    |
+-----------------------------------------------------------------------------+
|i9 : isPrime m^2                                                             |
|                                                                             |
|o9 = false                                                                   |
+-----------------------------------------------------------------------------+
|i10 : factor m^2                                                             |
|                                                                             |
|                                                                           2 |
|o10 = 158174196546819165468118574681196546811856748118567481185669501856749  |
|                                                                             |
|o10 : Expression of class Product                                            |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i11 : ndigits = 30                                                           |
|                                                                             |
|o11 = 30                                                                     |
+-----------------------------------------------------------------------------+
|i12 : m = nextPrime(10^30)                                                   |
|                                                                             |
|o12 = 1000000000000000000000000000057                                        |
+-----------------------------------------------------------------------------+
|i13 : m1 = nextPrime (m+10^10)                                               |
|                                                                             |
|o13 = 1000000000000000000010000000083                                        |
+-----------------------------------------------------------------------------+
|i14 : m2 = nextPrime (m1 + 10^20)                                            |
|                                                                             |
|o14 = 1000000000100000000010000000229                                        |
+-----------------------------------------------------------------------------+
|i15 : isPrime m                                                              |
|                                                                             |
|o15 = true                                                                   |
+-----------------------------------------------------------------------------+
|i16 : isPrime m1                                                             |
|                                                                             |
|o16 = true                                                                   |
+-----------------------------------------------------------------------------+
|i17 : isPrime (m*m1)                                                         |
|                                                                             |
|o17 = false                                                                  |
+-----------------------------------------------------------------------------+
|i18 : isPrime(m*m*m1*m1*m2^6)                                                |
|                                                                             |
|o18 = false                                                                  |
+-----------------------------------------------------------------------------+
|i19 : elapsedTime facs = factor(m*m1)                                        |
| -- 5.08868s elapsed                                                         |
|                                                                             |
|o19 = 1000000000000000000000000000057*1000000000000000000010000000083        |
|                                                                             |
|o19 : Expression of class Product                                            |
+-----------------------------------------------------------------------------+
|i20 : facs = facs//toList/toList                                             |
|                                                                             |
|o20 = {{1000000000000000000000000000057, 1},                                 |
|      -----------------------------------------------------------------------|
|      {1000000000000000000010000000083, 1}}                                  |
|                                                                             |
|o20 : List                                                                   |
+-----------------------------------------------------------------------------+
|i21 : assert(set facs === set {{m,1}, {m1,1}})                               |
+-----------------------------------------------------------------------------+
|i22 : m3 = nextPrime (m^3)                                                   |
|                                                                             |
|o22 = 10000000000000000000000000001710000000000000000000000000097470000000000|
|      00000000000000185613                                                   |
+-----------------------------------------------------------------------------+
|i23 : elapsedTime isPrime m3                                                 |
| -- .0483693s elapsed                                                        |
|                                                                             |
|o23 = true                                                                   |
+-----------------------------------------------------------------------------+
|i24 : elapsedTime isPseudoprime m3                                           |
| -- .000114371s elapsed                                                      |
|                                                                             |
|o24 = true                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * isPrime(ZZ) -- whether a integer or polynomial is prime
  * factor(ZZ) -- factor a ring element
  * nextPrime(Number) -- compute the smallest prime greater
    than or equal to a given number

Ways to use this method:
========================

  * isPseudoprime(ZZ) -- whether an integer is
    probably prime

isQuotientModule -- whether something is evidently a quotient of a free module
******************************************************************************

Synopsis
========

  * Usage:
        isQuotientModule M
  * Inputs:
      * M, a thing,
  * Outputs:
      * a Boolean value, true, if the given
        representation of M a quotient of a free module.

Description
===========

This function checks if the module M is a quotient of its ambient,
free module by examining its matrix of generators.
+-----------------------------+
|i1 : R = ZZ/101[a,b,c];      |
+-----------------------------+
|i2 : M = R^1/(a^2,b^2,c^2)   |
|                             |
|o2 = cokernel | a2 b2 c2 |   |
|                             |
|                            1|
|o2 : R-module, quotient of R |
+-----------------------------+
|i3 : isQuotientModule M      |
|                             |
|o3 = true                    |
+-----------------------------+
The image of a map from a free module to the first generator of M yields an
equivalent module that is not presented as a quotient.
+--------------------------------------+
|i4 : f = M_{0}                        |
|                                      |
|o4 = | 1 |                            |
|                                      |
|                   1                  |
|o4 : Matrix M <-- R                   |
+--------------------------------------+
|i5 : N = image f                      |
|                                      |
|o5 = subquotient (| 1 |, | a2 b2 c2 |)|
|                                      |
|                               1      |
|o5 : R-module, subquotient of R       |
+--------------------------------------+
|i6 : M == N                           |
|                                      |
|o6 = true                             |
+--------------------------------------+
|i7 : isQuotientModule N               |
|                                      |
|o7 = false                            |
+--------------------------------------+

See also
========

  * Module _ List -- map from free module to some
    generators
  * ambient -- ambient free module of a subquotient, or ambient
    ring
  * isFreeModule -- whether something is a free module

Ways to use isQuotientModule:
=============================

  * "isQuotientModule(Module)"
  * "isQuotientModule(Thing)"

For the programmer
==================

The object isQuotientModule, is a method function.

isQuotientOf -- whether one thing is a quotient of another
**********************************************************

Ways to use isQuotientOf:
=========================

  * "isQuotientOf(Ring,QuotientRing)" -- see isQuotientOf(Ring,Ring),
    -- whether one ring is a quotient of another
  * isQuotientOf(Ring,Ring) -- whether
    one ring is a quotient of another
  * "isQuotientOf(Type,QuotientRing)" -- see isQuotientOf(Type,Ring),
    -- whether one ring is a quotient of a ring
    of a given type
  * isQuotientOf(Type,Ring) -- whether
    one ring is a quotient of a ring of a given type

For the programmer
==================

The object isQuotientOf, is a method function.

isQuotientOf(Ring,Ring) -- whether one ring is a quotient of another
********************************************************************

Synopsis
========

  * Function: isQuotientOf,

Ways to use this method:
========================

  * "isQuotientOf(Ring,QuotientRing)"
  * isQuotientOf(Ring,Ring) -- whether
    one ring is a quotient of another

isQuotientOf(Type,Ring) -- whether one ring is a quotient of a ring of a given type
***********************************************************************************

Synopsis
========

  * Function: isQuotientOf,

Ways to use this method:
========================

  * "isQuotientOf(Type,QuotientRing)"
  * isQuotientOf(Type,Ring) -- whether
    one ring is a quotient of a ring of a given type

isQuotientRing -- whether something is a quotient ring
******************************************************

Synopsis
========

  * Usage:
        isQuotientRing R
  * Inputs:
      * R, a ring,
  * Outputs:
      * a Boolean value, true, if R is a
        quotient ring, and false, otherwise

Description
===========

+-----------------------------------+
|i1 : S = ZZ/3[x,y,z];              |
+-----------------------------------+
|i2 : isQuotientRing S              |
|                                   |
|o2 = false                         |
+-----------------------------------+
|i3 : R = S/(x^2-y*z);              |
+-----------------------------------+
|i4 : isQuotientRing R              |
|                                   |
|o4 = true                          |
+-----------------------------------+
|i5 : ambient R                     |
|                                   |
|o5 = S                             |
|                                   |
|o5 : PolynomialRing                |
+-----------------------------------+
|i6 : symAlg = symmetricAlgebra R^2;|
+-----------------------------------+
|i7 : isQuotientRing symAlg         |
|                                   |
|o7 = false                         |
+-----------------------------------+
|i8 : sing = singularLocus R;       |
+-----------------------------------+
|i9 : isQuotientRing sing           |
|                                   |
|o9 = true                          |
+-----------------------------------+

See also
========

  * ambient -- ambient free module of a subquotient, or ambient
    ring

Ways to use isQuotientRing:
===========================

  * "isQuotientRing(QuotientRing)"
  * "isQuotientRing(Ring)"

For the programmer
==================

The object isQuotientRing, is a method function.

isReady(File) -- whether a file has data available for reading
**************************************************************

Synopsis
========

  * Function: isReady,
  * Usage:
        isReady f
  * Inputs:
      * a file,
  * Outputs:
      * a Boolean value, whether the input file f has data
        available for reading

Description
===========

+------------------------------+
|i1 : f = openInOut "!cat"     |
|                              |
|o1 = !cat                     |
|                              |
|o1 : File                     |
+------------------------------+
|i2 : isReady f                |
|                              |
|o2 = false                    |
+------------------------------+
|i3 : f << "hi there" << flush;|
+------------------------------+
|i4 : isReady f                |
|                              |
|o4 = false                    |
+------------------------------+

Ways to use this method:
========================

  * isReady(File) -- whether a file has data
    available for reading

isReal -- whether a number is real
**********************************

Synopsis
========

  * Usage:
        isReal x
  * Inputs:
      * x, a number,
  * Outputs:
      * a Boolean value, whether x is real

Description
===========

+--------------------+
|i1 : isReal 2.      |
|                    |
|o1 = true           |
+--------------------+
|i2 : isReal sqrt(-1)|
|                    |
|o2 = false          |
+--------------------+

Ways to use isReal:
===================

  * "isReal(CC)"
  * "isReal(Constant)"
  * "isReal(InfiniteNumber)"
  * "isReal(QQ)"
  * "isReal(RR)"
  * "isReal(RRi)"
  * "isReal(ZZ)"

For the programmer
==================

The object isReal, is a method function.

isRing -- whether something is a ring
*************************************

Synopsis
========

  * Usage:
        isRing R
  * Inputs:
      * R, a thing,
  * Outputs:
      * a Boolean value, true, if R is a
        ring, and false, otherwise

Description
===========

+----------------------------------------------------+
|i1 : isRing QQ                                      |
|                                                    |
|o1 = true                                           |
+----------------------------------------------------+
|i2 : R = QQ[x,y];                                   |
+----------------------------------------------------+
|i3 : isRing(R)                                      |
|                                                    |
|o3 = true                                           |
+----------------------------------------------------+
|i4 : isRing(R^1)                                    |
|                                                    |
|o4 = false                                          |
+----------------------------------------------------+
|i5 : isRing(GF(2,3)[x,dx, WeylAlgebra => {x => dx}])|
|                                                    |
|o5 = true                                           |
+----------------------------------------------------+

Ways to use isRing:
===================

  * "isRing(Ring)"
  * "isRing(Thing)"

For the programmer
==================

The object isRing, is a method function.

isSkewCommutative -- whether a ring has skew commuting variables
****************************************************************

Synopsis
========

  * Usage:
        isSkewCommutative R
  * Inputs:
      * R, a ring,
  * Outputs:
      * a Boolean value, true, if R has skew
        commuting variables and false, otherwise

Description
===========

+---------------------------------------------------+
|i1 : A = ZZ/3[a,b,c];                              |
+---------------------------------------------------+
|i2 : isSkewCommutative A                           |
|                                                   |
|o2 = false                                         |
+---------------------------------------------------+
|i3 : B = QQ[a..d,SkewCommutative=>{a,b}]           |
|                                                   |
|o3 = B                                             |
|                                                   |
|o3 : PolynomialRing, 2 skew commutative variable(s)|
+---------------------------------------------------+
|i4 : isSkewCommutative B                           |
|                                                   |
|o4 = true                                          |
+---------------------------------------------------+
|i5 : C = B[x,y]                                    |
|                                                   |
|o5 = C                                             |
|                                                   |
|o5 : PolynomialRing                                |
+---------------------------------------------------+
|i6 : isSkewCommutative C                           |
|                                                   |
|o6 = true                                          |
+---------------------------------------------------+
|i7 : b_C * a_C                                     |
|                                                   |
|o7 = -a*b                                          |
|                                                   |
|o7 : C                                             |
+---------------------------------------------------+
|i8 : D = B/(a*d-b*c)                               |
|                                                   |
|o8 = D                                             |
|                                                   |
|o8 : QuotientRing                                  |
+---------------------------------------------------+
|i9 : isSkewCommutative D                           |
|                                                   |
|o9 = true                                          |
+---------------------------------------------------+

See also
========

  * exterior algebras

Ways to use isSkewCommutative:
==============================

  * "isSkewCommutative(PolynomialRing)"
  * "isSkewCommutative(QuotientRing)"
  * "isSkewCommutative(Ring)"

For the programmer
==================

The object isSkewCommutative, is a method function.

isSmooth
********

Description
===========

This function is a method function, defined in the core so multiple packages
can add methods to it.

See also
========

  * isSmooth(Ideal) (Divisor) -- whether R mod the
    ideal is smooth
  * isSmooth(Polyhedron) (missing documentation)
  * isSmooth(Variety) (missing documentation)
  * isSmooth(Curve) (SpaceCurves) -- checks
    smoothness of an ideal or of a Curve
  * isSmooth(Cone) (Polyhedra) -- checks if a Cone or
    Fan is smooth
  * isSmooth(NormalToricVariety) (NormalToricVarieties)
    -- whether a normal
    toric variety is smooth
  * isSmooth(EmbeddedProjectiveVariety) (missing documentation)

Ways to use isSmooth:
=====================

  * isSmooth(Cone) (Polyhedra) -- checks if a Cone or
    Fan is smooth
  * "isSmooth(Fan)" -- see isSmooth(Cone) (Polyhedra),
    -- checks if a Cone or Fan is smooth

For the programmer
==================

The object isSmooth, is a method function with options.

isSorted -- whether a list is sorted
************************************

Synopsis
========

  * Usage:
        isSorted L
  * Inputs:
      * L, a visible list,
  * Outputs:
      * a Boolean value, whether the elements of L are in
        increasing order

Description
===========

+--------------------------------------------+
|i1 : isSorted {1,2,2,3}                     |
|                                            |
|o1 = true                                   |
+--------------------------------------------+
|i2 : isSorted {1,2,3,2}                     |
|                                            |
|o2 = false                                  |
+--------------------------------------------+
|i3 : R = ZZ/2[x,y,z, MonomialOrder => Lex]; |
+--------------------------------------------+
|i4 : isSorted (z^3, y^2, x)                 |
|                                            |
|o4 = true                                   |
+--------------------------------------------+
|i5 : R = ZZ/2[x,y,z, MonomialOrder => GLex];|
+--------------------------------------------+
|i6 : isSorted (z^3, y^2, x)                 |
|                                            |
|o6 = false                                  |
+--------------------------------------------+

See also
========

  * sort -- sort a list or columns of a matrix
  * ? -- comparison operator
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use isSorted:
=====================

  * "isSorted(VisibleList)"

For the programmer
==================

The object isSorted, is a method function with a single argument.

isSquareFree -- whether something is square free monomial ideal
***************************************************************

Synopsis
========

  * Usage:
        isSquareFree I
  * Inputs:
      * I, a monomial ideal,
  * Outputs:
      * a Boolean value, true, if I is a square
        free monomial ideal, and false,
        otherwise

Description
===========

A square free monomial ideal, is an ideal generated by
products of variables; in other words, a radical monomial ideal.
+-------------------------------------------------------------------------+
|i1 : QQ[x,y,z];                                                          |
+-------------------------------------------------------------------------+
|i2 : J = monomialIdeal(x^3*y^5*z, y^5*z^4, y^3*z^5,                      |
|               x*y*z^5, x^2*z^5, x^4*z^3, x^4*y^2*z^2,                   |
|               x^4*y^4*z)                                                |
|                                                                         |
|                     4 4    3 5    4 2 2   4 3   5 4   2 5       5   3 5 |
|o2 = monomialIdeal (x y z, x y z, x y z , x z , y z , x z , x*y*z , y z )|
|                                                                         |
|o2 : MonomialIdeal of QQ[x..z]                                           |
+-------------------------------------------------------------------------+
|i3 : isSquareFree J                                                      |
|                                                                         |
|o3 = false                                                               |
+-------------------------------------------------------------------------+
|i4 : radical J                                                           |
|                                                                         |
|o4 = monomialIdeal (x*z, y*z)                                            |
|                                                                         |
|o4 : MonomialIdeal of QQ[x..z]                                           |
+-------------------------------------------------------------------------+
|i5 : isSquareFree radical J                                              |
|                                                                         |
|o5 = true                                                                |
+-------------------------------------------------------------------------+
Square free monomial ideals correspond both to simplicial complexes and to
unions of coordinate subspaces.
+----------------------------------------------------+
|i6 : needsPackage "SimplicialComplexes"             |
|                                                    |
|o6 = SimplicialComplexes                            |
|                                                    |
|o6 : Package                                        |
+----------------------------------------------------+
|i7 : R = QQ[a..d]                                   |
|                                                    |
|o7 = R                                              |
|                                                    |
|o7 : PolynomialRing                                 |
+----------------------------------------------------+
|i8 : D = simplicialComplex {a*b*c,a*b*d,a*c*d,b*c*d}|
|                                                    |
|o8 = simplicialComplex | bcd acd abd abc |          |
|                                                    |
|o8 : SimplicialComplex                              |
+----------------------------------------------------+
|i9 : I = monomialIdeal D                            |
|                                                    |
|o9 = monomialIdeal(a*b*c*d)                         |
|                                                    |
|o9 : MonomialIdeal of R                             |
+----------------------------------------------------+
|i10 : isSquareFree I                                |
|                                                    |
|o10 = true                                          |
+----------------------------------------------------+

Implemented by Greg Smith.

See also
========

  * radical (MinimalPrimes) -- the radical of an ideal
  * associatedPrimes (PrimaryDecomposition) -- find
    associated primes
  * SimplicialComplexes -- exploring abstract
    simplicial complexes within commutative algebra

Ways to use isSquareFree:
=========================

  * "isSquareFree(Ideal)"
  * "isSquareFree(Module)"
  * "isSquareFree(MonomialIdeal)"

For the programmer
==================

The object isSquareFree, is a method function.

isSubmodule -- whether a module is evidently a submodule of a free module
*************************************************************************

Synopsis
========

  * Usage:
        isSubmodule M
  * Inputs:
      * M, a thing,
  * Outputs:
      * true, if M is evidently a submodule of a free module and
        false, otherwise

Description
===========

No computation is done -- M may be a isomorphic to a submodule of a free module
although this function will not detect it.
+-------------------------------------------------+
|i1 : R = ZZ/5[a,b,c];                            |
+-------------------------------------------------+
|i2 : M = R^3;                                    |
+-------------------------------------------------+
|i3 : isSubmodule M                               |
|                                                 |
|o3 = true                                        |
+-------------------------------------------------+
|i4 : N = ideal(a,b) * M                          |
|                                                 |
|o4 = image | a 0 0 b 0 0 |                       |
|           | 0 a 0 0 b 0 |                       |
|           | 0 0 a 0 0 b |                       |
|                                                 |
|                             3                   |
|o4 : R-module, submodule of R                    |
+-------------------------------------------------+
|i5 : isSubmodule N                               |
|                                                 |
|o5 = true                                        |
+-------------------------------------------------+
|i6 : N' = ideal(a,b) * (R^1 / ideal(a^2,b^2,c^2))|
|                                                 |
|o6 = subquotient (| a b |, | a2 b2 c2 |)         |
|                                                 |
|                               1                 |
|o6 : R-module, subquotient of R                  |
+-------------------------------------------------+
|i7 : isSubmodule N'                              |
|                                                 |
|o7 = false                                       |
+-------------------------------------------------+

Ways to use isSubmodule:
========================

  * "isSubmodule(Module)"
  * "isSubmodule(Thing)"

For the programmer
==================

The object isSubmodule, is a method function.

isSubquotient(Module,Module) -- check whether a module is a subquotient of another
**********************************************************************************

Synopsis
========

  * Function: isSubquotient,
  * Usage:
        isSubquotient(M,N)
  * Inputs:
      * M
      * N
  * Outputs:
      * a Boolean value, returns true if M is a subquotient
        module of N

Description
===========

+--------------------------------------------+
|i1 : R = QQ[a..d];                          |
+--------------------------------------------+
|i2 : N = coker matrix{{a,b},{c,d}}          |
|                                            |
|o2 = cokernel | a b |                       |
|              | c d |                       |
|                                            |
|                            2               |
|o2 : R-module, quotient of R                |
+--------------------------------------------+
|i3 : N1 = N/(a^4*N)                         |
|                                            |
|o3 = cokernel | a4 0  a b |                 |
|              | 0  a4 c d |                 |
|                                            |
|                            2               |
|o3 : R-module, quotient of R                |
+--------------------------------------------+
|i4 : M = a*N/(R*a*N_0+a*b*N)                |
|                                            |
|o4 = subquotient (| a 0 |, | 0  ab 0  a b |)|
|                  | 0 a |  | -c 0  ab c d | |
|                                            |
|                               2            |
|o4 : R-module, subquotient of R             |
+--------------------------------------------+
|i5 : isSubquotient(M,N)                     |
|                                            |
|o5 = true                                   |
+--------------------------------------------+
|i6 : isSubquotient(M,N1)                    |
|                                            |
|o6 = false                                  |
+--------------------------------------------+

Ways to use this method:
========================

  * isSubquotient(Module,Module), --
    check whether a module is a subquotient of another

isSubset -- whether one object is a subset of another
*****************************************************

Ways to use isSubset:
=====================

  * isSubset(Ideal,Ideal) -- whether one
    object is a subset of another
  * "isSubset(Ideal,Module)" -- see isSubset(Module,Module),
    -- whether one object is a subset of another
  * "isSubset(Module,Ideal)" -- see isSubset(Module,Module),
    -- whether one object is a subset of another
  * isSubset(Module,Module) -- whether
    one object is a subset of another
  * isSubset(RRi,RRi) -- subset test for
    intervals
  * isSubset(Set,Set) -- whether one object is
    a subset of another
  * "isSubset(Set,VisibleList)" -- see isSubset(Set,Set),
    -- whether one object is a subset of another
  * "isSubset(VisibleList,Set)" -- see isSubset(Set,Set),
    -- whether one object is a subset of another
  * "isSubset(VisibleList,VisibleList)" -- see isSubset(Set,Set),
    -- whether one object is a subset of another

For the programmer
==================

The object isSubset, is a method function.

isSubset(Ideal,Ideal) -- whether one object is a subset of another
******************************************************************

Synopsis
========

  * Function: isSubset,
  * Usage:
        isSubset(I,J)
  * Inputs:
      * I
      * J
  * Outputs:
      * a Boolean value, whether I is contained in J

Description
===========

+--------------------------------------+
|i1 : R = QQ[a..d];                    |
+--------------------------------------+
|i2 : I = ideal(a^2-b*c-1,a*c-1,b^3-1);|
|                                      |
|o2 : Ideal of R                       |
+--------------------------------------+
|i3 : isSubset(I^2,I)                  |
|                                      |
|o3 = true                             |
+--------------------------------------+
|i4 : isSubset(I,I^2)                  |
|                                      |
|o4 = false                            |
+--------------------------------------+
In polynomial rings, this is accomplished by computing a Gröbner basis of J and
testing whether every element of I reduces to 0 modulo I.

Ways to use this method:
========================

  * isSubset(Ideal,Ideal) -- whether one
    object is a subset of another

isSubset(Module,Module) -- whether one object is a subset of another
********************************************************************

Synopsis
========

  * Function: isSubset,
  * Usage:
        isSubset(M,N)
  * Inputs:
      * M
      * N
  * Outputs:
      * a Boolean value, whether M is contained in N

Description
===========

+--------------------------------------+
|i1 : R = QQ[x,y]                      |
|                                      |
|o1 = R                                |
|                                      |
|o1 : PolynomialRing                   |
+--------------------------------------+
|i2 : M = image matrix {{x,0},{0,y}}   |
|                                      |
|o2 = image | x 0 |                    |
|           | 0 y |                    |
|                                      |
|                             2        |
|o2 : R-module, submodule of R         |
+--------------------------------------+
|i3 : N = image matrix {{x^2,0},{-y,y}}|
|                                      |
|o3 = image | x2 0 |                   |
|           | -y y |                   |
|                                      |
|                             2        |
|o3 : R-module, submodule of R         |
+--------------------------------------+
|i4 : isSubset(N,M)                    |
|                                      |
|o4 = true                             |
+--------------------------------------+
|i5 : isSubset(M,N)                    |
|                                      |
|o5 = false                            |
+--------------------------------------+

Ways to use this method:
========================

  * "isSubset(Ideal,Module)"
  * "isSubset(Module,Ideal)"
  * isSubset(Module,Module) -- whether
    one object is a subset of another

isSubset(RRi,RRi) -- subset test for intervals
**********************************************

Synopsis
========

  * Function: isSubset,
  * Usage:
        x = isSubset(I,J)
  * Inputs:
      * I, a real interval,
      * J, a real interval,
  * Outputs:
      * x, a Boolean value,

Description
===========

Returns true if interval I is a subset of interval J.

See also
========

  * isMember -- test membership in a list or set

Ways to use this method:
========================

  * isSubset(RRi,RRi) -- subset test for
    intervals

isSubset(Set,Set) -- whether one object is a subset of another
**************************************************************

Synopsis
========

  * Function: isSubset,
  * Usage:
        isSubset(x,y)
  * Inputs:
      * x, a set, or a list,
      * y, a set, or a list,
  * Outputs:
      * a Boolean value, whether every element of x is in y

Description
===========

+--------------------------------+
|i1 : isSubset(set{a},set{a,b,c})|
|                                |
|o1 = true                       |
+--------------------------------+
|i2 : isSubset({a},set{a,b,c})   |
|                                |
|o2 = true                       |
+--------------------------------+
|i3 : isSubset({a,a},{a,b,c})    |
|                                |
|o3 = true                       |
+--------------------------------+

See also
========

  * Set -- the class of all sets

Ways to use this method:
========================

  * isSubset(Set,Set) -- whether one object is
    a subset of another
  * "isSubset(Set,VisibleList)"
  * "isSubset(VisibleList,Set)"
  * "isSubset(VisibleList,VisibleList)"

isSurjective -- whether a map is surjective
*******************************************

See also
========

  * isInjective -- whether a map is injective

Ways to use isSurjective:
=========================

  * "isSurjective(Matrix)"

For the programmer
==================

The object isSurjective, is a method function.

isTable -- whether something is a list of lists of equal length
***************************************************************

Synopsis
========

  * Usage:
        isTable t
  * Inputs:
      * t, a thing,
  * Outputs:
      * b, a Boolean value, whether or not $t$ is a table

Description
===========

+------------------------------+
|i1 : isTable {{1,2,3},{4,5,6}}|
|                              |
|o1 = true                     |
+------------------------------+
|i2 : isTable {{1,2,3},{4,5}}  |
|                              |
|o2 = false                    |
+------------------------------+

Caveat
======

It is intrinsically impossible to represent a $0\times k$ matrix as a list of
lists.

See also
========

  * applyTable -- apply a function to each element of a
    table
  * table -- make a table from a binary function
  * subtable -- extract a subtable from a table
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

For the programmer
==================

The object isTable, is a function closure.

isUnit -- whether a ring element is a unit
******************************************

Synopsis
========

  * Usage:
        isUnit r
  * Inputs:
      * r, a ring element,
  * Outputs:
      * a Boolean value, true, if the ring element,
        r generates an ideal containing the
        multiplicative identity 1 and false otherwise

Description
===========

+---------------------------------+
|i1 : R = QQ[z]/(z^2+1);          |
+---------------------------------+
|i2 : isUnit z                    |
|                                 |
|o2 = true                        |
+---------------------------------+
|i3 : S = QQ[x,y]/(1-(x-1)*(y-1));|
+---------------------------------+
|i4 : isUnit (x^2 - 2*x + 1)      |
|                                 |
|o4 = true                        |
+---------------------------------+
|i5 : isUnit x                    |
|                                 |
|o5 = false                       |
+---------------------------------+

Ways to use isUnit:
===================

  * "isUnit(Number)"
  * "isUnit(RingElement)"
  * "isUnit(ZZ)"

For the programmer
==================

The object isUnit, is a method function.

isVeryAmple
***********

Description
===========

This function is a method function, defined in the core so multiple packages
can add methods to it.

See also
========

  * isVeryAmple(WeilDivisor) (Divisor), --
    whether a divisor is very ample.
  * isVeryAmple(Polyhedron) (Polyhedra), --
    checks if the Polyhedron is very ample
  * isVeryAmple(ToricVectorBundleKlyachko) (PositivityToricBundles)
    -- computes up to which order a
    toric vector bundle separates jets
  * isVeryAmple(ToricDivisor) (NormalToricVarieties)
    -- whether a
    torus-invariant Weil divisor is very ample

Ways to use isVeryAmple:
========================

  * isVeryAmple(Polyhedron) (Polyhedra), --
    checks if the Polyhedron is very ample

For the programmer
==================

The object isVeryAmple, is a method function with options.

isWellDefined -- whether a map is well defined
**********************************************

Synopsis
========

  * Usage:
        isWellDefined f
  * Inputs:
      * f, a matrix, or a ring map,
  * Outputs:
      * a Boolean value, whether f is a well-defined map

Description
===========

In order to check whether a matrix, whose source module is not free, is well
defined, then a Gröbner basis computation will probably be required.
+--------------------------------------------------+
|i1 : R = QQ[a..d];                                |
+--------------------------------------------------+
|i2 : f = map(R^1,coker vars R,{{1_R}})            |
|                                                  |
|o2 = | 1 |                                        |
|                                                  |
|o2 : Matrix                                       |
+--------------------------------------------------+
|i3 : isWellDefined f                              |
|                                                  |
|o3 = false                                        |
+--------------------------------------------------+
|i4 : isWellDefined map(coker vars R, R^1, {{1_R}})|
|                                                  |
|o4 = true                                         |
+--------------------------------------------------+
In order to check whether a ring map is well defined, it is often necessary to
check that the image of an ideal under a related ring map is zero.  This often
requires a Gröbner basis as well.
+--------------------------------+
|i5 : A = ZZ/5[a]                |
|                                |
|o5 = A                          |
|                                |
|o5 : PolynomialRing             |
+--------------------------------+
|i6 : factor(a^3-a-2)            |
|                                |
|       3                        |
|o6 = (a  - a - 2)               |
|                                |
|o6 : Expression of class Product|
+--------------------------------+
|i7 : B = A/(a^3-a-2);           |
+--------------------------------+
|i8 : isWellDefined map(A,B)     |
|                                |
|o8 = false                      |
+--------------------------------+
|i9 : isWellDefined map(B,A)     |
|                                |
|o9 = true                       |
+--------------------------------+

See also
========

  * map -- make a map

Ways to use isWellDefined:
==========================

  * "isWellDefined(Matrix)"
  * "isWellDefined(RingMap)"
  * isWellDefined(CoherentSheaf) (missing documentation)
  * isWellDefined(Cone) (Polyhedra) -- Checks
    whether a polyhedral object is well-defined.
  * "isWellDefined(Fan)" -- see isWellDefined(Cone) (Polyhedra),
    -- Checks whether a polyhedral object
    is well-defined.
  * "isWellDefined(PolyhedralComplex)" -- see isWellDefined(Cone) (Polyhedra),
    -- Checks whether a polyhedral object
    is well-defined.
  * "isWellDefined(PolyhedralObject)" -- see isWellDefined(Cone) (Polyhedra),
    -- Checks whether a polyhedral object
    is well-defined.
  * "isWellDefined(Polyhedron)" -- see isWellDefined(Cone) (Polyhedra),
    -- Checks whether a polyhedral object
    is well-defined.
  * isWellDefined(SheafMap) (missing documentation)
  * isWellDefined(Variety) (missing documentation)

For the programmer
==================

The object isWellDefined, is a method function.

Iterator -- class for iterators
*******************************

Description
===========

This is a class designed to simplify writing iterator, methods.
Each instance is a nullary FunctionClosure, that serves
as the next, method for the iterator.

+-----------------------------------------------------------------------------+
|i1 : iter = iterator {1, 2, 3}                                               |
|                                                                             |
|o1 = iter                                                                    |
|                                                                             |
|o1 : Iterator                                                                |
+-----------------------------------------------------------------------------+
|i2 : code iter                                                               |
|                                                                             |
|o2 = ../../../../../Macaulay2/m2/iterators.m2:22:4-27:15: --source code:     |
|         () -> (                                                             |
|             if i >= #x then StopIteration                                   |
|             else (                                                          |
|                 r := x#i;                                                   |
|                 i += 1;                                                     |
|                 r)))                                                        |
|     | symbol  class  value      location of symbol                          |
|     | ------  -----  -----      ------------------                          |
|     | i       ZZ     0          ../../../../../Macaulay2/m2/iterators.m2:21:|
|     | x       List   {1, 2, 3}  ../../../../../Macaulay2/m2/iterators.m2:20:|
|-----------------------------------------------------------------------------|
|                                                                             |
|4-21:5                                                                       |
|24-20:25                                                                     |
+-----------------------------------------------------------------------------+

Each call of next iter is equivalent to iter().

+------------------+
|i3 : next iter    |
|                  |
|o3 = 1            |
+------------------+
|i4 : iter()       |
|                  |
|o4 = 2            |
+------------------+
|i5 : next iter    |
|                  |
|o5 = 3            |
+------------------+
|i6 : iter()       |
|                  |
|o6 = StopIteration|
|                  |
|o6 : Symbol       |
+------------------+

Every Iterator object is an iterator for itself.

+----------------------------------+
|i7 : primes = Iterator (          |
|         p := 2;                  |
|         () -> (                  |
|             r := p;              |
|             p = nextPrime(p + 1);|
|             r));                 |
+----------------------------------+
|i8 : iterator primes === primes   |
|                                  |
|o8 = true                         |
+----------------------------------+

However, we cannot "rewind" an Iterator object.  Every time that it is iterated
upon using for, scan, etc., iteration will resume
where it left off previously.

+------------------------------------------------------+
|i9 : for p in primes list if p > 20 then break else p |
|                                                      |
|o9 = {2, 3, 5, 7, 11, 13, 17, 19}                     |
|                                                      |
|o9 : List                                             |
+------------------------------------------------------+
|i10 : for p in primes list if p > 20 then break else p|
|                                                      |
|o10 = {}                                              |
|                                                      |
|o10 : List                                            |
+------------------------------------------------------+

Contrast this with most other classes with the iterator, method
installed, like, strings, for which a new Iterator object is created every time
it is iterated upon, and so iteration starts over from the beginning

+---------------------------------------------+
|i11 : s = "Hello, world!"                    |
|                                             |
|o11 = Hello, world!                          |
+---------------------------------------------+
|i12 : for c in s list c                      |
|                                             |
|o12 = {H, e, l, l, o, ,,  , w, o, r, l, d, !}|
|                                             |
|o12 : List                                   |
+---------------------------------------------+
|i13 : for c in s list c                      |
|                                             |
|o13 = {H, e, l, l, o, ,,  , w, o, r, l, d, !}|
|                                             |
|o13 : List                                   |
+---------------------------------------------+

See also
========

  * iterator -- get an iterator
  * next -- get the next object from an iterator
  * StopIteration -- stop iteration

Functions and methods returning an iterator:
============================================

  * "accumulate(Function,Thing)" -- see accumulate, -- apply
    a binary operator repeatedly
  * "accumulate(Function,Thing,Thing)" -- see accumulate, --
    apply a binary operator repeatedly
  * apply(Thing,Function) -- apply a
    function to an object with an iterator
  * select(Thing,Function) -- select
    elements from an object with an iterator

Methods that use an iterator:
=============================

  * "iterator(Iterator)" -- see iterator, -- get an iterator
  * Iterator | Iterator (missing documentation)
  * "next(Iterator)" -- see next, -- get the next object from an
    iterator

For the programmer
==================

The object Iterator, is a self initializing type,
with ancestor classes FunctionClosure,
< Function < Thing.

iterator -- get an iterator
***************************

Synopsis
========

  * Usage:
        iterator x
  * Inputs:
      * x, a thing,
  * Outputs:
      * a thing, likely an Iterator,;

Description
===========

An iterator is an object that is used to traverse through x. Usually, but not
necessarily, this will be an instance of the Iterator, class.

+------------------------------+
|i1 : iter = iterator {1, 2, 3}|
|                              |
|o1 = iter                     |
|                              |
|o1 : Iterator                 |
+------------------------------+

The class of an iterator should have a next, method installed that
gets the next element of x.

+--------------+
|i2 : next iter|
|              |
|o2 = 1        |
+--------------+
|i3 : next iter|
|              |
|o3 = 2        |
+--------------+
|i4 : next iter|
|              |
|o4 = 3        |
+--------------+

If x contains only a finite number of elements, then next, should
return the symbol StopIteration, after exhausting them
all.

+------------------+
|i5 : next iter    |
|                  |
|o5 = StopIteration|
|                  |
|o5 : Symbol       |
+------------------+

Instances of classes with this method installed can be used like lists in
for, loops and scan.

+--------------------------------------------------------------------------+
|i6 : lookup(iterator, String)                                             |
|                                                                          |
|o6 = FunctionClosure[../../../../../Macaulay2/m2/iterators.m2:20:24-27:16]|
|                                                                          |
|o6 : FunctionClosure                                                      |
+--------------------------------------------------------------------------+
|i7 : for i in "foo" list i                                                |
|                                                                          |
|o7 = {f, o, o}                                                            |
|                                                                          |
|o7 : List                                                                 |
+--------------------------------------------------------------------------+
|i8 : scan("foo", print)                                                   |
|f                                                                         |
|o                                                                         |
|o                                                                         |
+--------------------------------------------------------------------------+

They can also be passed to apply, and select.  In
each case, an Iterator, object will be returned that is an
iterator for itself.

+----------------------------------+
|i9 : apply("foo", toUpper)        |
|                                  |
|o9 = (F, O, O)                    |
|                                  |
|o9 : Sequence                     |
+----------------------------------+
|i10 : for i in oo list i          |
|                                  |
|o10 = {F, O, O}                   |
|                                  |
|o10 : List                        |
+----------------------------------+
|i11 : select("foo", i -> i == "o")|
|                                  |
|o11 = iterator "foo"              |
|                                  |
|o11 : Iterator                    |
+----------------------------------+
|i12 : for i in oo list i          |
|                                  |
|o12 = {o, o}                      |
|                                  |
|o12 : List                        |
+----------------------------------+

See also
========

  * Iterator -- class for iterators
  * next -- get the next object from an iterator
  * StopIteration -- stop iteration

Ways to use iterator:
=====================

  * "iterator(Iterator)"
  * "iterator(String)"
  * "iterator(VisibleList)"

For the programmer
==================

The object iterator, is a method function with a single argument.

Jacobian
********

Description
===========

This symbol is defined in the core so it can be used as the name of an optional
argument by multiple packages.

See also
========

  * ReesAlgebra -- Compute Rees algebras and their
    invariants

Functions with optional argument named Jacobian:
================================================

  * reesAlgebra(...,Jacobian=>...) (missing documentation)
  * "reesIdeal(...,Jacobian=>...)" -- see reesIdeal (ReesAlgebra),
    -- Compute the defining ideal of the Rees Algebra
  * "specialFiber(...,Jacobian=>...)" -- see specialFiber (ReesAlgebra),
    -- Special fiber of a blowup
  * "specialFiberIdeal(...,Jacobian=>...)" -- see specialFiberIdeal (ReesAlgebra),
    -- Special fiber of a blowup

For the programmer
==================

The object Jacobian, is a symbol.

jacobian -- the Jacobian matrix of partial derivatives
******************************************************

See also
========

  * diff -- differentiate or take difference
  * contract -- contract one matrix by another

Ways to use jacobian:
=====================

  * jacobian(Ideal) -- the Jacobian matrix of the
    generators of an ideal
  * jacobian(Matrix) -- the matrix of partial
    derivatives of polynomials in a matrix
  * jacobian(Ring) -- the Jacobian matrix of the
    polynomials defining a quotient ring
  * jacobian(RingElement) (missing documentation)

For the programmer
==================

The object jacobian, is a method function.

jacobian(Ideal) -- the Jacobian matrix of the generators of an ideal
********************************************************************

Synopsis
========

  * Function: jacobian,
  * Usage:
        jacobian I
  * Inputs:
      * I,  in a polynomial ring
  * Outputs:
      * a matrix, the Jacobian matrix of partial derivatives of
        the generators of I

Description
===========

This is identical to jacobian generators I.  See jacobian(Matrix),
for more information.
+----------------------------------+
|i1 : R = QQ[x,y,z];               |
+----------------------------------+
|i2 : I = ideal(y^2-x*(x-1)*(x-13))|
|                                  |
|              3      2    2       |
|o2 = ideal(- x  + 14x  + y  - 13x)|
|                                  |
|o2 : Ideal of R                   |
+----------------------------------+
|i3 : jacobian I                   |
|                                  |
|o3 = {1} | -3x2+28x-13 |          |
|     {1} | 2y          |          |
|     {1} | 0           |          |
|                                  |
|             3      1             |
|o3 : Matrix R  <-- R              |
+----------------------------------+
If the ring of I is a polynomial ring over a polynomial ring, then
indeterminates in the coefficient ring are treated as constants.
+--------------------------------------+
|i4 : R = ZZ[a,b,c][x,y,z]             |
|                                      |
|o4 = R                                |
|                                      |
|o4 : PolynomialRing                   |
+--------------------------------------+
|i5 : jacobian ideal(a*y*z+b*x*z+c*x*y)|
|                                      |
|o5 = {1, 0} | cy+bz |                 |
|     {1, 0} | cx+az |                 |
|     {1, 0} | bx+ay |                 |
|                                      |
|             3      1                 |
|o5 : Matrix R  <-- R                  |
+--------------------------------------+

Ways to use this method:
========================

  * jacobian(Ideal) -- the Jacobian matrix of the
    generators of an ideal

jacobian(Matrix) -- the matrix of partial derivatives of polynomials in a matrix
********************************************************************************

Synopsis
========

  * Function: jacobian,
  * Usage:
        jacobian f
  * Inputs:
      * f,  with one row
  * Outputs:
      * a matrix, the Jacobian matrix of partial derivatives of
        the polynomial entries of f

Description
===========

If f is a 1 by m matrix over a polynomial ring R with n indeterminates, then
the resulting matrix of partial derivatives has dimensions n by m, and the
(i,j) entry is the partial derivative of the j-th entry of f by the i-th
indeterminate of the ring.

If the ring of f is a quotient polynomial ring S/J, then only the derivatives
of the given entries of f are computed and NOT the derivatives of elements of
J.
+-------------------------------------+
|i1 : R = QQ[x,y,z];                  |
+-------------------------------------+
|i2 : f = matrix{{y^2-x*(x-1)*(x-13)}}|
|                                     |
|o2 = | -x3+14x2+y2-13x |             |
|                                     |
|             1      1                |
|o2 : Matrix R  <-- R                 |
+-------------------------------------+
|i3 : jacobian f                      |
|                                     |
|o3 = {1} | -3x2+28x-13 |             |
|     {1} | 2y          |             |
|     {1} | 0           |             |
|                                     |
|             3      1                |
|o3 : Matrix R  <-- R                 |
+-------------------------------------+
If the ring of f is a polynomial ring over a polynomial ring, then
indeterminates in the coefficient ring are treated as constants.
+----------------------------------------------------+
|i4 : R = ZZ[a,b,c][x,y,z]                           |
|                                                    |
|o4 = R                                              |
|                                                    |
|o4 : PolynomialRing                                 |
+----------------------------------------------------+
|i5 : jacobian matrix{{a*x+b*y^2+c*z^3, a*x*y+b*x*z}}|
|                                                    |
|o5 = {1, 0} | a    ay+bz |                          |
|     {1, 0} | 2by  ax    |                          |
|     {1, 0} | 3cz2 bx    |                          |
|                                                    |
|             3      2                               |
|o5 : Matrix R  <-- R                                |
+----------------------------------------------------+

Ways to use this method:
========================

  * jacobian(Matrix) -- the matrix of partial
    derivatives of polynomials in a matrix

jacobian(Ring) -- the Jacobian matrix of the polynomials defining a quotient ring
*********************************************************************************

Synopsis
========

  * Function: jacobian,
  * Usage:
        jacobian R
  * Inputs:
      * R,  a quotient of a polynomial ring
  * Outputs:
      * a matrix, the Jacobian matrix of partial derivatives of
        the presentation matrix of R

Description
===========

This is identical to jacobian presentation R, except that the resulting matrix
is over the ring R.  See jacobian(Matrix), for more
information.
+---------------------------------+
|i1 : R = QQ[x,y,z]/(y^2-x^3-x^7);|
+---------------------------------+
|i2 : jacobian R                  |
|                                 |
|o2 = {1} | -7x6-3x2 |            |
|     {1} | 2y       |            |
|     {1} | 0        |            |
|                                 |
|             3      1            |
|o2 : Matrix R  <-- R             |
+---------------------------------+
If the ring R is a (quotient of a) polynomial ring over a polynomial ring, then
the top set of indeterminates is used, on the top set of quotients:
+---------------------------------+
|i3 : A = ZZ[a,b,c]/(a^2+b^2+c^2);|
+---------------------------------+
|i4 : R = A[x,y,z]/(a*x+b*y+c*z-1)|
|                                 |
|o4 = R                           |
|                                 |
|o4 : QuotientRing                |
+---------------------------------+
|i5 : jacobian R                  |
|                                 |
|o5 = {1, 0} | a |                |
|     {1, 0} | b |                |
|     {1, 0} | c |                |
|                                 |
|             3      1            |
|o5 : Matrix R  <-- R             |
+---------------------------------+

Ways to use this method:
========================

  * jacobian(Ring) -- the Jacobian matrix of the
    polynomials defining a quotient ring

join -- join lists, sequences, and iterable objects
***************************************************

Synopsis
========

  * Usage:
        join(A, B, ...)
  * Inputs:
      * A, a basic list,
      * B, a basic list, or any instance of a class  with the
        iterator, method installed
  * Outputs:
      * Z, a basic list, or an iterator,

Description
===========

join(A, B, ...) joins the elements of the lists or sequences A, B, ... into a
single list or sequence. The inputs may belong to different classes; the class
of the result will match the class of the first argument passed to join.

+--------------------------------------------+
|i1 : join( {1,2,3}, (4,5,6), (7,8,9) )      |
|                                            |
|o1 = {1, 2, 3, 4, 5, 6, 7, 8, 9}            |
|                                            |
|o1 : List                                   |
+--------------------------------------------+
|i2 : join( (1,2,3), {4,5,6}, {7}, (8,9,10) )|
|                                            |
|o2 = (1, 2, 3, 4, 5, 6, 7, 8, 9, 10)        |
|                                            |
|o2 : Sequence                               |
+--------------------------------------------+

The operator |, is a convenient shorthand for joining two inputs of
the same class.

+-----------------------+
|i3 : {1,2,3} | {4,5,6} |
|                       |
|o3 = {1, 2, 3, 4, 5, 6}|
|                       |
|o3 : List              |
+-----------------------+
|i4 : (1,2,3) | (4,5,6) |
|                       |
|o4 = (1, 2, 3, 4, 5, 6)|
|                       |
|o4 : Sequence          |
+-----------------------+

If the first argument is a list or sequence and any later arguments are
instances of a class with the iterator, method installed, then
these instances are converted to sequences and are then joined.

+----------------------------------------+
|i5 : join({1, 2, 3}, iterator {4, 5, 6})|
|                                        |
|o5 = {1, 2, 3, 4, 5, 6}                 |
|                                        |
|o5 : List                               |
+----------------------------------------+

If the first argument is not a list or sequence, then an Iterator,
object is returned that iterates through each argument sequentially,
provided that each argument is an iterable object.

+---------------------------------------------+
|i6 : join(iterator {1, 2, 3}, {4, 5, 6})     |
|                                             |
|o6 = iterator (iterator {1, 2, 3}, {4, 5, 6})|
|                                             |
|o6 : Iterator                                |
+---------------------------------------------+
|i7 : toList oo                               |
|                                             |
|o7 = {1, 2, 3, 4, 5, 6}                      |
|                                             |
|o7 : List                                    |
+---------------------------------------------+

See also
========

  * concatenate -- join strings
  * demark -- insert a string between elements of a list of
    strings
  * flatten -- flatten a nested list or a matrix
  * mingle -- mingle elements of several lists
  * List | List -- join lists, sequences or arrays
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

For the programmer
==================

The object join, is a compiled function.

Jupyter -- top level printing method used in the Jupyter kernel
***************************************************************

Description
===========

The mode allows for a more semantic output, with input, STDOUT, value and class
clearly delimited.

See also
========

  * Standard -- the standard top level printing method
  * TeXmacs -- the TeXmacs top level printing method
  * WebApp -- the web app top level printing method

For the programmer
==================

The object Jupyter, is a symbol.

KeepFiles -- whether to keep temporary files
********************************************

Functions with optional argument named KeepFiles:
=================================================

  * "runProgram(...,KeepFiles=>...)" -- see runProgram, --
    run an external program

For the programmer
==================

The object KeepFiles, is a symbol.

kernel -- kernel of a ringmap, matrix, or chain complex
*******************************************************

Ways to use kernel:
===================

  * kernel(ChainComplexMap) -- kernel of a
    chain complex map
  * "kernel(GradedModuleMap)" -- see kernel(ChainComplexMap),
    -- kernel of a chain complex map
  * kernel(Matrix) -- kernel of a matrix
  * "kernel(RingElement)" -- see kernel(Matrix), --
    kernel of a matrix
  * kernel(RingMap) -- kernel of a ringmap
  * kernel(SheafMap) (missing documentation)

For the programmer
==================

The object kernel, is a method function with options.

kernel(...,SubringLimit=>...)
*****************************

Description
===========

SubringLimit => n -- an option for kernel, which causes the
computation of the kernel of a ring map to stop after n elements have been
discovered.

Further information
===================

  * Default value: infinity,
  * Function: kernel, -- kernel of a ringmap, matrix, or chain
    complex
  * Option key: SubringLimit, -- stop after finding enough
    elements of a subring

Functions with optional argument named SubringLimit:
====================================================

  * "gb(...,SubringLimit=>...)" -- see gb, -- compute a Gröbner basis
  * kernel(...,SubringLimit=>...)

kernel(ChainComplexMap) -- kernel of a chain complex map
********************************************************

Synopsis
========

  * Function: kernel,
  * Usage:
        kernel f
  * Inputs:
      * f, a map of chain complexes C --> D
  * Optional inputs,:
      * SubringLimit, =>
        ..., default value infinity,
  * Outputs:
      * a chain complex, the kernel of f

Description
===========

If f is a graded module map, then the result will be a
graded module.

+------------------------------------------+
|i1 : R = QQ[a..d]                         |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : I = ideal(a^3,b^3,c^3)               |
|                                          |
|             3   3   3                    |
|o2 = ideal (a , b , c )                   |
|                                          |
|o2 : Ideal of R                           |
+------------------------------------------+
|i3 : C = res coker gens I                 |
|                                          |
|      1      3      3      1              |
|o3 = R  <-- R  <-- R  <-- R  <-- 0        |
|                                          |
|     0      1      2      3      4        |
|                                          |
|o3 : ChainComplex                         |
+------------------------------------------+
|i4 : D = res coker gens (I + ideal(a*b*c))|
|                                          |
|      1      4      6      3              |
|o4 = R  <-- R  <-- R  <-- R  <-- 0        |
|                                          |
|     0      1      2      3      4        |
|                                          |
|o4 : ChainComplex                         |
+------------------------------------------+
|i5 : F = extend(D,C,map(D_0,C_0,1))       |
|                                          |
|          1             1                 |
|o5 = 0 : R  <--------- R  : 0             |
|               | 1 |                      |
|                                          |
|          4                     3         |
|     1 : R  <----------------- R  : 1     |
|               {3} | 1 0 0 |              |
|               {3} | 0 1 0 |              |
|               {3} | 0 0 0 |              |
|               {3} | 0 0 1 |              |
|                                          |
|          6                     3         |
|     2 : R  <----------------- R  : 2     |
|               {5} | 0 0 0 |              |
|               {5} | 0 0 0 |              |
|               {5} | 0 0 0 |              |
|               {6} | 1 0 0 |              |
|               {6} | 0 1 0 |              |
|               {6} | 0 0 1 |              |
|                                          |
|          3                   1           |
|     3 : R  <--------------- R  : 3       |
|               {7} | c2  |                |
|               {7} | -b2 |                |
|               {7} | a2  |                |
|                                          |
|     4 : 0 <----- 0 : 4                   |
|              0                           |
|                                          |
|o5 : ChainComplexMap                      |
+------------------------------------------+

See also
========

  * syz -- the syzygy matrix
  * genericSkewMatrix -- make a generic skew
    symmetric matrix of variables

Ways to use this method:
========================

  * kernel(ChainComplexMap) -- kernel of a
    chain complex map
  * "kernel(GradedModuleMap)"

kernel(Matrix) -- kernel of a matrix
************************************

Synopsis
========

  * Function: kernel,
  * Usage:
        kernel f
  * Inputs:
      * f, a map of modules M --> N
  * Optional inputs,:
      * SubringLimit, =>
        ..., default value infinity,
  * Outputs:
      * a module, the kernel of f, a submodule of M

Description
===========

If f is a ring element, then it will be interpreted as a
one by one matrix.

The kernel is the submodule of M of all elements mapping to zero under f. Over
polynomial rings, this is computed using a Gröbner basis computation.
+---------------------------------+
|i1 : R = ZZ/32003[vars(0..10)]   |
|                                 |
|o1 = R                           |
|                                 |
|o1 : PolynomialRing              |
+---------------------------------+
|i2 : M = genericSkewMatrix(R,a,5)|
|                                 |
|o2 = | 0  a  b  c  d |           |
|     | -a 0  e  f  g |           |
|     | -b -e 0  h  i |           |
|     | -c -f -h 0  j |           |
|     | -d -g -i -j 0 |           |
|                                 |
|             5      5            |
|o2 : Matrix R  <-- R             |
+---------------------------------+
|i3 : ker M                       |
|                                 |
|o3 = image {1} | gh-fi+ej  |     |
|           {1} | -dh+ci-bj |     |
|           {1} | df-cg+aj  |     |
|           {1} | -de+bg-ai |     |
|           {1} | ce-bf+ah  |     |
|                                 |
|                             5   |
|o3 : R-module, submodule of R    |
+---------------------------------+

See also
========

  * syz -- the syzygy matrix
  * genericSkewMatrix -- make a generic skew
    symmetric matrix of variables

Ways to use this method:
========================

  * kernel(Matrix) -- kernel of a matrix
  * "kernel(RingElement)"

kernel(RingMap) -- kernel of a ringmap
**************************************

Synopsis
========

  * Function: kernel,
  * Usage:
        kernel f
  * Inputs:
      * f, R --> S
  * Optional inputs,:
      * SubringLimit, =>
        an integer, default value infinity, stop the computation
        after this many elements of the kernel have been found
  * Outputs:
      * an ideal, an ideal of R

Description
===========

+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..d];                                                           |
+-----------------------------------------------------------------------------+
|i2 : S = QQ[s,t];                                                            |
+-----------------------------------------------------------------------------+
|i3 : F = map(S,R,{s^3, s^2*t, s*t^2, t^3})                                   |
|                                                                             |
|                  3   2      2   3                                           |
|o3 = map (S, R, {s , s t, s*t , t })                                         |
|                                                                             |
|o3 : RingMap S <-- R                                                         |
+-----------------------------------------------------------------------------+
|i4 : ker F                                                                   |
|                                                                             |
|             2                    2                                          |
|o4 = ideal (c  - b*d, b*c - a*d, b  - a*c)                                   |
|                                                                             |
|o4 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i5 : G = map(S,R,{s^5, s^3*t^2-t, s*t-s, t^5})                               |
|                                                                             |
|                  5   3 2                5                                   |
|o5 = map (S, R, {s , s t  - t, s*t - s, t })                                 |
|                                                                             |
|o5 : RingMap S <-- R                                                         |
+-----------------------------------------------------------------------------+
|i6 : ker(G, SubringLimit=>1)                                                 |
|                                                                             |
|            2 10      2   7     2 7      2 2 4     3 5         6       3 3   |
|o6 = ideal(a c   + 10a b*c  - 5a c  + 25a b c  + 2a c  - 5a*b*c  - 5a*b c  + |
|     ------------------------------------------------------------------------|
|         6      5      2 3       3   2       2 3       4      2 2      3 2   |
|     5a*c  - a*b  + 10a b c - 15a b*c  - 5a*b c  - 5a*b  + 25a b c - 5a c  - |
|     ------------------------------------------------------------------------|
|      5    4        3      2           2     2                               |
|     c  + a  - 10a*b  + 20a b*c - 10a*b  + 5a c - 5a*b - a)                  |
|                                                                             |
|o6 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
In the case when everything is homogeneous, Hilbert functions are used to speed
up the computations.

Caveat
======

It should be possible to interrupt the computation and restart it, but this has
not yet been implemented.

See also
========

  * substitution and maps between rings
  * elimination of variables
  * monomialCurveIdeal -- make the ideal of a
    monomial curve

Ways to use this method:
========================

  * kernel(RingMap) -- kernel of a ringmap

Keyword -- the class of all keywords
************************************

Description
===========

Keywords are symbols that are treated specially by the system while parsing
user input.  Some of them, such as and, consist of alphanumeric
characters and look just like ordinary symbols.  Others, such as ==>,
consist of special characters and are called operators.

See also
========

  * precedence of operators

Methods that use a keyword:
===========================

  * "? Keyword" -- see ? Symbol, -- view brief documentation of
    a symbol
  * "dictionary(Keyword)" -- see dictionary, -- determine the
    dictionary to which a symbol belongs

For the programmer
==================

The object Keyword, is a type, with ancestor
classes Symbol, < Thing.

kill -- kill a process
**********************

Description
===========

kill f -- kill the process associated with the file f.

Ways to use kill:
=================

  * "kill(File)"
  * kill(ZZ) -- kill a process

For the programmer
==================

The object kill, is a compiled function.

kill(ZZ) -- kill a process
**************************

Synopsis
========

  * Function: kill,
  * Usage:
        kill n
  * Inputs:
      * n,
  * Consequences:
      * the process with id number n is killed

Ways to use this method:
========================

  * kill(ZZ) -- kill a process

koszul -- Koszul complex or specific matrix in the Koszul complex
*****************************************************************

Description
===========

Returns either the entire Koszul complex, or a specific matrix in the Koszul
complex.

See also
========

  * eagonNorthcott -- Eagon-Northcott
    complex of a matrix of linear forms

Ways to use koszul:
===================

  * koszul(Matrix) -- the Koszul complex
  * koszul(ZZ,Matrix) -- a differential in a
    Koszul complex

For the programmer
==================

The object koszul, is a method function.

koszul(Matrix) -- the Koszul complex
************************************

Synopsis
========

  * Function: koszul,
  * Usage:
        g = koszul f
  * Inputs:
      * f, a 1 by n matrix
  * Outputs:
      * g, the Koszul complex of the matrix f

Description
===========

+-----------------------------------+
|i1 : R = QQ[x_1..x_4];             |
+-----------------------------------+
|i2 : f = matrix{{x_1..x_4}}        |
|                                   |
|o2 = | x_1 x_2 x_3 x_4 |           |
|                                   |
|             1      4              |
|o2 : Matrix R  <-- R               |
+-----------------------------------+
|i3 : C = koszul f                  |
|                                   |
|      1      4      6      4      1|
|o3 = R  <-- R  <-- R  <-- R  <-- R |
|                                   |
|     0      1      2      3      4 |
|                                   |
|o3 : ChainComplex                  |
+-----------------------------------+
|i4 : C.dd^2                        |
|                                   |
|          1         6              |
|o4 = 0 : R  <----- R  : 2          |
|               0                   |
|                                   |
|          4         4              |
|     1 : R  <----- R  : 3          |
|               0                   |
|                                   |
|          6         1              |
|     2 : R  <----- R  : 4          |
|               0                   |
|                                   |
|o4 : ChainComplexMap               |
+-----------------------------------+

See also
========

  * eagonNorthcott -- Eagon-Northcott
    complex of a matrix of linear forms

Ways to use this method:
========================

  * koszul(Matrix) -- the Koszul complex

koszul(ZZ,Matrix) -- a differential in a Koszul complex
*******************************************************

Synopsis
========

  * Function: koszul,
  * Usage:
        g = koszul(i,f)
  * Inputs:
      * i
      * f, a 1 by n matrix
  * Outputs:
      * g, the i-th differential in the Koszul complex of the matrix f

Description
===========

+---------------------------+
|i1 : R = QQ[x_1..x_4];     |
+---------------------------+
|i2 : f = matrix{{x_1..x_4}}|
|                           |
|o2 = | x_1 x_2 x_3 x_4 |   |
|                           |
|             1      4      |
|o2 : Matrix R  <-- R       |
+---------------------------+
To see the second differential in the Koszul complex of the matrix f look at:
+------------------------------------------+
|i3 : koszul(2,f)                          |
|                                          |
|o3 = {1} | -x_2 -x_3 0    -x_4 0    0    ||
|     {1} | x_1  0    -x_3 0    -x_4 0    ||
|     {1} | 0    x_1  x_2  0    0    -x_4 ||
|     {1} | 0    0    0    x_1  x_2  x_3  ||
|                                          |
|             4      6                     |
|o3 : Matrix R  <-- R                      |
+------------------------------------------+

Ways to use this method:
========================

  * koszul(ZZ,Matrix) -- a differential in a
    Koszul complex

last -- last element of a list
******************************

Synopsis
========

  * Usage:
        last L
  * Inputs:
      * L, a list or sequence
  * Outputs:
      * l, the last element of L

Description
===========

+-------------------------+
|i1 : last {a,b,c,d,e}    |
|                         |
|o1 = e                   |
|                         |
|o1 : Symbol              |
+-------------------------+
|i2 : last gens(QQ[x,y,z])|
|                         |
|o2 = z                   |
|                         |
|o2 : QQ[x..z]            |
+-------------------------+

See also
========

  * first -- first element of a list
  * take -- Take some elements from a list or sequence.
  * select -- select from a list, hash table, or string
  * position -- the first element of a list satisfying a
    condition
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

For the programmer
==================

The object last, is a function closure.

lcm -- least common multiple
****************************

Synopsis
========

  * Usage:
        lcm(x,y,...)
  * Inputs:
      * x, a ring element, all the elements should be
        integers, rational numbers or ring elements
  * Outputs:
      * m, a ring element, the least common multiple of the
        elements x,y,...

Description
===========

+--------------------------------+
|i1 : lcm(-6,15,14)              |
|                                |
|o1 = 210                        |
+--------------------------------+
|i2 : lcm(-6/7,15,14)            |
|                                |
|o2 = 210                        |
|                                |
|o2 : QQ                         |
+--------------------------------+
|i3 : R = QQ[a..d];              |
+--------------------------------+
|i4 : lcm(a^2-d^2,(a-d)*(b+c))   |
|                                |
|      2     2       2      2    |
|o4 = a b + a c - b*d  - c*d     |
|                                |
|o4 : R                          |
+--------------------------------+
|i5 : factor oo                  |
|                                |
|o5 = (b + c)(a - d)(a + d)      |
|                                |
|o5 : Expression of class Product|
+--------------------------------+

See also
========

  * gcd -- greatest common divisor

Ways to use lcm:
================

  * "lcm(List)"
  * "lcm(QQ,QQ)"
  * "lcm(QQ,ZZ)"
  * "lcm(RingElement,RingElement)"
  * "lcm(RingElement,ZZ)"
  * "lcm(Sequence)"
  * "lcm(ZZ,QQ)"
  * "lcm(ZZ,RingElement)"
  * "lcm(ZZ,ZZ)"
  * lcm() (missing documentation)
  * lcm(MonomialIdeal) -- least common multiple
    of all minimal generators

For the programmer
==================

The object lcm, is an associative binary method function.

lcm(MonomialIdeal) -- least common multiple of all minimal generators
*********************************************************************

Synopsis
========

  * Function: lcm,
  * Usage:
        m = lcm I
  * Inputs:
      * I, a monomial ideal,
  * Outputs:
      * m, a ring element,

Description
===========

This function is implemented in the engine, as it is used in many algorithms
involving monomial ideals.

+--------------------------------------------+
|i1 : R = QQ[a..d];                          |
+--------------------------------------------+
|i2 : I = monomialIdeal "a4,a3b6,a2b8c2,c4d5"|
|                                            |
|                     4   3 6   2 8 2   4 5  |
|o2 = monomialIdeal (a , a b , a b c , c d ) |
|                                            |
|o2 : MonomialIdeal of R                     |
+--------------------------------------------+
|i3 : lcm I                                  |
|                                            |
|      4 8 4 5                               |
|o3 = a b c d                                |
|                                            |
|o3 : R                                      |
+--------------------------------------------+
|i4 : first exponents lcm I                  |
|                                            |
|o4 = {4, 8, 4, 5}                           |
|                                            |
|o4 : List                                   |
+--------------------------------------------+

See also
========

  * dual(MonomialIdeal) -- the Alexander dual
    of a monomial ideal
  * irreducibleDecomposition(MonomialIdeal) (PrimaryDecomposition)
    -- express a monomial ideal
    as an intersection of irreducible monomial ideals
  * primaryDecomposition(Ideal) (PrimaryDecomposition)
    -- irredundant primary
    decomposition of an ideal

Ways to use this method:
========================

  * lcm(MonomialIdeal) -- least common multiple
    of all minimal generators

leadCoefficient -- the coefficient of the leading term
******************************************************

Synopsis
========

  * Usage:
        leadCoefficient f
  * Inputs:
      * f, a ring element, a polynomial
  * Outputs:
      * a ring element, an element of the
        coefficientRing, of the ring of f

Description
===========

The leading term is with respect to the monomial ordering in the ring. See
monomial orderings, for details.

+-------------------------------------------------------------------+
|i1 : R = ZZ/5[a,b,c]; f = a*b^2 + 3*b*c^3 + 2;                     |
+-------------------------------------------------------------------+
|i3 : leadCoefficient f                                             |
|                                                                   |
|o3 = -2                                                            |
|                                                                   |
|     ZZ                                                            |
|o3 : --                                                            |
|      5                                                            |
+-------------------------------------------------------------------+
|i4 : S = ZZ/5[a,b,c, MonomialOrder => Lex]; g = a*b^2 +3*b*c^3 + 2;|
+-------------------------------------------------------------------+
|i6 : leadCoefficient g                                             |
|                                                                   |
|o6 = 1                                                             |
|                                                                   |
|     ZZ                                                            |
|o6 : --                                                            |
|      5                                                            |
+-------------------------------------------------------------------+

See also
========

  * coefficients -- monomials and their coefficients
  * coefficientRing -- get the coefficient ring
  * leadComponent -- the leading component(s) of a vector
    or matrix
  * leadMonomial -- the leading monomial of a ring element
  * leadTerm -- get the greatest term
  * someTerms -- select some terms of a polynomial
  * terms -- provide a list of terms of a polynomial

Ways to use leadCoefficient:
============================

  * "leadCoefficient(RingElement)"

For the programmer
==================

The object leadCoefficient, is a method function.

leadComponent -- the leading component(s) of a vector or matrix
***************************************************************

Synopsis
========

  * Usage:
        leadComponent v
  * Inputs:
      * v, a vector, or Matrix,
  * Outputs:
      * an integer, or List, of integers, the largest
        index of a nonzero element of v

Description
===========

+----------------------------------------------------+
|i1 : leadComponent vector{0,0,1,0,1}                |
|                                                    |
|o1 = 4                                              |
+----------------------------------------------------+
|i2 : leadComponent vector{0,0,1,2,3,4,0}            |
|                                                    |
|o2 = 5                                              |
+----------------------------------------------------+
|i3 : leadComponent matrix{{0,0,1}, {0,1,0}, {1,0,0}}|
|                                                    |
|o3 = {2, 1, 0}                                      |
|                                                    |
|o3 : List                                           |
+----------------------------------------------------+

Leading appears to be a bit of a misnomer here, since the index/indices return
are the last, not the first, corresponding to nonzero elements.

This command also works with vectors and matrices that contain polynomial ring
elements.

+-----------------------------------------------------------+
|i4 : R = ZZ/5[a,b,c]; leadComponent vector{a*b^2,3*b*c^3,0}|
|                                                           |
|o5 = 1                                                     |
+-----------------------------------------------------------+

See also
========

  * leadCoefficient -- the coefficient of the leading
    term
  * leadMonomial -- the leading monomial of a ring element
  * leadTerm -- get the greatest term
  * position -- the first element of a list satisfying a
    condition
  * positions -- which elements of a list satisfy a condition
  * select -- select from a list, hash table, or string
  * support -- list of variables occurring in a polynomial or
    matrix

Ways to use leadComponent:
==========================

  * "leadComponent(Matrix)"
  * "leadComponent(Vector)"

For the programmer
==================

The object leadComponent, is a method function.

leadMonomial -- the leading monomial of a ring element
******************************************************

Synopsis
========

  * Usage:
        leadMonomial f
  * Inputs:
      * f, a ring element, a polynomial
  * Outputs:
      * a ring element, the monomial, with no coefficient,
        of the leading term of f

Description
===========

The leading term is with respect to the monomial ordering in the ring. See
monomial orderings, for details.

+-------------------------------------------------------------------+
|i1 : R = ZZ/5[a,b,c]; f = a*b^2 + 3*b*c^3 + 2;                     |
+-------------------------------------------------------------------+
|i3 : leadMonomial f                                                |
|                                                                   |
|        3                                                          |
|o3 = b*c                                                           |
|                                                                   |
|o3 : R                                                             |
+-------------------------------------------------------------------+
|i4 : S = ZZ/5[a,b,c, MonomialOrder => Lex]; g = a*b^2 +3*b*c^3 + 2;|
+-------------------------------------------------------------------+
|i6 : leadMonomial g                                                |
|                                                                   |
|        2                                                          |
|o6 = a*b                                                           |
|                                                                   |
|o6 : S                                                             |
+-------------------------------------------------------------------+

See also
========

  * leadComponent -- the leading component(s) of a vector
    or matrix
  * leadMonomial -- the leading monomial of a ring element
  * leadTerm -- get the greatest term
  * monomials -- matrix of monomials in a ring element or
    matrix
  * someTerms -- select some terms of a polynomial
  * terms -- provide a list of terms of a polynomial

Ways to use leadMonomial:
=========================

  * "leadMonomial(RingElement)"
  * leadMonomial(Vector) (missing documentation)

For the programmer
==================

The object leadMonomial, is a method function.

leadTerm -- get the greatest term
*********************************

Description
===========

Every polynomial ring in Macaulay2 comes equipped with a monomial ordering. For
ring elements and matrices, this function returns the greatest term in this
order.

For an ideal, a Gröbner basis is first computed, and the ideal of lead terms is
returned.

If an initial integer n is specified, then the returned value contains the sum
of all of the terms with the greatest value on the first n parts of the
monomial order.

Ways to use leadTerm:
=====================

  * leadTerm(Ideal) -- get the ideal of greatest
    terms
  * "leadTerm(GroebnerBasis)" -- see leadTerm(Matrix),
    -- get the greatest term of each column
  * leadTerm(Matrix) -- get the greatest term of
    each column
  * "leadTerm(Vector)" -- see leadTerm(Matrix), --
    get the greatest term of each column
  * leadTerm(RingElement) -- get the greatest
    term
  * leadTerm(ZZ,Ideal) -- get the ideal of
    lead polynomials
  * leadTerm(ZZ,Matrix) -- get the matrix of
    lead polynomials of each column
  * leadTerm(ZZ,RingElement) -- get the
    lead polynomials using part of the monomial order

For the programmer
==================

The object leadTerm, is a method function.

leadTerm(Ideal) -- get the ideal of greatest terms
**************************************************

Synopsis
========

  * Function: leadTerm,
  * Usage:
        leadTerm I
  * Inputs:
      * I
  * Outputs:
      * The ideal of all possible lead terms of I

Description
===========

Compute a Gröbner basis, and return the ideal generated by
the lead terms of the Gröbner basis elements.
+---------------------------------+
|i1 : R = QQ[a..d];               |
+---------------------------------+
|i2 : I = ideal(a*b-c*d, a*c-b*d) |
|                                 |
|o2 = ideal (a*b - c*d, a*c - b*d)|
|                                 |
|o2 : Ideal of R                  |
+---------------------------------+
|i3 : leadTerm I                  |
|                                 |
|o3 = | ac ab b2d |               |
|                                 |
|             1      3            |
|o3 : Matrix R  <-- R             |
+---------------------------------+
+--------------------------------------+
|i4 : R = ZZ[a..d][x,y,z];             |
+--------------------------------------+
|i5 : I = ideal(a*x-b*y, x^3, y^3, z^3)|
|                                      |
|                        3   3   3     |
|o5 = ideal (a*x - b*y, x , y , z )    |
|                                      |
|o5 : Ideal of R                       |
+--------------------------------------+
|i6 : leadTerm I                       |
|                                      |
|o6 = | ax z3 y3 b2xy2 bx2y x3 |       |
|                                      |
|             1      6                 |
|o6 : Matrix R  <-- R                  |
+--------------------------------------+

Ways to use this method:
========================

  * leadTerm(Ideal) -- get the ideal of greatest
    terms

leadTerm(Matrix) -- get the greatest term of each column
********************************************************

Synopsis
========

  * Function: leadTerm,
  * Usage:
        leadTerm f
  * Inputs:
      * f, in a polynomial ring
  * Outputs:
      * a matrix, the lead term matrix of f

Description
===========

In Macaulay2, each free module over a polynomial ring comes equipped with a
monomial order, and this routine returns the matrix
whose i-th column is the lead term of the i th column of f.
+----------------------------------+
|i1 : R = QQ[a..d];                |
+----------------------------------+
|i2 : f = matrix{{0,a^2-b*c},{c,d}}|
|                                  |
|o2 = | 0 a2-bc |                  |
|     | c d     |                  |
|                                  |
|             2      2             |
|o2 : Matrix R  <-- R              |
+----------------------------------+
|i3 : leadTerm f                   |
|                                  |
|o3 = | 0 a2 |                     |
|     | c 0  |                     |
|                                  |
|             2      2             |
|o3 : Matrix R  <-- R              |
+----------------------------------+
Coefficients are included in the result:
+---------------------------------------------+
|i4 : R = ZZ[a..d][x,y,z];                    |
+---------------------------------------------+
|i5 : f = matrix{{0,(a+b)*x^2},{c*x, (b+c)*y}}|
|                                             |
|o5 = | 0  (a+b)x2 |                          |
|     | cx (b+c)y  |                          |
|                                             |
|             2      2                        |
|o5 : Matrix R  <-- R                         |
+---------------------------------------------+
|i6 : leadTerm f                              |
|                                             |
|o6 = | 0  ax2 |                              |
|     | cx 0   |                              |
|                                             |
|             2      2                        |
|o6 : Matrix R  <-- R                         |
+---------------------------------------------+
The argument f can also be a Gröbner basis, in which case
the lead term matrix of the generating matrix of f is returned.

See also
========

  * leadCoefficient -- the coefficient of the leading
    term
  * leadMonomial -- the leading monomial of a ring element
  * leadComponent -- the leading component(s) of a vector
    or matrix

Ways to use this method:
========================

  * "leadTerm(GroebnerBasis)"
  * leadTerm(Matrix) -- get the greatest term of
    each column
  * "leadTerm(Vector)"

leadTerm(RingElement) -- get the greatest term
**********************************************

Synopsis
========

  * Function: leadTerm,
  * Usage:
        leadTerm f
  * Inputs:
      * f, in a polynomial ring
  * Outputs:
      * a ring element, the lead term of f

Description
===========

Each polynomial ring comes equipped with a monomial ordering,
and this routine returns the lead (greatest) monomial and its
coefficient. Recall that the default monomial order is the graded reverse
lexicographic order.
+---------------------------------------+
|i1 : R = QQ[a..d];                     |
+---------------------------------------+
|i2 : leadTerm (3*b*c^2-d^3-1)          |
|                                       |
|         2                             |
|o2 = 3b*c                              |
|                                       |
|o2 : R                                 |
+---------------------------------------+
|i3 : S = QQ[a..d, MonomialOrder => Lex]|
|                                       |
|o3 = S                                 |
|                                       |
|o3 : PolynomialRing                    |
+---------------------------------------+
|i4 : leadTerm (3*b*c^2-d^3-1)          |
|                                       |
|         2                             |
|o4 = 3b*c                              |
|                                       |
|o4 : S                                 |
+---------------------------------------+
Coefficients are included in the result:
+------------------------------------+
|i5 : R = ZZ[a..d][x,y,z];           |
+------------------------------------+
|i6 : leadTerm((a+b)*y^2 + (b+c)*x*z)|
|                                    |
|             2                      |
|o6 = (a + b)y                       |
|                                    |
|o6 : R                              |
+------------------------------------+

See also
========

  * leadCoefficient -- the coefficient of the leading
    term
  * leadMonomial -- the leading monomial of a ring element
  * leadComponent -- the leading component(s) of a vector
    or matrix

Ways to use this method:
========================

  * leadTerm(RingElement) -- get the greatest
    term

leadTerm(ZZ,Ideal) -- get the ideal of lead polynomials
*******************************************************

Synopsis
========

  * Function: leadTerm,
  * Usage:
        leadTerm(n,I)
  * Inputs:
      * n
      * I
  * Outputs:
      * The ideal of all possible lead polynomials of I using the first n parts
        of the monomial order

Description
===========

Compute a Gröbner basis, and return the ideal generated by
the lead terms of the Gröbner basis elements using the first n.
+---------------------------------------------------+
|i1 : R = QQ[a..d,MonomialOrder=>ProductOrder{1,3}];|
+---------------------------------------------------+
|i2 : I = ideal(a*b-c*d, a*c-b*d)                   |
|                                                   |
|o2 = ideal (a*b - c*d, a*c - b*d)                  |
|                                                   |
|o2 : Ideal of R                                    |
+---------------------------------------------------+
|i3 : leadTerm(1,I)                                 |
|                                                   |
|o3 = | b2d-c2d ac ab |                             |
|                                                   |
|             1      3                              |
|o3 : Matrix R  <-- R                               |
+---------------------------------------------------+

Ways to use this method:
========================

  * leadTerm(ZZ,Ideal) -- get the ideal of
    lead polynomials

leadTerm(ZZ,Matrix) -- get the matrix of lead polynomials of each column
************************************************************************

Synopsis
========

  * Function: leadTerm,
  * Usage:
        leadTerm(n,f)
  * Inputs:
      * n
      * f, in a polynomial ring
  * Outputs:
      * a matrix, the lead term matrix of f using the first n
        parts of the monomial order

Description
===========

Returns the matrix whose i-th column is the lead term of the i-th column of f,
using the first n parts of the monomial order.
+---------------------------------------------------------+
|i1 : R = QQ[x,y,z,a..d,MonomialOrder=>ProductOrder{3,4}];|
+---------------------------------------------------------+
|i2 : f = matrix{{0,x^2*(a+b)}, {a*x+2*b*y, y^2*(c+d)}}   |
|                                                         |
|o2 = | 0      x2a+x2b |                                  |
|     | xa+2yb y2c+y2d |                                  |
|                                                         |
|             2      2                                    |
|o2 : Matrix R  <-- R                                     |
+---------------------------------------------------------+
|i3 : leadTerm(1,f)                                       |
|                                                         |
|o3 = | 0  x2a+x2b |                                      |
|     | xa 0       |                                      |
|                                                         |
|             2      2                                    |
|o3 : Matrix R  <-- R                                     |
+---------------------------------------------------------+

See also
========

  * selectInSubring -- select columns in a subring

Ways to use this method:
========================

  * leadTerm(ZZ,Matrix) -- get the matrix of
    lead polynomials of each column

leadTerm(ZZ,RingElement) -- get the lead polynomials using part of the monomial order
*************************************************************************************

Synopsis
========

  * Function: leadTerm,
  * Usage:
        leadTerm(n,f)
  * Inputs:
      * n
      * f, in a polynomial ring
  * Outputs:
      * a ring element, the lead term of f using the first
        n parts of the monomial order

Description
===========

Returns the sum of the terms of f which are greatest using the      first n
parts of the monomial order in the ring of f.

In the following example, the lead terms using the first part refers to all the
monomials that have the lead monomial in the indeterminates a and b.  This has
a effect similar to selecting leadTerm in the ring QQ[c,d][a,b].
+------------------------------------------------------+
|i1 : R = QQ[a..d, MonomialOrder => ProductOrder{2,2}];|
+------------------------------------------------------+
|i2 : leadTerm(1, (c+d)*a^3 - c^100*a - 1)             |
|                                                      |
|      3     3                                         |
|o2 = a c + a d                                        |
|                                                      |
|o2 : R                                                |
+------------------------------------------------------+

See also
========

  * selectInSubring -- select columns in a subring

Ways to use this method:
========================

  * leadTerm(ZZ,RingElement) -- get the
    lead polynomials using part of the monomial order

left -- left endpoint of an interval
************************************

Synopsis
========

  * Usage:
        x = left I
  * Inputs:
      * I, a real interval,
  * Outputs:
      * x, a real number,

Description
===========

Returns the left endpoint of the input interval.

See also
========

  * right -- right endpoint of an interval
  * midpoint -- midpoint of an interval
  * diameter -- diameter of an interval

For the programmer
==================

The object left, is a compiled function.

left shift
**********

Synopsis
========

  * Usage:
        x << j
        I << j
  * Inputs:
      * x
      * j
      * I, a real interval,
  * Outputs:
      * the number obtained from x by shifting its binary representation
        leftward j places
      * a real interval, an interval containing all shifts of the
        binary representations elements of I by j places leftward
+--------------------------+
|i1 : 256 << 5             |
|                          |
|o1 = 8192                 |
+--------------------------+
|i2 : 256. << 555          |
|                          |
|o2 = 3.019169939857233e169|
|                          |
|o2 : RR (of precision 53) |
+--------------------------+

See also
========

  * right shift

length -- length of an object
*****************************

Ways to use length:
===================

  * length(ChainComplex) -- length of a chain
    complex or graded module
  * length(Dictionary) -- length of a dictionary
  * length(GradedModule) -- length of a graded
    module
  * length(Module) -- Computes the length of a
    module
  * length(String) -- length of a string
  * length(VisibleList) -- length of a visible
    list

For the programmer
==================

The object length, is a method function with a single argument.

length(ChainComplex) -- length of a chain complex or graded module
******************************************************************

Synopsis
========

  * Function: length,

Description
===========

length C -- the length of a chain complex.

The length of a chain complex is defined to be the difference between the
smallest and largest indices of spots occupied by modules, even if those
modules happen to be zero.

Ways to use this method:
========================

  * length(ChainComplex) -- length of a chain
    complex or graded module

length(Dictionary) -- length of a dictionary
********************************************

Synopsis
========

  * Function: length,
  * Usage:
        n = length d
  * Inputs:
      * d
  * Outputs:
      * n, the number of entries in d

Ways to use this method:
========================

  * length(Dictionary) -- length of a dictionary

length(GradedModule) -- length of a graded module
*************************************************

Synopsis
========

  * Function: length,

Description
===========

The length of a graded module is the difference between the largest and
smallest indices of occupied spots.  Chain complexes are graded modules, so
this function applies to them, too.
+----------------------------------+
|i1 : R = QQ[x..z];                |
+----------------------------------+
|i2 : C = res coker vars R         |
|                                  |
|      1      3      3      1      |
|o2 = R  <-- R  <-- R  <-- R  <-- 0|
|                                  |
|     0      1      2      3      4|
|                                  |
|o2 : ChainComplex                 |
+----------------------------------+
|i3 : length C                     |
|                                  |
|o3 = 3                            |
+----------------------------------+

Ways to use this method:
========================

  * length(GradedModule) -- length of a graded
    module

length(Module) -- Computes the length of a module
*************************************************

Synopsis
========

  * Function: length,
  * Usage:
        l = length M
  * Inputs:
      * M, a module,
  * Outputs:
      * l, an integer, the length of M
  * Consequences:
      * In the local case, the length of the module is stored in
        M.cache.length.

Description
===========

If M is a graded module over a singly graded polynomial ring or a quotient of a
polynomial ring over a field k then length is the same as the degree.

If M is over a local ring then length is computed by summing the output of the
Hilbert-Samuel function until it vanishes. Note that in this case the
LocalRings, package must be loaded first.

Caveat
======

In the local case, the input is assumed to have finite length.

See also
========

  * degree(Module)

Ways to use this method:
========================

  * length(Module) -- Computes the length of a
    module

length(String) -- length of a string
************************************

Synopsis
========

  * Function: length,
  * Usage:
        n = length s
  * Inputs:
      * s
  * Outputs:
      * n, the length of the string s

Ways to use this method:
========================

  * length(String) -- length of a string

length(VisibleList) -- length of a visible list
***********************************************

Synopsis
========

  * Function: length,
  * Usage:
        n = length x
  * Inputs:
      * x
  * Outputs:
      * n, the number of entries in x

Ways to use this method:
========================

  * length(VisibleList) -- length of a visible
    list

LengthLimit -- stop when the resolution reaches this length
***********************************************************

Functions with optional argument named LengthLimit:
===================================================

  * "minimalBetti(...,LengthLimit=>...)" -- see minimalBetti,
    -- minimal betti numbers of (the minimal free resolution of)
    a homogeneous ideal or module
  * resolution(...,LengthLimit=>...)
    -- stop when the
    resolution reaches this length

For the programmer
==================

The object LengthLimit, is a symbol.

lift -- lift to another ring
****************************

Synopsis
========

  * Usage:
        lift(f,R)
  * Inputs:
      * f, a ring element, ideal, or
        matrix,
      * R, a ring,
  * Optional inputs,:
      * Verify => a Boolean value, default value true, whether
        to give an error message if lifting is not possible, or, alternatively,
        to return null,
  * Outputs:
      * a ring element, ideal, or
        matrix, over the ring R

Description
===========

(Disambiguation: for division of matrices, which is thought of as lifting one
homomorphism over another, see instead Matrix // Matrix.
For lifting a map between modules to a map between their free
resolutions, see extend.)

The ring R should be one of the base rings associated with the ring of f.  An
error is raised if f cannot be lifted to R.

The first example is lifting from the fraction field of R to R.

+--------------------------------------+
|i1 : lift(4/2,ZZ)                     |
|                                      |
|o1 = 2                                |
+--------------------------------------+
|i2 : R = ZZ[x];                       |
+--------------------------------------+
|i3 : f = ((x+1)^3*(x+4))/((x+4)*(x+1))|
|                                      |
|      2                               |
|o3 = x  + 2x + 1                      |
|                                      |
|o3 : frac R                           |
+--------------------------------------+
|i4 : lift(f,R)                        |
|                                      |
|      2                               |
|o4 = x  + 2x + 1                      |
|                                      |
|o4 : R                                |
+--------------------------------------+

Another use of lift is to take polynomials in a quotient ring and lift them to
the polynomial ring.

+-------------------------------------------+
|i5 : A = QQ[a..d];                         |
+-------------------------------------------+
|i6 : B = A/(a^2-b,c^2-d-a-3);              |
+-------------------------------------------+
|i7 : f = c^5                               |
|                                           |
|                 2                         |
|o7 = 2a*c*d + c*d  + 6a*c + b*c + 6c*d + 9c|
|                                           |
|o7 : B                                     |
+-------------------------------------------+
|i8 : lift(f,A)                             |
|                                           |
|                 2                         |
|o8 = 2a*c*d + c*d  + 6a*c + b*c + 6c*d + 9c|
|                                           |
|o8 : A                                     |
+-------------------------------------------+
|i9 : jf = jacobian ideal f                 |
|                                           |
|o9 = {1} | 2cd+6c           |              |
|     {1} | c                |              |
|     {1} | 2ad+d2+6a+b+6d+9 |              |
|     {1} | 2ac+2cd+6c       |              |
|                                           |
|             4      1                      |
|o9 : Matrix B  <-- B                       |
+-------------------------------------------+
|i10 : lift(jf,A)                           |
|                                           |
|o10 = {1} | 2cd+6c           |             |
|      {1} | c                |             |
|      {1} | 2ad+d2+6a+b+6d+9 |             |
|      {1} | 2ac+2cd+6c       |             |
|                                           |
|              4      1                     |
|o10 : Matrix A  <-- A                      |
+-------------------------------------------+

Elements may be lifted to any base ring, if such a lift exists.

+-----------------------------+
|i11 : use B;                 |
+-----------------------------+
|i12 : g = (a^2+2*a-3)-(a+1)^2|
|                             |
|o12 = -4                     |
|                             |
|o12 : B                      |
+-----------------------------+
|i13 : lift(g,A)              |
|                             |
|o13 = -4                     |
|                             |
|o13 : A                      |
+-----------------------------+
|i14 : lift(g,QQ)             |
|                             |
|o14 = -4                     |
|                             |
|o14 : QQ                     |
+-----------------------------+
|i15 : lift(lift(g,QQ),ZZ)    |
|                             |
|o15 = -4                     |
+-----------------------------+

The functions lift and substitute, are useful to move numbers
from one kind of coefficient ring to another.

+------------------+
|i16 : lift(3.0,ZZ)|
|                  |
|o16 = 3           |
+------------------+
|i17 : lift(3.0,QQ)|
|                  |
|o17 = 3           |
|                  |
|o17 : QQ          |
+------------------+

A continued fraction method is used to lift a real number to a rational number,
whereas promote, uses the internal binary representation.

+--------------------------------+
|i18 : lift(123/2341.,QQ)        |
|                                |
|       123                      |
|o18 = ----                      |
|      2341                      |
|                                |
|o18 : QQ                        |
+--------------------------------+
|i19 : promote(123/2341.,QQ)     |
|                                |
|       7572049608428139         |
|o19 = ------------------        |
|      144115188075855872        |
|                                |
|o19 : QQ                        |
+--------------------------------+
|i20 : factor oo                 |
|                                |
|      3*811*39877*78045679      |
|o20 = --------------------      |
|                57              |
|               2                |
|                                |
|o20 : Expression of class Divide|
+--------------------------------+

For numbers and ring elements, an alternate syntax with ^, is
available, analogous to the use of _, for promote.

+--------------------------+
|i21 : .0001^QQ            |
|                          |
|        1                 |
|o21 = -----               |
|      10000               |
|                          |
|o21 : QQ                  |
+--------------------------+
|i22 : .0001_QQ            |
|                          |
|        7378697629483821  |
|o22 = --------------------|
|      73786976294838206464|
|                          |
|o22 : QQ                  |
+--------------------------+

See also
========

  * baseRings -- store the list of base rings of a ring
  * liftable -- whether lifting to another ring is possible
  * promote -- promote to another ring
  * setupLift -- set up lift from one ring to another

Ways to use lift:
=================

  * "lift(BettiTally,type of ZZ)" -- see BettiTally, -- the
    class of all Betti tallies
  * "lift(CC,type of QQ)"
  * "lift(CC,type of RR_*)"
  * "lift(CC,type of ZZ)"
  * "lift(Ideal,type of QQ)"
  * "lift(Ideal,type of RingElement)"
  * "lift(Ideal,type of ZZ)"
  * "lift(Matrix,type of CC_*,type of QQ)"
  * "lift(Matrix,type of CC_*,type of RR_*)"
  * "lift(Matrix,type of CC_*,type of ZZ)"
  * "lift(Matrix,type of Number)"
  * "lift(Matrix,type of QQ,type of QQ)"
  * "lift(Matrix,type of QQ,type of ZZ)"
  * "lift(Matrix,type of RingElement)"
  * "lift(Matrix,type of RR_*,type of QQ)"
  * "lift(Matrix,type of RR_*,type of ZZ)"
  * "lift(Matrix,type of RRi_*,type of QQ)"
  * "lift(Matrix,type of RRi_*,type of RR_*)"
  * "lift(Matrix,type of RRi_*,type of ZZ)"
  * "lift(Matrix,type of ZZ,type of ZZ)"
  * "lift(QQ,type of QQ)"
  * "lift(QQ,type of ZZ)"
  * "lift(RR,type of QQ)"
  * "lift(RR,type of ZZ)"
  * "lift(RRi,type of QQ)"
  * "lift(RRi,type of RR_*)"
  * "lift(RRi,type of ZZ)"
  * "lift(ZZ,type of ZZ)"
  * lift(IndexedVariable,type of MonoidElement) (missing documentation)
  * lift(Matrix,type of CC_*,type of CC_*) (missing documentation)
  * lift(Matrix,type of RR_*,type of RR_*) (missing documentation)
  * lift(Module,type of InexactNumber') (missing documentation)
  * lift(Module,type of InexactNumber) (missing documentation)
  * lift(Module,type of Number) (missing documentation)
  * lift(Module,type of RingElement) (missing documentation)
  * lift(MutableMatrix,type of InexactNumber') (missing documentation)
  * lift(MutableMatrix,type of InexactNumber) (missing documentation)
  * lift(MutableMatrix,type of Number) (missing documentation)
  * lift(MutableMatrix,type of RingElement) (missing documentation)
  * lift(RingElement,type of MonoidElement) (missing documentation)
  * lift(SheafMap) (missing documentation)
  * lift(Vector,type of InexactNumber') (missing documentation)
  * lift(Vector,type of InexactNumber) (missing documentation)
  * lift(Vector,type of Number) (missing documentation)
  * lift(Vector,type of RingElement) (missing documentation)

For the programmer
==================

The object lift, is a method function with options.

liftable -- whether lifting to another ring is possible
*******************************************************

Synopsis
========

  * Usage:
        liftable(f,R)
  * Inputs:
      * f, a ring element, or a matrix,
      * R, a ring,
  * Outputs:
      * a Boolean value, whether f can be lifted to the ring R

Description
===========

The ring R should be one of the base rings associated with the ring of f.
+-----------------------------------+
|i1 : R = ZZ[x]                     |
|                                   |
|o1 = R                             |
|                                   |
|o1 : PolynomialRing                |
+-----------------------------------+
|i2 : liftable ((x-1)*(x+1)-x^2, ZZ)|
|                                   |
|o2 = true                          |
+-----------------------------------+
+-------------------------+
|i3 : liftable(3/4,ZZ)    |
|                         |
|o3 = false               |
+-------------------------+
|i4 : liftable((3/4)*4,ZZ)|
|                         |
|o4 = true                |
+-------------------------+

See also
========

  * lift -- lift to another ring
  * baseRings -- store the list of base rings of a ring

Ways to use liftable:
=====================

  * liftable(CC,type of RR_*) (missing documentation)

For the programmer
==================

The object liftable, is a method function.

limitFiles
**********

Synopsis
========

  * Usage:
        limitFiles n
  * Inputs:
      * n, an integer,
  * Consequences:
      * the number of open file descriptors for the current process will be
        limited to n

For the programmer
==================

The object limitFiles, is a compiled function.

limitProcesses
**************

Synopsis
========

  * Usage:
        limitProcesses n
  * Inputs:
      * n, an integer,
  * Consequences:
      * the number of simultaneous processes for the current user will be
        limited to n

For the programmer
==================

The object limitProcesses, is a compiled function.

lineNumber -- current line number
*********************************

Description
===========

lineNumber -- the current line number.
lineNumber = n -- sets the line number to n.

For the programmer
==================

The object lineNumber, is an integer.

list -- loop control
********************

Description
===========

list a keyword used with while, and for.

For the programmer
==================

The object list, is a keyword.

List ** List -- Cartesian product of two lists
**********************************************

Synopsis
========

  * Operator: **,

Description
===========

+-----------------------------------------------------------+
|i1 : {1, 2} ** {10, 20, 30}                                |
|                                                           |
|o1 = {(1, 10), (1, 20), (1, 30), (2, 10), (2, 20), (2, 30)}|
|                                                           |
|o1 : List                                                  |
+-----------------------------------------------------------+

Ways to use this method:
========================

  * List ** List -- Cartesian product of two lists

List + List -- sum of two vectors
*********************************

Synopsis
========

  * Operator: +,
  * Usage:
        v+w
  * Inputs:
      * v, a list interpreted as a vector
      * w, a list interpreted as a vector
  * Outputs:
      * the sum of the two vectors

Description
===========

+----------------------+
|i1 : {1,2,3} + {1,5,6}|
|                      |
|o1 = {2, 7, 9}        |
|                      |
|o1 : List             |
+----------------------+

Ways to use this method:
========================

  * List + List -- sum of two vectors

List - List -- difference of two vectors
****************************************

Synopsis
========

  * Operator: -,
  * Usage:
        v-w
  * Inputs:
      * v, a list interpreted as a vector
      * w, a list interpreted as a vector
  * Outputs:
      * the difference of the two vectors

Description
===========

+----------------------+
|i1 : {1,2,3} - {1,5,6}|
|                      |
|o1 = {0, -3, -3}      |
|                      |
|o1 : List             |
+----------------------+

Ways to use this method:
========================

  * List - List -- difference of two vectors

List .. List -- rectangular sequences of consecutive lists and sequences
************************************************************************

Synopsis
========

  * Operator: ..,
  * Usage:
        s .. t
  * Inputs:
      * s
      * t
  * Outputs:
      * the rectangular sequence of consecutive lists of the same length, from
        s to t, in lexicographic order, inclusive, obtained by applying the
        operator .., recursively

Description
===========

+-----------------------------------------------------------------------------+
|i1 : {a,1} .. {c,3}                                                          |
|                                                                             |
|o1 = ({a, 1}, {a, 2}, {a, 3}, {b, 1}, {b, 2}, {b, 3}, {c, 1}, {c, 2}, {c, 3})|
|                                                                             |
|o1 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i2 : {1} .. {4}                                                              |
|                                                                             |
|o2 = ({1}, {2}, {3}, {4})                                                    |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * List .. List -- rectangular sequences of
    consecutive lists and sequences
  * "Sequence .. Sequence"

List ..< List -- rectangular sequences of consecutive lists and sequences
*************************************************************************

Synopsis
========

  * Operator: ..<,
  * Usage:
        s ..< t
  * Inputs:
      * s
      * t
  * Outputs:
      * the rectangular sequence of consecutive lists of the same length, from
        s to t, in lexicographic order, not including the endpoint, obtained by
        applying the operator ..<, recursively

Description
===========

+-----------------------------------------------------------------------------+
|i1 : {a,1} ..< {d,4}                                                         |
|                                                                             |
|o1 = ({a, 1}, {a, 2}, {a, 3}, {b, 1}, {b, 2}, {b, 3}, {c, 1}, {c, 2}, {c, 3})|
|                                                                             |
|o1 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i2 : {1} ..< {5}                                                             |
|                                                                             |
|o2 = ({1}, {2}, {3}, {4})                                                    |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * List ..< List -- rectangular sequences of
    consecutive lists and sequences
  * "Sequence ..< Sequence"

List / RingElement -- vector division
*************************************

Synopsis
========

  * Operator: /,
  * Usage:
        v/c
  * Inputs:
      * v, to be treated as a vector
      * c, a number or scalar ring element
  * Outputs:
      * the quotient vector; every element of v is divided by c

Description
===========

+------------------+
|i1 : {1,2,3,4} / 3|
|                  |
|      1  2     4  |
|o1 = {-, -, 1, -} |
|      3  3     3  |
|                  |
|o1 : List         |
+------------------+

Ways to use this method:
========================

  * "List / Number"
  * List / RingElement -- vector division

List << List -- component-wise comparison of lists
**************************************************

Synopsis
========

  * Operator: <<,
  * Usage:
        L1 << L2
  * Inputs:
      * L1, a list,
      * L2, a list,
  * Outputs:
      * a Boolean value, whether the first list is less than or
        equal to the second list in each component

Code
====

../../../../../Macaulay2/m2/lists.m2:221:16-221:59: --source code:
List << List := (A, B) -> all(min(#A, #B), i -> A#i <= B#i)

See also
========

  * List ? List -- comparison operator

Ways to use this method:
========================

  * List << List -- component-wise comparison of lists

List | List -- join lists, sequences or arrays
**********************************************

Synopsis
========

  * Operator: |,
  * Usage:
        v|w
  * Inputs:
      * v, a list, an array, or a sequence,
      * w, of the same type as v
  * Outputs:
      * The join of the lists, sequences or arrays.

Description
===========

+-----------------------+
|i1 : {1,2,3}|{4,5,6}   |
|                       |
|o1 = {1, 2, 3, 4, 5, 6}|
|                       |
|o1 : List              |
+-----------------------+
+--------------------+
|i2 : (a,b,c)|(1,2)  |
|                    |
|o2 = (a, b, c, 1, 2)|
|                    |
|o2 : Sequence       |
+--------------------+

See also
========

  * join -- join lists, sequences, and iterable objects

Ways to use this method:
========================

  * "Array | Array"
  * List | List -- join lists, sequences or arrays
  * "Sequence | Sequence"

listForm -- convert to list form
********************************

Synopsis
========

  * Usage:
        listForm f
  * Inputs:
      * f, a ring element, or a monoid element,
  * Outputs:
      * a list, the polynomial or monomial in a form represented
        by nested lists.

Description
===========

A monomial is represented by the list of its exponents. A polynomial is
represented by lists of pairs (m, c)x, one for each term, where m is a list of
exponents for monomial, and c is the coefficient.

+-----------------------------------------------------------------------+
|i1 : R = ZZ/101[x,y,z];                                                |
+-----------------------------------------------------------------------+
|i2 : listForm (x^2 - 7 + x*y*z^11 + y)                                 |
|                                                                       |
|o2 = {({1, 1, 11}, 1), ({2, 0, 0}, 1), ({0, 1, 0}, 1), ({0, 0, 0}, -7)}|
|                                                                       |
|o2 : List                                                              |
+-----------------------------------------------------------------------+

Code
====

../../../../../Macaulay2/m2/monoids.m2:133:24-138:69: --source code:
listForm RingElement := f -> (
    R := ring f;
    n := numgens R;
    k := coefficientRing R;
    (cc, mm) := rawPairs(raw k, raw f);
    toList apply(cc, mm, (c, m) -> (exponents(n, m), promote(c, k))))

See also
========

  * standardForm -- convert to standard form
  * content -- the content of a polynomial
  * coefficients -- monomials and their coefficients
  * exponents -- the exponents of a polynomial
  * monomials -- matrix of monomials in a ring element or
    matrix

Ways to use listForm:
=====================

  * "listForm(MonoidElement)"
  * "listForm(RingElement)"
  * listForm(Number) (missing documentation)

For the programmer
==================

The object listForm, is a method function.

listLocalSymbols -- display of local symbols and their values
*************************************************************

Description
===========

Synopsis
========

  * Usage:
        listLocalSymbols f
  * Inputs:
      * f, an instance of the type PseudocodeClosure, a
        symbol, a dictionary, or a
        function,
  * Outputs:
      * a net, a compact display of the symbols in the local
        dictionaries attached to the closure f, and their values
+---------------------------------------------------+
|i1 : x:=3; y:="hi there"; z:=2^30; f = x->x;       |
+---------------------------------------------------+
|i5 : listLocalSymbols f                            |
|                                                   |
|o5 = symbol  class   value       location of symbol|
|     ------  -----   -----       ------------------|
|     x       ZZ      3           stdio:1:0-1:1     |
|     y       String  "hi there"  stdio:1:6-1:7     |
|     z       ZZ      1073741824  stdio:1:21-1:22   |
+---------------------------------------------------+
|i6 : listLocalSymbols symbol x                     |
|                                                   |
|o6 = symbol  class   value       location of symbol|
|     ------  -----   -----       ------------------|
|     x       ZZ      3           stdio:1:0-1:1     |
|     y       String  "hi there"  stdio:1:6-1:7     |
|     z       ZZ      1073741824  stdio:1:21-1:22   |
+---------------------------------------------------+

Synopsis
========

  * Usage:
        listLocalSymbols
  * Outputs:
      * a net, a compact display of the symbols in the local
        dictionaries attached to current,

This usage works only in the debugger, where current, has a
non-null value.

+-----------------------------------------------------------------------------+
|i7 : load "Macaulay2Doc/demo1.m2"                                            |
+-----------------------------------------------------------------------------+
|i8 : g 2                                                                     |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|8:10-8:13: --source code:                                                    |
|     b := 1/x;                                                               |
|-----------------------------------------------------------------------------|
|error: division by zero                                                      |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
|ii9 : listLocalSymbols                                                       |
|                                                                             |
|oo9 = symbol  class                                                          |
|      ------  -----                                                          |
|      a       String                                                         |
|      b       Nothing                                                        |
|      x       ZZ                                                             |
|      f       FunctionClosure                                                |
|-----------------------------------------------------------------------------|
|value                                                                        |
|-----                                                                        |
|"hi there"                                                                   |
|null                                                                         |
|0                                                                            |
|FunctionClosure[/home/m2user/src/macaulay2/M2/M2/Ma.                         |
|-----------------------------------------------------------------------------|
|   location of symbol                                                        |
|   ------------------                                                        |
|   /usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:7:5-7:6                  |
|   /usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:5-8:6                  |
|   /usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:6:5-6:6                  |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:6:0-6:1                     |
+-----------------------------------------------------------------------------+

Synopsis
========

  * Usage:
        listLocalSymbols(X,f)
  * Inputs:
      * X, a type,
      * f, an instance of the type PseudocodeClosure, a
        symbol, a dictionary, or a
        function,
  * Outputs:
      * a net, a compact display of the symbols in the local
        dictionaries attached to the closure f, and their values, provided
        their values are instances of the type X
+-----------------------------------------------------------------------------+
|ii10 : h := x -> y -> y+1;                                                   |
+-----------------------------------------------------------------------------+
|ii11 : listLocalSymbols(ZZ,h                                                 |
|                                                                             |
|oo11 = symbol  class  value                                                  |
|       ------  -----  -----                                                  |
|       x       ZZ     0                                                      |
|       x       ZZ     11                                                     |
|-----------------------------------------------------------------------------|
|11)                                                                          |
|                                                                             |
|location of symbol                                                           |
|------------------                                                           |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:6:5-6:6                     |
|stdio:7:5-7:6                                                                |
+-----------------------------------------------------------------------------+

Synopsis
========

  * Usage:
        listLocalSymbols X
  * Outputs:
      * a net, a compact display of the symbols in the local
        dictionaries attached to current, whose values have type
        X.

This usage works only in the debugger, where current, has a
non-null value.

+-----------------------------------------------------------------------------+
|ii12 : load "Macaulay2Doc/demo1.m2"                                          |
+-----------------------------------------------------------------------------+
|ii13 : g 2                                                                   |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|8:10-8:13: --source code:                                                    |
|     b := 1/x;                                                               |
|-----------------------------------------------------------------------------|
|error: division by zero                                                      |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
|iii14 : listLocalSymbols ZZ                                                  |
|                                                                             |
|ooo14 = symbol  class  value                                                 |
|        ------  -----  -----                                                 |
|        x       ZZ     0                                                     |
|-----------------------------------------------------------------------------|
|location of symbol                                                           |
|------------------                                                           |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:6:5-6:6                     |
+-----------------------------------------------------------------------------+

For the programmer
==================

The object listLocalSymbols, is a command.

listSymbols -- compact display of symbols and their values
**********************************************************

Synopsis
========

  * Usage:
        listSymbols v
  * Inputs:
      * v, a list, or a dictionary,; if it's a
        list, it should be a list of symbols
  * Outputs:
      * a net, a compact display of the symbols in v and their
        values

Description
===========

+--------------------------------------------------------+
|i1 : x:=3; y:="hi there"; z:=2^30; f = x->x;            |
+--------------------------------------------------------+
|i5 : listSymbols { symbol x, symbol y }                 |
|                                                        |
|o5 = symbol  class   value       location of symbol     |
|     ------  -----   -----       ------------------     |
|     x       ZZ      3           currentString:1:0-1:1  |
|     y       String  "hi there"  currentString:1:6-1:7  |
+--------------------------------------------------------+
|i6 : listSymbols first localDictionaries()              |
|                                                        |
|o6 = symbol  class   value       location of symbol     |
|     ------  -----   -----       ------------------     |
|     x       ZZ      3           currentString:1:0-1:1  |
|     y       String  "hi there"  currentString:1:6-1:7  |
|     z       ZZ      1073741824  currentString:1:21-1:22|
+--------------------------------------------------------+

Ways to use listSymbols:
========================

  * "listSymbols(Dictionary)"
  * "listSymbols(List)"

For the programmer
==================

The object listSymbols, is a method function.

listUserSymbols -- display the user's symbols
*********************************************

Description
===========

Synopsis
========

  * Usage:
        listUserSymbols
  * Outputs:
      * a display of the symbols defined and given values by the user, along
        with their types and values, in abbreviated form

A symbol is considered to have been give a value, if it's current value is not
equal to itself.

+---------------------------------------------------------+
|i1 : t=3;                                                |
+---------------------------------------------------------+
|i2 : R=QQ[x];                                            |
+---------------------------------------------------------+
|i3 : listUserSymbols                                     |
|                                                         |
|o3 = symbol  class           value  location of symbol   |
|     ------  -----           -----  ------------------   |
|     R       PolynomialRing  R      currentString:2:0-2:1|
|     t       ZZ              3      currentString:1:0-1:1|
|     x       R               x      currentString:2:5-2:6|
+---------------------------------------------------------+

Synopsis
========

  * Usage:
        listUserSymbols X
  * Inputs:
      * X, a type,
  * Outputs:
      * a display of the symbols of type X defined and given values by the
        user, along with their types and values, in abbreviated form
+------------------------------------------------+
|i4 : listUserSymbols ZZ                         |
|                                                |
|o4 = symbol  class  value  location of symbol   |
|     ------  -----  -----  ------------------   |
|     t       ZZ     3      currentString:1:0-1:1|
+------------------------------------------------+

See also
========

  * userSymbols -- a list of the user's symbols

For the programmer
==================

The object listUserSymbols, is a command.

lngamma -- logarithm of the Gamma function
******************************************

Synopsis
========

  * Usage:
        lngamma x
  * Inputs:
      * x, a real number,
  * Outputs:
      * a real number, or a complex number, the logarithm
        of the Gamma, function of x as a real or complex number.

Description
===========

+-------------------------------------------------------+
|i1 : lngamma 2.1                                       |
|                                                       |
|o1 = .04543773854448518                                |
|                                                       |
|o1 : RR (of precision 53)                              |
+-------------------------------------------------------+
|i2 : lngamma(-1.1)                                     |
|                                                       |
|o2 = 2.273651152924463                                 |
|                                                       |
|o2 : RR (of precision 53)                              |
+-------------------------------------------------------+
|i3 : lngamma(-2.1)                                     |
|                                                       |
|o3 = 1.531713808195086+3.141592653589793*ii            |
|                                                       |
|o3 : CC (of precision 53)                              |
+-------------------------------------------------------+
|i4 : lngamma (-2.000000000000000000000000000000001p120)|
|                                                       |
|o4 = 75.29308515659711265950622174439893398+           |
|     3.141592653589793238462643383279502885*ii         |
|                                                       |
|o4 : CC (of precision 120)                             |
+-------------------------------------------------------+

See also
========

  * Gamma -- Gamma function

Ways to use lngamma:
====================

  * "lngamma(CC)"
  * "lngamma(Number)"
  * "lngamma(RR)"
  * "lngamma(RRi)"

For the programmer
==================

The object lngamma, is a method function.

loadDepth -- the load depth
***************************

Description
===========

loadDepth = i -- sets the load depth to i, which should be a small integer,
returning the old value.

During the backtrace after an error message, a position in interpreted code is
displayed only if the load depth at the time the code was parsed is at least as
large as the error depth is now.  The load depth is set to 0 initially, is set
to 1 when the files of the Core, package are being loaded, is set
to 2 while loading a package with the debuggingMode,
option set to false, and is set to 3 while loading a package with
the debuggingMode, option set to true, and for
user input.

The value of loadDepth, active when code is parsed is referred
to later when error messages are being handled: see errorDepth,
and it is also displayed, in parentheses, when the error message
is printed.

Caveat
======

The user should not attempt to adjust the value of loadDepth.

For the programmer
==================

The object loadDepth, is an integer.

loadedFiles
***********

Description
===========

After each source file is successfully loaded, the full path to the file is
stored in the hash table loadedFiles.  It is stored as the
value, with the corresponding key being a small integer, consecutively
assigned, starting at 0.

+-----------------------------------------------------------------------------+
|i1 : peek loadedFiles                                                        |
|                                                                             |
|o1 = MutableHashTable{0 => /usr/local/share/Macaulay2/Core/version.m2        |
|                      1 => /usr/local/share/Macaulay2/Core/classes.m2        |
|                      2 => /usr/local/share/Macaulay2/Core/option.m2         |
|                      3 => /usr/local/share/Macaulay2/Core/methods.m2        |
|                      4 => /usr/local/share/Macaulay2/Core/remember.m2       |
|                      5 => /usr/local/share/Macaulay2/Core/system.m2         |
|                      6 => /usr/local/share/Macaulay2/Core/run.m2            |
|                      7 => /usr/local/share/Macaulay2/Core/shared.m2         |
|                      8 => /usr/local/share/Macaulay2/Core/autoload.m2       |
|                      9 => /usr/local/share/Macaulay2/Core/regex.m2          |
|                      10 => /usr/local/share/Macaulay2/Core/profile.m2       |
|                      11 => /usr/local/share/Macaulay2/Core/set.m2           |
|                      12 => /usr/local/share/Macaulay2/Core/nets.m2          |
|                      13 => /usr/local/share/Macaulay2/Core/debugging.m2     |
|                      14 => /usr/local/share/Macaulay2/Core/iterators.m2     |
|                      15 => /usr/local/share/Macaulay2/Core/files.m2         |
|                      16 => /usr/local/share/Macaulay2/Core/fold.m2          |
|                      17 => /usr/local/share/Macaulay2/Core/max.m2           |
|                      18 => /usr/local/share/Macaulay2/Core/combinatorics.m2 |
|                      19 => /usr/local/share/Macaulay2/Core/lists.m2         |
|                      20 => /usr/local/share/Macaulay2/Core/robust.m2        |
|                      21 => /usr/local/share/Macaulay2/Core/content.m2       |
|                      22 => /usr/local/share/Macaulay2/Core/hypertext.m2     |
|                      23 => /usr/local/share/Macaulay2/Core/validate.m2      |
|                      24 => /usr/local/share/Macaulay2/Core/expressions.m2   |
|                      25 => /usr/local/share/Macaulay2/Core/peek.m2          |
|                      26 => /usr/local/share/Macaulay2/Core/gateway.m2       |
|                      27 => /usr/local/share/Macaulay2/Core/code.m2          |
|                      28 => /usr/local/share/Macaulay2/Core/printing.m2      |
|                      29 => /usr/local/share/Macaulay2/Core/http.m2          |
|                      30 => /usr/local/share/Macaulay2/Core/computations.m2  |
|                      31 => /usr/local/share/Macaulay2/Core/rings.m2         |
|                      32 => /usr/local/share/Macaulay2/Core/integers.m2      |
|                      33 => /usr/local/share/Macaulay2/Core/engine.m2        |
|                      34 => /usr/local/share/Macaulay2/Core/enginering.m2    |
|                      35 => /usr/local/share/Macaulay2/Core/rationals.m2     |
|                      36 => /usr/local/share/Macaulay2/Core/reals.m2         |
|                      37 => /usr/local/share/Macaulay2/Core/intervals.m2     |
|                      38 => /usr/local/share/Macaulay2/Core/quotient.m2      |
|                      39 => /usr/local/share/Macaulay2/Core/powers.m2        |
|                      40 => /usr/local/share/Macaulay2/Core/variables.m2     |
|                      41 => /usr/local/share/Macaulay2/Core/indeterminates.m2|
|                      42 => /usr/local/share/Macaulay2/Core/monoids.m2       |
|                      43 => /usr/local/share/Macaulay2/Core/polyrings.m2     |
|                      44 => /usr/local/share/Macaulay2/Core/dotdot.m2        |
|                      45 => /usr/local/share/Macaulay2/Core/modules.m2       |
|                      46 => /usr/local/share/Macaulay2/Core/matrix.m2        |
|                      47 => /usr/local/share/Macaulay2/Core/matrix1.m2       |
|                      48 => /usr/local/share/Macaulay2/Core/mutablemat.m2    |
|                      49 => /usr/local/share/Macaulay2/Core/localring.m2     |
|                      50 => /usr/local/share/Macaulay2/Core/quotring.m2      |
|                      51 => /usr/local/share/Macaulay2/Core/freealgebras.m2  |
|                      52 => /usr/local/share/Macaulay2/Core/flint.m2         |
|                      53 => /usr/local/share/Macaulay2/Core/gb.m2            |
|                      54 => /usr/local/share/Macaulay2/Core/matrix2.m2       |
|                      55 => /usr/local/share/Macaulay2/Core/modules2.m2      |
|                      56 => /usr/local/share/Macaulay2/Core/hilbert.m2       |
|                      57 => /usr/local/share/Macaulay2/Core/galois.m2        |
|                      58 => /usr/local/share/Macaulay2/Core/ringmap.m2       |
|                      59 => /usr/local/share/Macaulay2/Core/newring.m2       |
|                      60 => /usr/local/share/Macaulay2/Core/basis.m2         |
|                      61 => /usr/local/share/Macaulay2/Core/genmat.m2        |
|                      62 => /usr/local/share/Macaulay2/Core/multilin.m2      |
|                      63 => /usr/local/share/Macaulay2/Core/pushforward.m2   |
|                      64 => /usr/local/share/Macaulay2/Core/Hom.m2           |
|                      65 => /usr/local/share/Macaulay2/Core/ext.m2           |
|                      66 => /usr/local/share/Macaulay2/Core/tor.m2           |
|                      67 => /usr/local/share/Macaulay2/Core/gradedmodules.m2 |
|                      68 => /usr/local/share/Macaulay2/Core/chaincomplexes.m2|
|                      69 => /usr/local/share/Macaulay2/Core/res.m2           |
|                      70 => /usr/local/share/Macaulay2/Core/betti.m2         |
|                      71 => /usr/local/share/Macaulay2/Core/monideal.m2      |
|                      72 => /usr/local/share/Macaulay2/Core/intersect.m2     |
|                      73 => /usr/local/share/Macaulay2/Core/factor.m2        |
|                      74 => /usr/local/share/Macaulay2/Core/integrate.m2     |
|                      75 => /usr/local/share/Macaulay2/Core/minPres.m2       |
|                      76 => /usr/local/share/Macaulay2/Core/monomcurve.m2    |
|                      77 => /usr/local/share/Macaulay2/Core/fano.m2          |
|                      78 => /usr/local/share/Macaulay2/Core/schubert.m2      |
|                      79 => /usr/local/share/Macaulay2/Core/local.m2         |
|                      80 => /usr/local/share/Macaulay2/Core/packages.m2      |
|                      81 => /usr/local/share/Macaulay2/Core/document.m2      |
|                      82 => /usr/local/share/Macaulay2/Core/examples.m2      |
|                      83 => /usr/local/share/Macaulay2/Core/installPackage.m2|
|                      84 => /usr/local/share/Macaulay2/Core/testing.m2       |
|                      85 => /usr/local/share/Macaulay2/Core/help.m2          |
|                      86 => /usr/local/share/Macaulay2/Core/format.m2        |
|                      87 => /usr/local/share/Macaulay2/Core/html.m2          |
|                      88 => /usr/local/share/Macaulay2/Core/markdown.m2      |
|                      89 => /usr/local/share/Macaulay2/Core/mathml.m2        |
|                      90 => /usr/local/share/Macaulay2/Core/latex.m2         |
|                      91 => /usr/local/share/Macaulay2/Core/book.m2          |
|                      92 => /usr/local/share/Macaulay2/Core/webapp.m2        |
|                      93 => /usr/local/share/Macaulay2/Core/jupyter.m2       |
|                      94 => /usr/local/share/Macaulay2/Core/texmacs.m2       |
|                      95 => /usr/local/share/Macaulay2/Core/pretty.m2        |
|                      96 => /usr/local/share/Macaulay2/Core/programs.m2      |
|                      97 => /usr/local/share/Macaulay2/Core/obsolete.m2      |
|                      98 => /usr/local/share/Macaulay2/Core/tvalues.m2       |
|                      99 => /usr/local/share/Macaulay2/Core/typicalvalues.m2 |
|                      100 => /usr/local/share/Macaulay2/Core/exports.m2      |
|                      101 => /usr/local/share/Macaulay2/Core/last.m2         |
|                      102 => /usr/local/share/Macaulay2/Core/Core.m2         |
|                      103 => /usr/local/share/Macaulay2/Text.m2              |
|                      104 => /usr/local/share/Macaulay2/SimpleDoc/helpers.m2 |
|                      105 => /usr/local/share/Macaulay2/SimpleDoc/templates.m|
|                      106 => /usr/local/share/Macaulay2/SimpleDoc/example.m2 |
|                      107 => /usr/local/share/Macaulay2/SimpleDoc.m2         |
|                      108 => /usr/local/share/Macaulay2/Elimination.m2       |
|                      109 => /usr/local/share/Macaulay2/LLLBases.m2          |
|                      110 => /usr/local/share/Macaulay2/MinimalPrimes/Annotat|
|                      111 => /usr/local/share/Macaulay2/MinimalPrimes/PDState|
|                      112 => /usr/local/share/Macaulay2/MinimalPrimes/splitId|
|                      113 => /usr/local/share/Macaulay2/MinimalPrimes/quickGB|
|                      114 => /usr/local/share/Macaulay2/MinimalPrimes/factorT|
|                      115 => /usr/local/share/Macaulay2/MinimalPrimes/radical|
|                      116 => /usr/local/share/Macaulay2/MinimalPrimes/tests.m|
|                      117 => /usr/local/share/Macaulay2/MinimalPrimes/doc.m2 |
|                      118 => /usr/local/share/Macaulay2/MinimalPrimes.m2     |
|                      119 => /usr/local/share/Macaulay2/Saturation/quotient-t|
|                      120 => /usr/local/share/Macaulay2/Saturation/saturate-t|
|                      121 => /usr/local/share/Macaulay2/Saturation/annihilato|
|                      122 => /usr/local/share/Macaulay2/Saturation/doc.m2    |
|                      123 => /usr/local/share/Macaulay2/Saturation/quotient-d|
|                      124 => /usr/local/share/Macaulay2/Saturation/saturate-d|
|                      125 => /usr/local/share/Macaulay2/Saturation/annihilato|
|                      126 => /usr/local/share/Macaulay2/Saturation.m2        |
|                      127 => /usr/local/share/Macaulay2/PrimaryDecomposition/|
|                      128 => /usr/local/share/Macaulay2/PrimaryDecomposition/|
|                      129 => /usr/local/share/Macaulay2/PrimaryDecomposition/|
|                      130 => /usr/local/share/Macaulay2/PrimaryDecomposition/|
|                      131 => /usr/local/share/Macaulay2/PrimaryDecomposition/|
|                      132 => /usr/local/share/Macaulay2/PrimaryDecomposition.|
|                      133 => /usr/local/share/Macaulay2/ReesAlgebra.m2       |
|                      134 => /usr/local/share/Macaulay2/IntegralClosure/Harbo|
|                      135 => /usr/local/share/Macaulay2/IntegralClosure.m2   |
|                      136 => /usr/local/share/Macaulay2/Parsing.m2           |
|                      137 => /usr/local/share/Macaulay2/Classic.m2           |
|                      138 => /usr/local/share/Macaulay2/TangentCone.m2       |
|                      139 => /usr/local/share/Macaulay2/ConwayPolynomials.m2 |
|                      140 => /usr/local/share/Macaulay2/InverseSystems.m2    |
|                      141 => /usr/local/share/Macaulay2/OnlineLookup.m2      |
|                      142 => /usr/local/share/Macaulay2/Isomorphism.m2       |
|                      143 => /usr/local/share/Macaulay2/FourierMotzkin.m2    |
|                      144 => /usr/local/share/Macaulay2/Topcom.m2            |
|                      145 => /usr/local/share/Macaulay2/Polyhedra/exports.m2 |
|                      146 => /usr/local/share/Macaulay2/Polyhedra/symbols.m2 |
|                      147 => /usr/local/share/Macaulay2/Polyhedra/helpers.m2 |
|                      148 => /usr/local/share/Macaulay2/Polyhedra/engine/prop|
|                      149 => /usr/local/share/Macaulay2/Polyhedra/engine/alte|
|                      150 => /usr/local/share/Macaulay2/Polyhedra/core/global|
|                      151 => /usr/local/share/Macaulay2/Polyhedra/core/cone/c|
|                      152 => /usr/local/share/Macaulay2/Polyhedra/core/cone/p|
|                      153 => /usr/local/share/Macaulay2/Polyhedra/core/cone/m|
|                      154 => /usr/local/share/Macaulay2/Polyhedra/core/fan/co|
|                      155 => /usr/local/share/Macaulay2/Polyhedra/core/polyhe|
|                      156 => /usr/local/share/Macaulay2/Polyhedra/core/fan/me|
|                      157 => /usr/local/share/Macaulay2/Polyhedra/core/fan/pr|
|                      158 => /usr/local/share/Macaulay2/Polyhedra/core/polyhe|
|                      159 => /usr/local/share/Macaulay2/Polyhedra/core/polyhe|
|                      160 => /usr/local/share/Macaulay2/Polyhedra/core/polyhe|
|                      161 => /usr/local/share/Macaulay2/Polyhedra/core/polyhe|
|                      162 => /usr/local/share/Macaulay2/Polyhedra/core/polyhe|
|                      163 => /usr/local/share/Macaulay2/Polyhedra/core/contai|
|                      164 => /usr/local/share/Macaulay2/Polyhedra/core/inters|
|                      165 => /usr/local/share/Macaulay2/Polyhedra/deprecated.|
|                      166 => /usr/local/share/Macaulay2/Polyhedra/extended/di|
|                      167 => /usr/local/share/Macaulay2/Polyhedra/extended/mi|
|                      168 => /usr/local/share/Macaulay2/Polyhedra/extended/po|
|                      169 => /usr/local/share/Macaulay2/Polyhedra/extended/po|
|                      170 => /usr/local/share/Macaulay2/Polyhedra/extended/fa|
|                      171 => /usr/local/share/Macaulay2/Polyhedra/extended/st|
|                      172 => /usr/local/share/Macaulay2/Polyhedra/extended/co|
|                      173 => /usr/local/share/Macaulay2/Polyhedra/extended/in|
|                      174 => /usr/local/share/Macaulay2/Polyhedra/extended/af|
|                      175 => /usr/local/share/Macaulay2/Polyhedra/extended/le|
|                      176 => /usr/local/share/Macaulay2/Polyhedra/extended/no|
|                      177 => /usr/local/share/Macaulay2/Polyhedra/tests/core/|
|                      178 => /usr/local/share/Macaulay2/Polyhedra/tests/core/|
|                      179 => /usr/local/share/Macaulay2/Polyhedra/tests/core/|
|                      180 => /usr/local/share/Macaulay2/Polyhedra/tests/core/|
|                      181 => /usr/local/share/Macaulay2/Polyhedra/tests/core/|
|                      182 => /usr/local/share/Macaulay2/Polyhedra/tests/core/|
|                      183 => /usr/local/share/Macaulay2/Polyhedra/tests/core/|
|                      184 => /usr/local/share/Macaulay2/Polyhedra/tests/core/|
|                      185 => /usr/local/share/Macaulay2/Polyhedra/tests/core/|
|                      186 => /usr/local/share/Macaulay2/Polyhedra/tests/core/|
|                      187 => /usr/local/share/Macaulay2/Polyhedra/tests/core/|
|                      188 => /usr/local/share/Macaulay2/Polyhedra/tests/core/|
|                      189 => /usr/local/share/Macaulay2/Polyhedra/tests/exten|
|                      190 => /usr/local/share/Macaulay2/Polyhedra/tests/exten|
|                      191 => /usr/local/share/Macaulay2/Polyhedra/tests/exten|
|                      192 => /usr/local/share/Macaulay2/Polyhedra/tests/exten|
|                      193 => /usr/local/share/Macaulay2/Polyhedra/tests/exten|
|                      194 => /usr/local/share/Macaulay2/Polyhedra/tests/exten|
|                      195 => /usr/local/share/Macaulay2/Polyhedra/tests/exten|
|                      196 => /usr/local/share/Macaulay2/Polyhedra/tests/legac|
|                      197 => /usr/local/share/Macaulay2/Polyhedra/tests/shoul|
|                      198 => /usr/local/share/Macaulay2/Polyhedra/tests/isWel|
|                      199 => /usr/local/share/Macaulay2/Polyhedra/interfaces/|
|                      200 => /usr/local/share/Macaulay2/Polyhedra/interfaces/|
|                      201 => /usr/local/share/Macaulay2/Polyhedra/interfaces/|
|                      202 => /usr/local/share/Macaulay2/Polyhedra/documentati|
|                      203 => /usr/local/share/Macaulay2/Polyhedra/documentati|
|                      204 => /usr/local/share/Macaulay2/Polyhedra/documentati|
|                      205 => /usr/local/share/Macaulay2/Polyhedra/documentati|
|                      206 => /usr/local/share/Macaulay2/Polyhedra/documentati|
|                      207 => /usr/local/share/Macaulay2/Polyhedra/documentati|
|                      208 => /usr/local/share/Macaulay2/Polyhedra/documentati|
|                      209 => /usr/local/share/Macaulay2/Polyhedra/loadFile.m2|
|                      210 => /usr/local/share/Macaulay2/Polyhedra.m2         |
|                      211 => /usr/local/share/Macaulay2/Truncations/tests.m2 |
|                      212 => /usr/local/share/Macaulay2/Truncations/docs.m2  |
|                      213 => /usr/local/share/Macaulay2/Truncations.m2       |
|                      214 => /usr/local/share/Macaulay2/Varieties/SheafMaps.m|
|                      215 => /usr/local/share/Macaulay2/Varieties/tests.m2   |
|                      216 => /usr/local/share/Macaulay2/Varieties/tests-funct|
|                      217 => /usr/local/share/Macaulay2/Varieties/doc-varieti|
|                      218 => /usr/local/share/Macaulay2/Varieties/doc-sheaves|
|                      219 => /usr/local/share/Macaulay2/Varieties/doc-functor|
|                      220 => /usr/local/share/Macaulay2/Varieties/euler-doc.m|
|                      221 => /usr/local/share/Macaulay2/Varieties/genus-doc.m|
|                      222 => /usr/local/share/Macaulay2/Varieties/genera-doc.|
|                      223 => /usr/local/share/Macaulay2/Varieties/tangentShea|
|                      224 => /usr/local/share/Macaulay2/Varieties/cotangentSh|
|                      225 => /usr/local/share/Macaulay2/Varieties.m2         |
|                      226 => /usr/local/share/Macaulay2/PackageCitations.m2  |
|                      227 => /usr/local/share/Macaulay2/Macaulay2Doc/doc.m2  |
|                      228 => /usr/local/share/Macaulay2/Macaulay2Doc/doc1.m2 |
|                      229 => /usr/local/share/Macaulay2/Macaulay2Doc/doc2.m2 |
|                      230 => /usr/local/share/Macaulay2/Macaulay2Doc/doc3.m2 |
|                      231 => /usr/local/share/Macaulay2/Macaulay2Doc/doc4.m2 |
|                      232 => /usr/local/share/Macaulay2/Macaulay2Doc/doc5.m2 |
|                      233 => /usr/local/share/Macaulay2/Macaulay2Doc/doc6.m2 |
|                      234 => /usr/local/share/Macaulay2/Macaulay2Doc/doc7.m2 |
|                      235 => /usr/local/share/Macaulay2/Macaulay2Doc/doc8.m2 |
|                      236 => /usr/local/share/Macaulay2/Macaulay2Doc/doc9.m2 |
|                      237 => /usr/local/share/Macaulay2/Macaulay2Doc/doc10.m2|
|                      238 => /usr/local/share/Macaulay2/Macaulay2Doc/doc11.m2|
|                      239 => /usr/local/share/Macaulay2/Macaulay2Doc/doc12.m2|
|                      240 => /usr/local/share/Macaulay2/Macaulay2Doc/doc13.m2|
|                      241 => /usr/local/share/Macaulay2/Macaulay2Doc/doc14.m2|
|                      242 => /usr/local/share/Macaulay2/Macaulay2Doc/doc15.m2|
|                      243 => /usr/local/share/Macaulay2/Macaulay2Doc/changes.|
|                      244 => /usr/local/share/Macaulay2/Macaulay2Doc/overview|
|                      245 => /usr/local/share/Macaulay2/Macaulay2Doc/overview|
|                      246 => /usr/local/share/Macaulay2/Macaulay2Doc/overview|
|                      247 => /usr/local/share/Macaulay2/Macaulay2Doc/overview|
|                      248 => /usr/local/share/Macaulay2/Macaulay2Doc/overview|
|                      249 => /usr/local/share/Macaulay2/Macaulay2Doc/overview|
|                      250 => /usr/local/share/Macaulay2/Macaulay2Doc/macaulay|
|                      251 => /usr/local/share/Macaulay2/Style.m2             |
|                      252 => /usr/local/share/Macaulay2/FirstPackage.m2      |
|                      253 => /usr/local/share/Macaulay2/Macaulay2Doc.m2      |
|                      254 => /usr/local/share/Macaulay2/Parsing.m2           |
|                      255 => /usr/local/share/Macaulay2/Classic.m2           |
|                      256 => /usr/local/share/Macaulay2/Browse.m2            |
|                      257 => /usr/local/share/Macaulay2/Benchmark.m2         |
|                      258 => /usr/local/share/Macaulay2/Text.m2              |
|                      259 => /usr/local/share/Macaulay2/SimpleDoc.m2         |
|                      260 => /usr/local/share/Macaulay2/PackageTemplate.m2   |
|                      261 => /usr/local/share/Macaulay2/Saturation.m2        |
|                      262 => /usr/local/share/Macaulay2/PrimaryDecomposition.|
|                      263 => /usr/local/share/Macaulay2/FourierMotzkin.m2    |
|                      264 => /usr/local/share/Macaulay2/Dmodules.m2          |
|                      265 => /usr/local/share/Macaulay2/WeylAlgebras.m2      |
|                      266 => /usr/local/share/Macaulay2/HolonomicSystems.m2  |
|                      267 => /usr/local/share/Macaulay2/BernsteinSato.m2     |
|                      268 => /usr/local/share/Macaulay2/Depth.m2             |
|                      269 => /usr/local/share/Macaulay2/Elimination.m2       |
|                      270 => /usr/local/share/Macaulay2/GenericInitialIdeal.m|
|                      271 => /usr/local/share/Macaulay2/IntegralClosure.m2   |
|                      272 => /usr/local/share/Macaulay2/HyperplaneArrangement|
|                      273 => /usr/local/share/Macaulay2/LexIdeals.m2         |
|                      274 => /usr/local/share/Macaulay2/Markov.m2            |
|                      275 => /usr/local/share/Macaulay2/NoetherNormalization.|
|                      276 => /usr/local/share/Macaulay2/Points.m2            |
|                      277 => /usr/local/share/Macaulay2/ReesAlgebra.m2       |
|                      278 => /usr/local/share/Macaulay2/Regularity.m2        |
|                      279 => /usr/local/share/Macaulay2/SchurRings.m2        |
|                      280 => /usr/local/share/Macaulay2/SymmetricPolynomials.|
|                      281 => /usr/local/share/Macaulay2/SchurFunctors.m2     |
|                      282 => /usr/local/share/Macaulay2/SimplicialComplexes.m|
|                      283 => /usr/local/share/Macaulay2/LLLBases.m2          |
|                      284 => /usr/local/share/Macaulay2/TangentCone.m2       |
|                      285 => /usr/local/share/Macaulay2/ChainComplexExtras.m2|
|                      286 => /usr/local/share/Macaulay2/Varieties.m2         |
|                      287 => /usr/local/share/Macaulay2/Schubert2.m2         |
|                      288 => /usr/local/share/Macaulay2/PushForward.m2       |
|                      289 => /usr/local/share/Macaulay2/LocalRings.m2        |
|                      290 => /usr/local/share/Macaulay2/PruneComplex.m2      |
|                      291 => /usr/local/share/Macaulay2/BoijSoederberg.m2    |
|                      292 => /usr/local/share/Macaulay2/BGG.m2               |
|                      293 => /usr/local/share/Macaulay2/Bruns.m2             |
|                      294 => /usr/local/share/Macaulay2/InvolutiveBases.m2   |
|                      295 => /usr/local/share/Macaulay2/ConwayPolynomials.m2 |
|                      296 => /usr/local/share/Macaulay2/EdgeIdeals.m2        |
|                      297 => /usr/local/share/Macaulay2/FourTiTwo.m2         |
|                      298 => /usr/local/share/Macaulay2/StatePolytope.m2     |
|                      299 => /usr/local/share/Macaulay2/Polyhedra.m2         |
|                      300 => /usr/local/share/Macaulay2/Truncations.m2       |
|                      301 => /usr/local/share/Macaulay2/Polymake.m2          |
|                      302 => /usr/local/share/Macaulay2/gfanInterface.m2     |
|                      303 => /usr/local/share/Macaulay2/PieriMaps.m2         |
|                      304 => /usr/local/share/Macaulay2/Normaliz.m2          |
|                      305 => /usr/local/share/Macaulay2/Posets.m2            |
|                      306 => /usr/local/share/Macaulay2/XML.m2               |
|                      307 => /usr/local/share/Macaulay2/OpenMath.m2          |
|                      308 => /usr/local/share/Macaulay2/SCSCP.m2             |
|                      309 => /usr/local/share/Macaulay2/RationalPoints.m2    |
|                      310 => /usr/local/share/Macaulay2/MapleInterface.m2    |
|                      311 => /usr/local/share/Macaulay2/ConvexInterface.m2   |
|                      312 => /usr/local/share/Macaulay2/SRdeformations.m2    |
|                      313 => /usr/local/share/Macaulay2/NumericalAlgebraicGeo|
|                      314 => /usr/local/share/Macaulay2/BeginningMacaulay2.m2|
|                      315 => /usr/local/share/Macaulay2/FormalGroupLaws.m2   |
|                      316 => /usr/local/share/Macaulay2/Graphics.m2          |
|                      317 => /usr/local/share/Macaulay2/WeylGroups.m2        |
|                      318 => /usr/local/share/Macaulay2/HodgeIntegrals.m2    |
|                      319 => /usr/local/share/Macaulay2/Cyclotomic.m2        |
|                      320 => /usr/local/share/Macaulay2/Binomials.m2         |
|                      321 => /usr/local/share/Macaulay2/Kronecker.m2         |
|                      322 => /usr/local/share/Macaulay2/Nauty.m2             |
|                      323 => /usr/local/share/Macaulay2/ToricVectorBundles.m2|
|                      324 => /usr/local/share/Macaulay2/ModuleDeformations.m2|
|                      325 => /usr/local/share/Macaulay2/PHCpack.m2           |
|                      326 => /usr/local/share/Macaulay2/SimplicialDecomposabi|
|                      327 => /usr/local/share/Macaulay2/BooleanGB.m2         |
|                      328 => /usr/local/share/Macaulay2/AdjointIdeal.m2      |
|                      329 => /usr/local/share/Macaulay2/Parametrization.m2   |
|                      330 => /usr/local/share/Macaulay2/Serialization.m2     |
|                      331 => /usr/local/share/Macaulay2/NAGtypes.m2          |
|                      332 => /usr/local/share/Macaulay2/NormalToricVarieties.|
|                      333 => /usr/local/share/Macaulay2/DGAlgebras.m2        |
|                      334 => /usr/local/share/Macaulay2/Graphs.m2            |
|                      335 => /usr/local/share/Macaulay2/GraphicalModels.m2   |
|                      336 => /usr/local/share/Macaulay2/BIBasis.m2           |
|                      337 => /usr/local/share/Macaulay2/KustinMiller.m2      |
|                      338 => /usr/local/share/Macaulay2/Units.m2             |
|                      339 => /usr/local/share/Macaulay2/NautyGraphs.m2       |
|                      340 => /usr/local/share/Macaulay2/VersalDeformations.m2|
|                      341 => /usr/local/share/Macaulay2/CharacteristicClasses|
|                      342 => /usr/local/share/Macaulay2/RandomIdeals.m2      |
|                      343 => /usr/local/share/Macaulay2/RandomObjects.m2     |
|                      344 => /usr/local/share/Macaulay2/RandomPlaneCurves.m2 |
|                      345 => /usr/local/share/Macaulay2/RandomSpaceCurves.m2 |
|                      346 => /usr/local/share/Macaulay2/RandomGenus14Curves.m|
|                      347 => /usr/local/share/Macaulay2/RandomCanonicalCurves|
|                      348 => /usr/local/share/Macaulay2/RandomCurves.m2      |
|                      349 => /usr/local/share/Macaulay2/TensorComplexes.m2   |
|                      350 => /usr/local/share/Macaulay2/MonomialAlgebras.m2  |
|                      351 => /usr/local/share/Macaulay2/QthPower.m2          |
|                      352 => /usr/local/share/Macaulay2/EliminationMatrices.m|
|                      353 => /usr/local/share/Macaulay2/EllipticIntegrals.m2 |
|                      354 => /usr/local/share/Macaulay2/Triplets.m2          |
|                      355 => /usr/local/share/Macaulay2/CompleteIntersectionR|
|                      356 => /usr/local/share/Macaulay2/EagonResolution.m2   |
|                      357 => /usr/local/share/Macaulay2/MCMApproximations.m2 |
|                      358 => /usr/local/share/Macaulay2/MultiplierIdeals.m2  |
|                      359 => /usr/local/share/Macaulay2/InvariantRing.m2     |
|                      360 => /usr/local/share/Macaulay2/QuillenSuslin.m2     |
|                      361 => /usr/local/share/Macaulay2/EnumerationCurves.m2 |
|                      362 => /usr/local/share/Macaulay2/Book3264Examples.m2  |
|                      363 => /usr/local/share/Macaulay2/Divisor.m2           |
|                      364 => /usr/local/share/Macaulay2/EllipticCurves.m2    |
|                      365 => /usr/local/share/Macaulay2/HighestWeights.m2    |
|                      366 => /usr/local/share/Macaulay2/MinimalPrimes.m2     |
|                      367 => /usr/local/share/Macaulay2/Bertini.m2           |
|                      368 => /usr/local/share/Macaulay2/TorAlgebra.m2        |
|                      369 => /usr/local/share/Macaulay2/Permanents.m2        |
|                      370 => /usr/local/share/Macaulay2/BinomialEdgeIdeals.m2|
|                      371 => /usr/local/share/Macaulay2/TateOnProducts.m2    |
|                      372 => /usr/local/share/Macaulay2/LatticePolytopes.m2  |
|                      373 => /usr/local/share/Macaulay2/FiniteFittingIdeals.m|
|                      374 => /usr/local/share/Macaulay2/HigherCIOperators.m2 |
|                      375 => /usr/local/share/Macaulay2/LieTypes.m2          |
|                      376 => /usr/local/share/Macaulay2/ConformalBlocks.m2   |
|                      377 => /usr/local/share/Macaulay2/M0nbar.m2            |
|                      378 => /usr/local/share/Macaulay2/AnalyzeSheafOnP1.m2  |
|                      379 => /usr/local/share/Macaulay2/MultiplierIdealsDim2.|
|                      380 => /usr/local/share/Macaulay2/RunExternalM2.m2     |
|                      381 => /usr/local/share/Macaulay2/NumericalSchubertCalc|
|                      382 => /usr/local/share/Macaulay2/ToricTopology.m2     |
|                      383 => /usr/local/share/Macaulay2/Cremona.m2           |
|                      384 => /usr/local/share/Macaulay2/Resultants.m2        |
|                      385 => /usr/local/share/Macaulay2/VectorFields.m2      |
|                      386 => /usr/local/share/Macaulay2/SLPexpressions.m2    |
|                      387 => /usr/local/share/Macaulay2/Miura.m2             |
|                      388 => /usr/local/share/Macaulay2/ResidualIntersections|
|                      389 => /usr/local/share/Macaulay2/Visualize.m2         |
|                      390 => /usr/local/share/Macaulay2/EquivariantGB.m2     |
|                      391 => /usr/local/share/Macaulay2/ExampleSystems.m2    |
|                      392 => /usr/local/share/Macaulay2/RationalMaps.m2      |
|                      393 => /usr/local/share/Macaulay2/FastMinors.m2        |
|                      394 => /usr/local/share/Macaulay2/RandomPoints.m2      |
|                      395 => /usr/local/share/Macaulay2/SwitchingFields.m2   |
|                      396 => /usr/local/share/Macaulay2/SpectralSequences.m2 |
|                      397 => /usr/local/share/Macaulay2/SectionRing.m2       |
|                      398 => /usr/local/share/Macaulay2/OldPolyhedra.m2      |
|                      399 => /usr/local/share/Macaulay2/OldToricVectorBundles|
|                      400 => /usr/local/share/Macaulay2/K3Carpets.m2         |
|                      401 => /usr/local/share/Macaulay2/ChainComplexOperation|
|                      402 => /usr/local/share/Macaulay2/NumericalCertificatio|
|                      403 => /usr/local/share/Macaulay2/PhylogeneticTrees.m2 |
|                      404 => /usr/local/share/Macaulay2/MonodromySolver.m2   |
|                      405 => /usr/local/share/Macaulay2/ReactionNetworks.m2  |
|                      406 => /usr/local/share/Macaulay2/PackageCitations.m2  |
|                      407 => /usr/local/share/Macaulay2/NumericSolutions.m2  |
|                      408 => /usr/local/share/Macaulay2/GradedLieAlgebras.m2 |
|                      409 => /usr/local/share/Macaulay2/InverseSystems.m2    |
|                      410 => /usr/local/share/Macaulay2/Pullback.m2          |
|                      411 => /usr/local/share/Macaulay2/EngineTests.m2       |
|                      412 => /usr/local/share/Macaulay2/SVDComplexes.m2      |
|                      413 => /usr/local/share/Macaulay2/RandomComplexes.m2   |
|                      414 => /usr/local/share/Macaulay2/CohomCalg.m2         |
|                      415 => /usr/local/share/Macaulay2/Topcom.m2            |
|                      416 => /usr/local/share/Macaulay2/Triangulations.m2    |
|                      417 => /usr/local/share/Macaulay2/ReflexivePolytopesDB.|
|                      418 => /usr/local/share/Macaulay2/AbstractToricVarietie|
|                      419 => /usr/local/share/Macaulay2/Licenses.m2          |
|                      420 => /usr/local/share/Macaulay2/TestIdeals.m2        |
|                      421 => /usr/local/share/Macaulay2/FrobeniusThresholds.m|
|                      422 => /usr/local/share/Macaulay2/Seminormalization.m2 |
|                      423 => /usr/local/share/Macaulay2/AlgebraicSplines.m2  |
|                      424 => /usr/local/share/Macaulay2/TriangularSets.m2    |
|                      425 => /usr/local/share/Macaulay2/Chordal.m2           |
|                      426 => /usr/local/share/Macaulay2/Tropical.m2          |
|                      427 => /usr/local/share/Macaulay2/SymbolicPowers.m2    |
|                      428 => /usr/local/share/Macaulay2/Complexes.m2         |
|                      429 => /usr/local/share/Macaulay2/GroebnerWalk.m2      |
|                      430 => /usr/local/share/Macaulay2/RandomMonomialIdeals.|
|                      431 => /usr/local/share/Macaulay2/Matroids.m2          |
|                      432 => /usr/local/share/Macaulay2/NumericalImplicitizat|
|                      433 => /usr/local/share/Macaulay2/NonminimalComplexes.m|
|                      434 => /usr/local/share/Macaulay2/CoincidentRootLoci.m2|
|                      435 => /usr/local/share/Macaulay2/RelativeCanonicalReso|
|                      436 => /usr/local/share/Macaulay2/RandomCurvesOverVeryS|
|                      437 => /usr/local/share/Macaulay2/StronglyStableIdeals.|
|                      438 => /usr/local/share/Macaulay2/SLnEquivariantMatrice|
|                      439 => /usr/local/share/Macaulay2/CorrespondenceScrolls|
|                      440 => /usr/local/share/Macaulay2/NCAlgebra.m2         |
|                      441 => /usr/local/share/Macaulay2/SpaceCurves.m2       |
|                      442 => /usr/local/share/Macaulay2/ExteriorIdeals.m2    |
|                      443 => /usr/local/share/Macaulay2/ToricInvariants.m2   |
|                      444 => /usr/local/share/Macaulay2/SegreClasses.m2      |
|                      445 => /usr/local/share/Macaulay2/SemidefiniteProgrammi|
|                      446 => /usr/local/share/Macaulay2/SumsOfSquares.m2     |
|                      447 => /usr/local/share/Macaulay2/MultiGradedRationalMa|
|                      448 => /usr/local/share/Macaulay2/AssociativeAlgebras.m|
|                      449 => /usr/local/share/Macaulay2/VirtualResolutions.m2|
|                      450 => /usr/local/share/Macaulay2/Quasidegrees.m2      |
|                      451 => /usr/local/share/Macaulay2/DiffAlg.m2           |
|                      452 => /usr/local/share/Macaulay2/DeterminantalRepresen|
|                      453 => /usr/local/share/Macaulay2/FGLM.m2              |
|                      454 => /usr/local/share/Macaulay2/SpechtModule.m2      |
|                      455 => /usr/local/share/Macaulay2/SchurComplexes.m2    |
|                      456 => /usr/local/share/Macaulay2/SimplicialPosets.m2  |
|                      457 => /usr/local/share/Macaulay2/SlackIdeals.m2       |
|                      458 => /usr/local/share/Macaulay2/PositivityToricBundle|
|                      459 => /usr/local/share/Macaulay2/SparseResultants.m2  |
|                      460 => /usr/local/share/Macaulay2/PHCpack.m2           |
|                      461 => /usr/local/share/Macaulay2/DecomposableSparseSys|
|                      462 => /usr/local/share/Macaulay2/MixedMultiplicity.m2 |
|                      463 => /usr/local/share/Macaulay2/PencilsOfQuadrics.m2 |
|                      464 => /usr/local/share/Macaulay2/ThreadedGB.m2        |
|                      465 => /usr/local/share/Macaulay2/AdjunctionForSurfaces|
|                      466 => /usr/local/share/Macaulay2/VectorGraphics.m2    |
|                      467 => /usr/local/share/Macaulay2/GKMVarieties.m2      |
|                      468 => /usr/local/share/Macaulay2/MonomialIntegerProgra|
|                      469 => /usr/local/share/Macaulay2/NoetherianOperators.m|
|                      470 => /usr/local/share/Macaulay2/Hadamard.m2          |
|                      471 => /usr/local/share/Macaulay2/StatGraphs.m2        |
|                      472 => /usr/local/share/Macaulay2/GraphicalModelsMLE.m2|
|                      473 => /usr/local/share/Macaulay2/EigenSolver.m2       |
|                      474 => /usr/local/share/Macaulay2/MultiplicitySequence.|
|                      475 => /usr/local/share/Macaulay2/ResolutionsOfStanleyR|
|                      476 => /usr/local/share/Macaulay2/NumericalLinearAlgebr|
|                      477 => /usr/local/share/Macaulay2/ResLengthThree.m2    |
|                      478 => /usr/local/share/Macaulay2/MonomialOrbits.m2    |
|                      479 => /usr/local/share/Macaulay2/MultiprojectiveVariet|
|                      480 => /usr/local/share/Macaulay2/SpecialFanoFourfolds.|
|                      481 => /usr/local/share/Macaulay2/RationalPoints2.m2   |
|                      482 => /usr/local/share/Macaulay2/SuperLinearAlgebra.m2|
|                      483 => /usr/local/share/Macaulay2/SubalgebraBases.m2   |
|                      484 => /usr/local/share/Macaulay2/AInfinity.m2         |
|                      485 => /usr/local/share/Macaulay2/LinearTruncations.m2 |
|                      486 => /usr/local/share/Macaulay2/ThinSincereQuivers.m2|
|                      487 => /usr/local/share/Macaulay2/Python.m2            |
|                      488 => /usr/local/share/Macaulay2/BettiCharacters.m2   |
|                      489 => /usr/local/share/Macaulay2/Jets.m2              |
|                      490 => /usr/local/share/Macaulay2/FunctionFieldDesingul|
|                      491 => /usr/local/share/Macaulay2/HomotopyLieAlgebra.m2|
|                      492 => /usr/local/share/Macaulay2/TSpreadIdeals.m2     |
|                      493 => /usr/local/share/Macaulay2/RealRoots.m2         |
|                      494 => /usr/local/share/Macaulay2/ExteriorModules.m2   |
|                      495 => /usr/local/share/Macaulay2/K3Surfaces.m2        |
|                      496 => /usr/local/share/Macaulay2/GroebnerStrata.m2    |
|                      497 => /usr/local/share/Macaulay2/QuaternaryQuartics.m2|
|                      498 => /usr/local/share/Macaulay2/CotangentSchubert.m2 |
|                      499 => /usr/local/share/Macaulay2/OnlineLookup.m2      |
|                      500 => /usr/local/share/Macaulay2/MergeTeX.m2          |
|                      501 => /usr/local/share/Macaulay2/Probability.m2       |
|                      502 => /usr/local/share/Macaulay2/Isomorphism.m2       |
|                      503 => /usr/local/share/Macaulay2/CodingTheory.m2      |
|                      504 => /usr/local/share/Macaulay2/WhitneyStratification|
|                      505 => /usr/local/share/Macaulay2/JSON.m2              |
|                      506 => /usr/local/share/Macaulay2/ForeignFunctions.m2  |
|                      507 => /usr/local/share/Macaulay2/GeometricDecomposabil|
|                      508 => /usr/local/share/Macaulay2/PseudomonomialPrimary|
|                      509 => /usr/local/share/Macaulay2/PolyominoIdeals.m2   |
|                      510 => /usr/local/share/Macaulay2/MatchingFields.m2    |
|                      511 => /usr/local/share/Macaulay2/CellularResolutions.m|
|                      512 => /usr/local/share/Macaulay2/SagbiGbDetection.m2  |
|                      513 => /usr/local/share/Macaulay2/A1BrouwerDegrees.m2  |
|                      514 => /usr/local/share/Macaulay2/QuadraticIdealExample|
|                      515 => /usr/local/share/Macaulay2/TerraciniLoci.m2     |
|                      516 => /usr/local/share/Macaulay2/MatrixSchubert.m2    |
|                      517 => /usr/local/share/Macaulay2/RInterface.m2        |
|                      518 => /usr/local/share/Macaulay2/OIGroebnerBases.m2   |
|                      519 => /usr/local/share/Macaulay2/PlaneCurveLinearSerie|
|                      520 => /usr/local/share/Macaulay2/Valuations.m2        |
|                      521 => /usr/local/share/Macaulay2/SchurVeronese.m2     |
|                      522 => /usr/local/share/Macaulay2/VNumber.m2           |
|                      523 => /usr/local/share/Macaulay2/TropicalToric.m2     |
|                      524 => /usr/local/share/Macaulay2/MultigradedBGG.m2    |
|                      525 => /usr/local/share/Macaulay2/AbstractSimplicialCom|
|                      526 => /usr/local/share/Macaulay2/MultigradedImplicitiz|
|                      527 => /usr/local/share/Macaulay2/Msolve.m2            |
|                      528 => /usr/local/share/Macaulay2/Permutations.m2      |
|                      529 => /usr/local/share/Macaulay2/SCMAlgebras.m2       |
|                      530 => /usr/local/share/Macaulay2/NumericalSemigroups.m|
|                      531 => /usr/local/share/Macaulay2/Style.m2             |
|                      532 => /usr/local/share/Macaulay2/FirstPackage.m2      |
|                      533 => /usr/local/share/Macaulay2/Macaulay2Doc.m2      |
|                      534 => /usr/local/share/Macaulay2/Parsing.m2           |
|                      535 => /usr/local/share/Macaulay2/Classic.m2           |
|                      536 => /usr/local/share/Macaulay2/Browse.m2            |
|                      537 => /usr/local/share/Macaulay2/Benchmark.m2         |
|                      538 => /usr/local/share/Macaulay2/Text.m2              |
|                      539 => /usr/local/share/Macaulay2/SimpleDoc.m2         |
|                      540 => /usr/local/share/Macaulay2/PackageTemplate.m2   |
|                      541 => /usr/local/share/Macaulay2/Saturation.m2        |
|                      542 => /usr/local/share/Macaulay2/PrimaryDecomposition.|
|                      543 => /usr/local/share/Macaulay2/FourierMotzkin.m2    |
|                      544 => /usr/local/share/Macaulay2/Dmodules.m2          |
|                      545 => /usr/local/share/Macaulay2/WeylAlgebras.m2      |
|                      546 => /usr/local/share/Macaulay2/HolonomicSystems.m2  |
|                      547 => /usr/local/share/Macaulay2/BernsteinSato.m2     |
|                      548 => /usr/local/share/Macaulay2/Depth.m2             |
|                      549 => /usr/local/share/Macaulay2/Elimination.m2       |
|                      550 => /usr/local/share/Macaulay2/GenericInitialIdeal.m|
|                      551 => /usr/local/share/Macaulay2/IntegralClosure.m2   |
|                      552 => /usr/local/share/Macaulay2/HyperplaneArrangement|
|                      553 => /usr/local/share/Macaulay2/LexIdeals.m2         |
|                      554 => /usr/local/share/Macaulay2/Markov.m2            |
|                      555 => /usr/local/share/Macaulay2/NoetherNormalization.|
|                      556 => /usr/local/share/Macaulay2/Points.m2            |
|                      557 => /usr/local/share/Macaulay2/ReesAlgebra.m2       |
|                      558 => /usr/local/share/Macaulay2/Regularity.m2        |
|                      559 => /usr/local/share/Macaulay2/SchurRings.m2        |
|                      560 => /usr/local/share/Macaulay2/SymmetricPolynomials.|
|                      561 => /usr/local/share/Macaulay2/SchurFunctors.m2     |
|                      562 => /usr/local/share/Macaulay2/SimplicialComplexes.m|
|                      563 => /usr/local/share/Macaulay2/LLLBases.m2          |
|                      564 => /usr/local/share/Macaulay2/TangentCone.m2       |
|                      565 => /usr/local/share/Macaulay2/ChainComplexExtras.m2|
|                      566 => /usr/local/share/Macaulay2/Varieties.m2         |
|                      567 => /usr/local/share/Macaulay2/Schubert2.m2         |
|                      568 => /usr/local/share/Macaulay2/PushForward.m2       |
|                      569 => /usr/local/share/Macaulay2/LocalRings.m2        |
|                      570 => /usr/local/share/Macaulay2/PruneComplex.m2      |
|                      571 => /usr/local/share/Macaulay2/BoijSoederberg.m2    |
|                      572 => /usr/local/share/Macaulay2/BGG.m2               |
|                      573 => /usr/local/share/Macaulay2/Bruns.m2             |
|                      574 => /usr/local/share/Macaulay2/InvolutiveBases.m2   |
|                      575 => /usr/local/share/Macaulay2/ConwayPolynomials.m2 |
|                      576 => /usr/local/share/Macaulay2/EdgeIdeals.m2        |
|                      577 => /usr/local/share/Macaulay2/FourTiTwo.m2         |
|                      578 => /usr/local/share/Macaulay2/StatePolytope.m2     |
|                      579 => /usr/local/share/Macaulay2/Polyhedra.m2         |
|                      580 => /usr/local/share/Macaulay2/Truncations.m2       |
|                      581 => /usr/local/share/Macaulay2/Polymake.m2          |
|                      582 => /usr/local/share/Macaulay2/gfanInterface.m2     |
|                      583 => /usr/local/share/Macaulay2/PieriMaps.m2         |
|                      584 => /usr/local/share/Macaulay2/Normaliz.m2          |
|                      585 => /usr/local/share/Macaulay2/Posets.m2            |
|                      586 => /usr/local/share/Macaulay2/XML.m2               |
|                      587 => /usr/local/share/Macaulay2/OpenMath.m2          |
|                      588 => /usr/local/share/Macaulay2/SCSCP.m2             |
|                      589 => /usr/local/share/Macaulay2/RationalPoints.m2    |
|                      590 => /usr/local/share/Macaulay2/MapleInterface.m2    |
|                      591 => /usr/local/share/Macaulay2/ConvexInterface.m2   |
|                      592 => /usr/local/share/Macaulay2/SRdeformations.m2    |
|                      593 => /usr/local/share/Macaulay2/NumericalAlgebraicGeo|
|                      594 => /usr/local/share/Macaulay2/BeginningMacaulay2.m2|
|                      595 => /usr/local/share/Macaulay2/FormalGroupLaws.m2   |
|                      596 => /usr/local/share/Macaulay2/Graphics.m2          |
|                      597 => /usr/local/share/Macaulay2/WeylGroups.m2        |
|                      598 => /usr/local/share/Macaulay2/HodgeIntegrals.m2    |
|                      599 => /usr/local/share/Macaulay2/Cyclotomic.m2        |
|                      600 => /usr/local/share/Macaulay2/Binomials.m2         |
|                      601 => /usr/local/share/Macaulay2/Kronecker.m2         |
|                      602 => /usr/local/share/Macaulay2/Nauty.m2             |
|                      603 => /usr/local/share/Macaulay2/ToricVectorBundles.m2|
|                      604 => /usr/local/share/Macaulay2/ModuleDeformations.m2|
|                      605 => /usr/local/share/Macaulay2/PHCpack.m2           |
|                      606 => /usr/local/share/Macaulay2/SimplicialDecomposabi|
|                      607 => /usr/local/share/Macaulay2/BooleanGB.m2         |
|                      608 => /usr/local/share/Macaulay2/AdjointIdeal.m2      |
|                      609 => /usr/local/share/Macaulay2/Parametrization.m2   |
|                      610 => /usr/local/share/Macaulay2/Serialization.m2     |
|                      611 => /usr/local/share/Macaulay2/NAGtypes.m2          |
|                      612 => /usr/local/share/Macaulay2/NormalToricVarieties.|
|                      613 => /usr/local/share/Macaulay2/DGAlgebras.m2        |
|                      614 => /usr/local/share/Macaulay2/Graphs.m2            |
|                      615 => /usr/local/share/Macaulay2/GraphicalModels.m2   |
|                      616 => /usr/local/share/Macaulay2/BIBasis.m2           |
|                      617 => /usr/local/share/Macaulay2/KustinMiller.m2      |
|                      618 => /usr/local/share/Macaulay2/Units.m2             |
|                      619 => /usr/local/share/Macaulay2/NautyGraphs.m2       |
|                      620 => /usr/local/share/Macaulay2/VersalDeformations.m2|
|                      621 => /usr/local/share/Macaulay2/CharacteristicClasses|
|                      622 => /usr/local/share/Macaulay2/RandomIdeals.m2      |
|                      623 => /usr/local/share/Macaulay2/RandomObjects.m2     |
|                      624 => /usr/local/share/Macaulay2/RandomPlaneCurves.m2 |
|                      625 => /usr/local/share/Macaulay2/RandomSpaceCurves.m2 |
|                      626 => /usr/local/share/Macaulay2/RandomGenus14Curves.m|
|                      627 => /usr/local/share/Macaulay2/RandomCanonicalCurves|
|                      628 => /usr/local/share/Macaulay2/RandomCurves.m2      |
|                      629 => /usr/local/share/Macaulay2/TensorComplexes.m2   |
|                      630 => /usr/local/share/Macaulay2/MonomialAlgebras.m2  |
|                      631 => /usr/local/share/Macaulay2/QthPower.m2          |
|                      632 => /usr/local/share/Macaulay2/EliminationMatrices.m|
|                      633 => /usr/local/share/Macaulay2/EllipticIntegrals.m2 |
|                      634 => /usr/local/share/Macaulay2/Triplets.m2          |
|                      635 => /usr/local/share/Macaulay2/CompleteIntersectionR|
|                      636 => /usr/local/share/Macaulay2/EagonResolution.m2   |
|                      637 => /usr/local/share/Macaulay2/MCMApproximations.m2 |
|                      638 => /usr/local/share/Macaulay2/MultiplierIdeals.m2  |
|                      639 => /usr/local/share/Macaulay2/InvariantRing.m2     |
|                      640 => /usr/local/share/Macaulay2/QuillenSuslin.m2     |
|                      641 => /usr/local/share/Macaulay2/EnumerationCurves.m2 |
|                      642 => /usr/local/share/Macaulay2/Book3264Examples.m2  |
|                      643 => /usr/local/share/Macaulay2/Divisor.m2           |
|                      644 => /usr/local/share/Macaulay2/EllipticCurves.m2    |
|                      645 => /usr/local/share/Macaulay2/HighestWeights.m2    |
|                      646 => /usr/local/share/Macaulay2/MinimalPrimes.m2     |
|                      647 => /usr/local/share/Macaulay2/Bertini.m2           |
|                      648 => /usr/local/share/Macaulay2/TorAlgebra.m2        |
|                      649 => /usr/local/share/Macaulay2/Permanents.m2        |
|                      650 => /usr/local/share/Macaulay2/BinomialEdgeIdeals.m2|
|                      651 => /usr/local/share/Macaulay2/TateOnProducts.m2    |
|                      652 => /usr/local/share/Macaulay2/LatticePolytopes.m2  |
|                      653 => /usr/local/share/Macaulay2/FiniteFittingIdeals.m|
|                      654 => /usr/local/share/Macaulay2/HigherCIOperators.m2 |
|                      655 => /usr/local/share/Macaulay2/LieTypes.m2          |
|                      656 => /usr/local/share/Macaulay2/ConformalBlocks.m2   |
|                      657 => /usr/local/share/Macaulay2/M0nbar.m2            |
|                      658 => /usr/local/share/Macaulay2/AnalyzeSheafOnP1.m2  |
|                      659 => /usr/local/share/Macaulay2/MultiplierIdealsDim2.|
|                      660 => /usr/local/share/Macaulay2/RunExternalM2.m2     |
|                      661 => /usr/local/share/Macaulay2/NumericalSchubertCalc|
|                      662 => /usr/local/share/Macaulay2/ToricTopology.m2     |
|                      663 => /usr/local/share/Macaulay2/Cremona.m2           |
|                      664 => /usr/local/share/Macaulay2/Resultants.m2        |
|                      665 => /usr/local/share/Macaulay2/VectorFields.m2      |
|                      666 => /usr/local/share/Macaulay2/SLPexpressions.m2    |
|                      667 => /usr/local/share/Macaulay2/Miura.m2             |
|                      668 => /usr/local/share/Macaulay2/ResidualIntersections|
|                      669 => /usr/local/share/Macaulay2/Visualize.m2         |
|                      670 => /usr/local/share/Macaulay2/EquivariantGB.m2     |
|                      671 => /usr/local/share/Macaulay2/ExampleSystems.m2    |
|                      672 => /usr/local/share/Macaulay2/RationalMaps.m2      |
|                      673 => /usr/local/share/Macaulay2/FastMinors.m2        |
|                      674 => /usr/local/share/Macaulay2/RandomPoints.m2      |
|                      675 => /usr/local/share/Macaulay2/SwitchingFields.m2   |
|                      676 => /usr/local/share/Macaulay2/SpectralSequences.m2 |
|                      677 => /usr/local/share/Macaulay2/SectionRing.m2       |
|                      678 => /usr/local/share/Macaulay2/OldPolyhedra.m2      |
|                      679 => /usr/local/share/Macaulay2/OldToricVectorBundles|
|                      680 => /usr/local/share/Macaulay2/K3Carpets.m2         |
|                      681 => /usr/local/share/Macaulay2/ChainComplexOperation|
|                      682 => /usr/local/share/Macaulay2/NumericalCertificatio|
|                      683 => /usr/local/share/Macaulay2/PhylogeneticTrees.m2 |
|                      684 => /usr/local/share/Macaulay2/MonodromySolver.m2   |
|                      685 => /usr/local/share/Macaulay2/ReactionNetworks.m2  |
|                      686 => /usr/local/share/Macaulay2/PackageCitations.m2  |
|                      687 => /usr/local/share/Macaulay2/NumericSolutions.m2  |
|                      688 => /usr/local/share/Macaulay2/GradedLieAlgebras.m2 |
|                      689 => /usr/local/share/Macaulay2/InverseSystems.m2    |
|                      690 => /usr/local/share/Macaulay2/Pullback.m2          |
|                      691 => /usr/local/share/Macaulay2/EngineTests.m2       |
|                      692 => /usr/local/share/Macaulay2/SVDComplexes.m2      |
|                      693 => /usr/local/share/Macaulay2/RandomComplexes.m2   |
|                      694 => /usr/local/share/Macaulay2/CohomCalg.m2         |
|                      695 => /usr/local/share/Macaulay2/Topcom.m2            |
|                      696 => /usr/local/share/Macaulay2/Triangulations.m2    |
|                      697 => /usr/local/share/Macaulay2/ReflexivePolytopesDB.|
|                      698 => /usr/local/share/Macaulay2/AbstractToricVarietie|
|                      699 => /usr/local/share/Macaulay2/Licenses.m2          |
|                      700 => /usr/local/share/Macaulay2/TestIdeals.m2        |
|                      701 => /usr/local/share/Macaulay2/FrobeniusThresholds.m|
|                      702 => /usr/local/share/Macaulay2/Seminormalization.m2 |
|                      703 => /usr/local/share/Macaulay2/AlgebraicSplines.m2  |
|                      704 => /usr/local/share/Macaulay2/TriangularSets.m2    |
|                      705 => /usr/local/share/Macaulay2/Chordal.m2           |
|                      706 => /usr/local/share/Macaulay2/Tropical.m2          |
|                      707 => /usr/local/share/Macaulay2/SymbolicPowers.m2    |
|                      708 => /usr/local/share/Macaulay2/Complexes.m2         |
|                      709 => /usr/local/share/Macaulay2/GroebnerWalk.m2      |
|                      710 => /usr/local/share/Macaulay2/RandomMonomialIdeals.|
|                      711 => /usr/local/share/Macaulay2/Matroids.m2          |
|                      712 => /usr/local/share/Macaulay2/NumericalImplicitizat|
|                      713 => /usr/local/share/Macaulay2/NonminimalComplexes.m|
|                      714 => /usr/local/share/Macaulay2/CoincidentRootLoci.m2|
|                      715 => /usr/local/share/Macaulay2/RelativeCanonicalReso|
|                      716 => /usr/local/share/Macaulay2/RandomCurvesOverVeryS|
|                      717 => /usr/local/share/Macaulay2/StronglyStableIdeals.|
|                      718 => /usr/local/share/Macaulay2/SLnEquivariantMatrice|
|                      719 => /usr/local/share/Macaulay2/CorrespondenceScrolls|
|                      720 => /usr/local/share/Macaulay2/NCAlgebra.m2         |
|                      721 => /usr/local/share/Macaulay2/SpaceCurves.m2       |
|                      722 => /usr/local/share/Macaulay2/ExteriorIdeals.m2    |
|                      723 => /usr/local/share/Macaulay2/ToricInvariants.m2   |
|                      724 => /usr/local/share/Macaulay2/SegreClasses.m2      |
|                      725 => /usr/local/share/Macaulay2/SemidefiniteProgrammi|
|                      726 => /usr/local/share/Macaulay2/SumsOfSquares.m2     |
|                      727 => /usr/local/share/Macaulay2/MultiGradedRationalMa|
|                      728 => /usr/local/share/Macaulay2/AssociativeAlgebras.m|
|                      729 => /usr/local/share/Macaulay2/VirtualResolutions.m2|
|                      730 => /usr/local/share/Macaulay2/Quasidegrees.m2      |
|                      731 => /usr/local/share/Macaulay2/DiffAlg.m2           |
|                      732 => /usr/local/share/Macaulay2/DeterminantalRepresen|
|                      733 => /usr/local/share/Macaulay2/FGLM.m2              |
|                      734 => /usr/local/share/Macaulay2/SpechtModule.m2      |
|                      735 => /usr/local/share/Macaulay2/SchurComplexes.m2    |
|                      736 => /usr/local/share/Macaulay2/SimplicialPosets.m2  |
|                      737 => /usr/local/share/Macaulay2/SlackIdeals.m2       |
|                      738 => /usr/local/share/Macaulay2/PositivityToricBundle|
|                      739 => /usr/local/share/Macaulay2/SparseResultants.m2  |
|                      740 => /usr/local/share/Macaulay2/PHCpack.m2           |
|                      741 => /usr/local/share/Macaulay2/DecomposableSparseSys|
|                      742 => /usr/local/share/Macaulay2/MixedMultiplicity.m2 |
|                      743 => /usr/local/share/Macaulay2/PencilsOfQuadrics.m2 |
|                      744 => /usr/local/share/Macaulay2/ThreadedGB.m2        |
|                      745 => /usr/local/share/Macaulay2/AdjunctionForSurfaces|
|                      746 => /usr/local/share/Macaulay2/VectorGraphics.m2    |
|                      747 => /usr/local/share/Macaulay2/GKMVarieties.m2      |
|                      748 => /usr/local/share/Macaulay2/MonomialIntegerProgra|
|                      749 => /usr/local/share/Macaulay2/NoetherianOperators.m|
|                      750 => /usr/local/share/Macaulay2/Hadamard.m2          |
|                      751 => /usr/local/share/Macaulay2/StatGraphs.m2        |
|                      752 => /usr/local/share/Macaulay2/GraphicalModelsMLE.m2|
|                      753 => /usr/local/share/Macaulay2/EigenSolver.m2       |
|                      754 => /usr/local/share/Macaulay2/MultiplicitySequence.|
|                      755 => /usr/local/share/Macaulay2/ResolutionsOfStanleyR|
|                      756 => /usr/local/share/Macaulay2/NumericalLinearAlgebr|
|                      757 => /usr/local/share/Macaulay2/ResLengthThree.m2    |
|                      758 => /usr/local/share/Macaulay2/MonomialOrbits.m2    |
|                      759 => /usr/local/share/Macaulay2/MultiprojectiveVariet|
|                      760 => /usr/local/share/Macaulay2/SpecialFanoFourfolds.|
|                      761 => /usr/local/share/Macaulay2/RationalPoints2.m2   |
|                      762 => /usr/local/share/Macaulay2/SuperLinearAlgebra.m2|
|                      763 => /usr/local/share/Macaulay2/SubalgebraBases.m2   |
|                      764 => /usr/local/share/Macaulay2/AInfinity.m2         |
|                      765 => /usr/local/share/Macaulay2/LinearTruncations.m2 |
|                      766 => /usr/local/share/Macaulay2/ThinSincereQuivers.m2|
|                      767 => /usr/local/share/Macaulay2/Python.m2            |
|                      768 => /usr/local/share/Macaulay2/BettiCharacters.m2   |
|                      769 => /usr/local/share/Macaulay2/Jets.m2              |
|                      770 => /usr/local/share/Macaulay2/FunctionFieldDesingul|
|                      771 => /usr/local/share/Macaulay2/HomotopyLieAlgebra.m2|
|                      772 => /usr/local/share/Macaulay2/TSpreadIdeals.m2     |
|                      773 => /usr/local/share/Macaulay2/RealRoots.m2         |
|                      774 => /usr/local/share/Macaulay2/ExteriorModules.m2   |
|                      775 => /usr/local/share/Macaulay2/K3Surfaces.m2        |
|                      776 => /usr/local/share/Macaulay2/GroebnerStrata.m2    |
|                      777 => /usr/local/share/Macaulay2/QuaternaryQuartics.m2|
|                      778 => /usr/local/share/Macaulay2/CotangentSchubert.m2 |
|                      779 => /usr/local/share/Macaulay2/OnlineLookup.m2      |
|                      780 => /usr/local/share/Macaulay2/MergeTeX.m2          |
|                      781 => /usr/local/share/Macaulay2/Probability.m2       |
|                      782 => /usr/local/share/Macaulay2/Isomorphism.m2       |
|                      783 => /usr/local/share/Macaulay2/CodingTheory.m2      |
|                      784 => /usr/local/share/Macaulay2/WhitneyStratification|
|                      785 => /usr/local/share/Macaulay2/JSON.m2              |
|                      786 => /usr/local/share/Macaulay2/ForeignFunctions.m2  |
|                      787 => /usr/local/share/Macaulay2/GeometricDecomposabil|
|                      788 => /usr/local/share/Macaulay2/PseudomonomialPrimary|
|                      789 => /usr/local/share/Macaulay2/PolyominoIdeals.m2   |
|                      790 => /usr/local/share/Macaulay2/MatchingFields.m2    |
|                      791 => /usr/local/share/Macaulay2/CellularResolutions.m|
|                      792 => /usr/local/share/Macaulay2/SagbiGbDetection.m2  |
|                      793 => /usr/local/share/Macaulay2/A1BrouwerDegrees.m2  |
|                      794 => /usr/local/share/Macaulay2/QuadraticIdealExample|
|                      795 => /usr/local/share/Macaulay2/TerraciniLoci.m2     |
|                      796 => /usr/local/share/Macaulay2/MatrixSchubert.m2    |
|                      797 => /usr/local/share/Macaulay2/RInterface.m2        |
|                      798 => /usr/local/share/Macaulay2/OIGroebnerBases.m2   |
|                      799 => /usr/local/share/Macaulay2/PlaneCurveLinearSerie|
|                      800 => /usr/local/share/Macaulay2/Valuations.m2        |
|                      801 => /usr/local/share/Macaulay2/SchurVeronese.m2     |
|                      802 => /usr/local/share/Macaulay2/VNumber.m2           |
|                      803 => /usr/local/share/Macaulay2/TropicalToric.m2     |
|                      804 => /usr/local/share/Macaulay2/MultigradedBGG.m2    |
|                      805 => /usr/local/share/Macaulay2/AbstractSimplicialCom|
|                      806 => /usr/local/share/Macaulay2/MultigradedImplicitiz|
|                      807 => /usr/local/share/Macaulay2/Msolve.m2            |
|                      808 => /usr/local/share/Macaulay2/Permutations.m2      |
|                      809 => /usr/local/share/Macaulay2/SCMAlgebras.m2       |
|                      810 => /usr/local/share/Macaulay2/NumericalSemigroups.m|
|                      811 => /usr/local/share/Macaulay2/Macaulay2Doc/overview|
|                      812 => /usr/local/share/Macaulay2/Macaulay2Doc/overview|
|                      813 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_idea|
|                      814 => /usr/local/share/Macaulay2/Macaulay2Doc/overview|
|                      815 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_modu|
|                      816 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_muta|
|                      817 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_ring|
|                      818 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_assi|
|                      819 => /usr/local/share/Macaulay2/Macaulay2Doc/ov_top.m|
|                      820 => /usr/local/share/Macaulay2/Macaulay2Doc/ov_getti|
|                      821 => /usr/local/share/Macaulay2/Macaulay2Doc/ov_ideal|
|                      822 => /usr/local/share/Macaulay2/Macaulay2Doc/ov_ringm|
|                      823 => /usr/local/share/Macaulay2/Macaulay2Doc/ov_matri|
|                      824 => /usr/local/share/Macaulay2/Macaulay2Doc/ov_langu|
|                      825 => /usr/local/share/Macaulay2/Macaulay2Doc/ov_files|
|                      826 => /usr/local/share/Macaulay2/Macaulay2Doc/threads.|
|                      827 => /usr/local/share/Macaulay2/Macaulay2Doc/system.m|
|                      828 => /usr/local/share/Macaulay2/Macaulay2Doc/repl.m2 |
|                      829 => /usr/local/share/Macaulay2/Macaulay2Doc/debuggin|
|                      830 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_arit|
|                      831 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_fano|
|                      832 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_ring|
|                      833 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_ring|
|                      834 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_list|
|                      835 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_stri|
|                      836 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_tabl|
|                      837 => /usr/local/share/Macaulay2/Macaulay2Doc/operator|
|                      838 => /usr/local/share/Macaulay2/Macaulay2Doc/operator|
|                      839 => /usr/local/share/Macaulay2/Macaulay2Doc/groebner|
|                      840 => /usr/local/share/Macaulay2/Macaulay2Doc/monomord|
|                      841 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      842 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      843 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      844 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      845 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      846 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      847 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      848 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      849 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      850 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      851 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      852 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      853 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      854 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      855 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      856 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      857 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      858 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      859 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      860 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      861 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      862 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      863 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      864 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      865 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      866 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      867 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      868 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      869 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      870 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      871 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      872 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      873 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      874 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      875 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      876 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      877 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      878 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      879 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      880 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      881 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      882 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      883 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      884 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      885 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      886 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      887 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      888 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      889 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      890 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      891 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      892 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      893 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      894 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      895 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      896 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      897 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      898 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      899 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      900 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      901 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      902 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      903 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      904 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      905 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      906 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      907 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      908 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      909 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      910 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      911 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      912 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      913 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      914 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      915 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      916 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      917 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      918 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      919 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      920 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      921 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      922 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      923 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      924 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      925 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      926 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      927 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      928 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      929 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      930 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      931 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      932 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      933 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      934 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      935 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      936 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      937 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      938 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      939 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      940 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      941 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      942 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      943 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      944 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      945 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      946 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      947 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      948 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      949 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      950 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      951 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      952 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      953 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      954 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      955 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      956 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      957 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      958 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      959 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      960 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      961 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      962 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      963 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      964 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      965 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      966 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      967 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      968 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      969 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      970 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      971 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      972 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      973 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      974 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      975 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      976 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      977 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      978 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      979 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      980 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      981 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      982 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      983 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      984 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      985 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      986 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      987 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      988 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      989 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      990 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      991 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      992 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      993 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      994 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      995 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      996 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      997 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      998 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      999 => /usr/local/share/Macaulay2/Macaulay2Doc/function|
|                      1000 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1001 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1002 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1003 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1004 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1005 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1006 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1007 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1008 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1009 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1010 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1011 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1012 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1013 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1014 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1015 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1016 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1017 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1018 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1019 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1020 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1021 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1022 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1023 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1024 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1025 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1026 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1027 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1028 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1029 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1030 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1031 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1032 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1033 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1034 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1035 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1036 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1037 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1038 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1039 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1040 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1041 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1042 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1043 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1044 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1045 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1046 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1047 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1048 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1049 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1050 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1051 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1052 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1053 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1054 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1055 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1056 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1057 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1058 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1059 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1060 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1061 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1062 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1063 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1064 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1065 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1066 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1067 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1068 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1069 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1070 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1071 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1072 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1073 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1074 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1075 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1076 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1077 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1078 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1079 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1080 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1081 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1082 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1083 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1084 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1085 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1086 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1087 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1088 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1089 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1090 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1091 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1092 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1093 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1094 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1095 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1096 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1097 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1098 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1099 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1100 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1101 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1102 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1103 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1104 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1105 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1106 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1107 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1108 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1109 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1110 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1111 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1112 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1113 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1114 => /usr/local/share/Macaulay2/Macaulay2Doc/functio|
|                      1115 => /usr/local/share/Macaulay2/Macaulay2Doc/shared.|
|                      1116 => /usr/local/share/Macaulay2/Macaulay2Doc/types.m|
|                      1117 => /usr/local/share/Macaulay2/Macaulay2Doc/methods|
|                      1118 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_ite|
|                      1119 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_aug|
|                      1120 => /usr/local/share/Macaulay2/Macaulay2Doc/doc_ato|
|                      1121 => /usr/local/share/Macaulay2/Macaulay2Doc/options|
|                      1122 => /usr/local/share/Macaulay2/Macaulay2Doc/undocum|
|                      1123 => /usr/local/share/Macaulay2/Macaulay2Doc/M2-Sing|
|                      1124 => /usr/local/share/Macaulay2/Macaulay2Doc/loads.m|
|                      1125 => /usr/local/share/Macaulay2/Macaulay2Doc.m2     |
|                      1126 => /usr/local/share/Macaulay2/Complexes/ChainCompl|
|                      1127 => /usr/local/share/Macaulay2/Complexes/FreeResolu|
|                      1128 => /usr/local/share/Macaulay2/Complexes/ChainCompl|
|                      1129 => /usr/local/share/Macaulay2/Complexes/Tor.m2    |
|                      1130 => /usr/local/share/Macaulay2/Complexes/Ext.m2    |
|                      1131 => /usr/local/share/Macaulay2/Complexes/ChainCompl|
|                      1132 => /usr/local/share/Macaulay2/Complexes/ChainCompl|
|                      1133 => /usr/local/share/Macaulay2/Complexes/ChainCompl|
|                      1134 => /usr/local/share/Macaulay2/Complexes/FreeResolu|
|                      1135 => /usr/local/share/Macaulay2/Complexes.m2        |
|                      1136 => /usr/local/share/Macaulay2/GenericInitialIdeal.|
|                      1137 => /usr/local/share/Macaulay2/SimplicialComplexes/|
|                      1138 => /usr/local/share/Macaulay2/SimplicialComplexes/|
|                      1139 => /usr/local/share/Macaulay2/SimplicialComplexes/|
|                      1140 => /usr/local/share/Macaulay2/SimplicialComplexes.|
|                      1141 => /usr/local/share/Macaulay2/FirstPackage.m2     |
|                      1142 => /usr/local/share/Macaulay2/FourTiTwo.m2        |
|                      1143 => /usr/local/share/Macaulay2/WeylAlgebras/Dbasic.|
|                      1144 => /usr/local/share/Macaulay2/WeylAlgebras/Gbw.m2 |
|                      1145 => /usr/local/share/Macaulay2/WeylAlgebras/switch.|
|                      1146 => /usr/local/share/Macaulay2/WeylAlgebras/newRing|
|                      1147 => /usr/local/share/Macaulay2/WeylAlgebras/staffor|
|                      1148 => /usr/local/share/Macaulay2/WeylAlgebras/makeCyc|
|                      1149 => /usr/local/share/Macaulay2/WeylAlgebras/TST/Dba|
|                      1150 => /usr/local/share/Macaulay2/WeylAlgebras/TST/Gbw|
|                      1151 => /usr/local/share/Macaulay2/WeylAlgebras/DOC/mai|
|                      1152 => /usr/local/share/Macaulay2/WeylAlgebras/DOC/bas|
|                      1153 => /usr/local/share/Macaulay2/WeylAlgebras/DOC/gen|
|                      1154 => /usr/local/share/Macaulay2/WeylAlgebras.m2     |
|                      1155 => /usr/local/share/Macaulay2/AssociativeAlgebras/|
|                      1156 => /usr/local/share/Macaulay2/AssociativeAlgebras/|
|                      1157 => /usr/local/share/Macaulay2/AssociativeAlgebras.|
|                      1158 => /usr/local/share/Macaulay2/HolonomicSystems/Dsy|
|                      1159 => /usr/local/share/Macaulay2/HolonomicSystems/can|
|                      1160 => /usr/local/share/Macaulay2/HolonomicSystems/Dif|
|                      1161 => /usr/local/share/Macaulay2/HolonomicSystems/TST|
|                      1162 => /usr/local/share/Macaulay2/HolonomicSystems/TST|
|                      1163 => /usr/local/share/Macaulay2/HolonomicSystems/DOC|
|                      1164 => /usr/local/share/Macaulay2/HolonomicSystems/DOC|
|                      1165 => /usr/local/share/Macaulay2/HolonomicSystems/DOC|
|                      1166 => /usr/local/share/Macaulay2/HolonomicSystems/DOC|
|                      1167 => /usr/local/share/Macaulay2/HolonomicSystems.m2 |
|                      1168 => /usr/local/share/Macaulay2/BernsteinSato/global|
|                      1169 => /usr/local/share/Macaulay2/BernsteinSato/localB|
|                      1170 => /usr/local/share/Macaulay2/BernsteinSato/bFunct|
|                      1171 => /usr/local/share/Macaulay2/BernsteinSato/bFunct|
|                      1172 => /usr/local/share/Macaulay2/BernsteinSato/multip|
|                      1173 => /usr/local/share/Macaulay2/BernsteinSato/annFs.|
|                      1174 => /usr/local/share/Macaulay2/BernsteinSato/paramB|
|                      1175 => /usr/local/share/Macaulay2/BernsteinSato/WeylCl|
|                      1176 => /usr/local/share/Macaulay2/BernsteinSato/Dresol|
|                      1177 => /usr/local/share/Macaulay2/BernsteinSato/Drestr|
|                      1178 => /usr/local/share/Macaulay2/BernsteinSato/Dlocal|
|                      1179 => /usr/local/share/Macaulay2/BernsteinSato/DHom.m|
|                      1180 => /usr/local/share/Macaulay2/BernsteinSato/DeRham|
|                      1181 => /usr/local/share/Macaulay2/BernsteinSato/localC|
|                      1182 => /usr/local/share/Macaulay2/BernsteinSato/CC.m2 |
|                      1183 => /usr/local/share/Macaulay2/BernsteinSato/inters|
|                      1184 => /usr/local/share/Macaulay2/BernsteinSato/TST/te|
|                      1185 => /usr/local/share/Macaulay2/BernsteinSato/DOC/ma|
|                      1186 => /usr/local/share/Macaulay2/BernsteinSato/DOC/DH|
|                      1187 => /usr/local/share/Macaulay2/BernsteinSato/DOC/Dl|
|                      1188 => /usr/local/share/Macaulay2/BernsteinSato/DOC/Dr|
|                      1189 => /usr/local/share/Macaulay2/BernsteinSato/DOC/We|
|                      1190 => /usr/local/share/Macaulay2/BernsteinSato/DOC/an|
|                      1191 => /usr/local/share/Macaulay2/BernsteinSato/DOC/bF|
|                      1192 => /usr/local/share/Macaulay2/BernsteinSato/DOC/lo|
|                      1193 => /usr/local/share/Macaulay2/BernsteinSato/DOC/in|
|                      1194 => /usr/local/share/Macaulay2/BernsteinSato/DOC/mu|
|                      1195 => /usr/local/share/Macaulay2/BernsteinSato/DOC/pa|
|                      1196 => /usr/local/share/Macaulay2/BernsteinSato/DOC/ot|
|                      1197 => /usr/local/share/Macaulay2/BernsteinSato.m2    |
|                      1198 => /usr/local/share/Macaulay2/Dmodules.m2         |
|-----------------------------------------------------------------------------|
|                     }                                                       |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|edIdeal.m2                                                                   |
|.m2                                                                          |
|eals.m2                                                                      |
|.m2                                                                          |
|ower.m2                                                                      |
|.m2                                                                          |
|2                                                                            |
|                                                                             |
|                                                                             |
|est.m2                                                                       |
|est.m2                                                                       |
|r-test.m2                                                                    |
|                                                                             |
|oc.m2                                                                        |
|oc.m2                                                                        |
|r-doc.m2                                                                     |
|                                                                             |
|GTZ.m2                                                                       |
|Shimoyama-Yokoyama.m2                                                        |
|Eisenbud-Huneke-Vasconcelos.m2                                               |
|tests.m2                                                                     |
|doc.m2                                                                       |
|m2                                                                           |
|                                                                             |
|urneExamples.m2                                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|erties.m2                                                                    |
|rnatives.m2                                                                  |
|Methods.m2                                                                   |
|onstructors.m2                                                               |
|roperties.m2                                                                 |
|ethods.m2                                                                    |
|nstructors.m2                                                                |
|dron/constructors.m2                                                         |
|thods.m2                                                                     |
|operties.m2                                                                  |
|dron/properties.m2                                                           |
|dron/methods.m2                                                              |
|dralComplex/constructors.m2                                                  |
|dralComplex/properties.m2                                                    |
|dralComplex/methods.m2                                                       |
|ns.m2                                                                        |
|ection.m2                                                                    |
|m2                                                                           |
|rectProduct.m2                                                               |
|nkowskiSum.m2                                                                |
|lyhedron/properties.m2                                                       |
|lyhedron/methods.m2                                                          |
|n/methods.m2                                                                 |
|andardConstructions.m2                                                       |
|mmonFace.m2                                                                  |
|compare.m2                                                                   |
|fineImages.m2                                                                |
|gacy.m2                                                                      |
|t_refactored.m2                                                              |
|cone_basics.m2                                                               |
|polyhedron_basics.m2                                                         |
|fan_basics.m2                                                                |
|polyhedralComplex_basics.m2                                                  |
|dualFaceRepresentation.m2                                                    |
|tests_from_polymake/fvector.m2                                               |
|tests_from_polymake/representation.m2                                        |
|tests_from_polymake/hilbert_basis.m2                                         |
|tests_from_polymake/lattice_points.m2                                        |
|tests_from_polymake/normal_fan.m2                                            |
|tests_from_polymake/basic_fans.m2                                            |
|volume.m2                                                                    |
|ded/polyhedron.m2                                                            |
|ded/tests_from_polymake/minkowskiSum.m2                                      |
|ded/mixedVolume.m2                                                           |
|ded/tests_from_polymake/ehrhart_and_volume.m2                                |
|ded/linearTransform.m2                                                       |
|ded/regularSubdivision.m2                                                    |
|ded/stanleyReisner.m2                                                        |
|y_tests_working.m2                                                           |
|dFail.m2                                                                     |
|lDefined.m2                                                                  |
|fourierMotzkinAlternatives.m2                                                |
|fourtitwo.m2                                                                 |
|normaliz.m2                                                                  |
|on/intro.m2                                                                  |
|on/working_with_polyhedra.m2                                                 |
|on/working_with_cones.m2                                                     |
|on/v_h_representation.m2                                                     |
|on/deprecated_documentation.m2                                               |
|on/old_documentation.m2                                                      |
|on/documentation.m2                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|                                                                             |
|ors.m2                                                                       |
|es.m2                                                                        |
|.m2                                                                          |
|s.m2                                                                         |
|2                                                                            |
|2                                                                            |
|m2                                                                           |
|f-doc.m2                                                                     |
|eaf-doc.m2                                                                   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|A.m2                                                                         |
|B.m2                                                                         |
|C.m2                                                                         |
|2.m2                                                                         |
|3.m2                                                                         |
|4.m2                                                                         |
|.m2                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|                                                                             |
|s.m2                                                                         |
|                                                                             |
|                                                                             |
|m2                                                                           |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|                                                                             |
|2                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|metry.m2                                                                     |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|lity.m2                                                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|.m2                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|.m2                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|                                                                             |
|                                                                             |
|esolutions.m2                                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|                                                                             |
|ulus.m2                                                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|.m2                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|.m2                                                                          |
|                                                                             |
|s.m2                                                                         |
|n.m2                                                                         |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|s.m2                                                                         |
|                                                                             |
|                                                                             |
|2                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|                                                                             |
|ion.m2                                                                       |
|2                                                                            |
|                                                                             |
|lution.m2                                                                    |
|mallFiniteFields.m2                                                          |
|m2                                                                           |
|s.m2                                                                         |
|.m2                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ng.m2                                                                        |
|                                                                             |
|p.m2                                                                         |
|2                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|tations.m2                                                                   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|s.m2                                                                         |
|                                                                             |
|                                                                             |
|tems.m2                                                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|.m2                                                                          |
|                                                                             |
|                                                                             |
|ms.m2                                                                        |
|2                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|eisnerRings.m2                                                               |
|a.m2                                                                         |
|                                                                             |
|                                                                             |
|ies.m2                                                                       |
|m2                                                                           |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|arization.m2                                                                 |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|s.m2                                                                         |
|                                                                             |
|                                                                             |
|ity.m2                                                                       |
|Decomposition.m2                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|                                                                             |
|                                                                             |
|sByRoos.m2                                                                   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|s.m2                                                                         |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|plexes.m2                                                                    |
|ation.m2                                                                     |
|                                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|                                                                             |
|s.m2                                                                         |
|                                                                             |
|                                                                             |
|m2                                                                           |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|                                                                             |
|2                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|metry.m2                                                                     |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|lity.m2                                                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|.m2                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|.m2                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|                                                                             |
|                                                                             |
|esolutions.m2                                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|                                                                             |
|ulus.m2                                                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|.m2                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|.m2                                                                          |
|                                                                             |
|s.m2                                                                         |
|n.m2                                                                         |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|s.m2                                                                         |
|                                                                             |
|                                                                             |
|2                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|                                                                             |
|ion.m2                                                                       |
|2                                                                            |
|                                                                             |
|lution.m2                                                                    |
|mallFiniteFields.m2                                                          |
|m2                                                                           |
|s.m2                                                                         |
|.m2                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ng.m2                                                                        |
|                                                                             |
|p.m2                                                                         |
|2                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|tations.m2                                                                   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|s.m2                                                                         |
|                                                                             |
|                                                                             |
|tems.m2                                                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|.m2                                                                          |
|                                                                             |
|                                                                             |
|ms.m2                                                                        |
|2                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|m2                                                                           |
|eisnerRings.m2                                                               |
|a.m2                                                                         |
|                                                                             |
|                                                                             |
|ies.m2                                                                       |
|m2                                                                           |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|arization.m2                                                                 |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|s.m2                                                                         |
|                                                                             |
|                                                                             |
|ity.m2                                                                       |
|Decomposition.m2                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|                                                                             |
|                                                                             |
|sByRoos.m2                                                                   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|s.m2                                                                         |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|plexes.m2                                                                    |
|ation.m2                                                                     |
|                                                                             |
|                                                                             |
|                                                                             |
|2                                                                            |
|_packages.m2                                                                 |
|_doc.m2                                                                      |
|ls.m2                                                                        |
|_modules.m2                                                                  |
|le.m2                                                                        |
|blematrices.m2                                                               |
|maps.m2                                                                      |
|gnment.m2                                                                    |
|2                                                                            |
|ng_started.m2                                                                |
|s.m2                                                                         |
|aps.m2                                                                       |
|ces.m2                                                                       |
|age.m2                                                                       |
|.m2                                                                          |
|m2                                                                           |
|2                                                                            |
|                                                                             |
|g.m2                                                                         |
|hmetic.m2                                                                    |
|.m2                                                                          |
|s.m2                                                                         |
|element.m2                                                                   |
|s.m2                                                                         |
|ngs.m2                                                                       |
|es.m2                                                                        |
|s/dotdot.m2                                                                  |
|s.m2                                                                         |
|.m2                                                                          |
|erings.m2                                                                    |
|s/regex-doc.m2                                                               |
|s/package-doc.m2                                                             |
|s/document-doc.m2                                                            |
|s/help-doc.m2                                                                |
|s/accumulate-doc.m2                                                          |
|s/all-doc.m2                                                                 |
|s/ambient-doc.m2                                                             |
|s/antipode-doc.m2                                                            |
|s/any-doc.m2                                                                 |
|s/append-doc.m2                                                              |
|s/apply-doc.m2                                                               |
|s/applyKeys-doc.m2                                                           |
|s/applyPairs-doc.m2                                                          |
|s/applyValues-doc.m2                                                         |
|s/atan-doc.m2                                                                |
|s/baseRing-doc.m2                                                            |
|s/basis-doc.m2                                                               |
|s/Beta-doc.m2                                                                |
|s/betti-doc.m2                                                               |
|s/between-doc.m2                                                             |
|s/binomial-doc.m2                                                            |
|s/ceiling-doc.m2                                                             |
|s/chainComplex-doc.m2                                                        |
|s/changeBase-doc.m2                                                          |
|s/char-doc.m2                                                                |
|s/characters-doc.m2                                                          |
|s/check-doc.m2                                                               |
|s/class-doc.m2                                                               |
|s/clean-doc.m2                                                               |
|s/codim-doc.m2                                                               |
|s/coefficientRing-doc.m2                                                     |
|s/coefficient-doc.m2                                                         |
|s/cohomology-doc.m2                                                          |
|s/commonest-doc.m2                                                           |
|s/cpuTime-doc.m2                                                             |
|s/coimage-doc.m2                                                             |
|s/cokernel-doc.m2                                                            |
|s/comodule-doc.m2                                                            |
|s/compositions-doc.m2                                                        |
|s/compress-doc.m2                                                            |
|s/cos-doc.m2                                                                 |
|s/cover-doc.m2                                                               |
|s/deepSplice-doc.m2                                                          |
|s/degree-doc.m2                                                              |
|s/degreeLength-doc.m2                                                        |
|s/degrees-doc.m2                                                             |
|s/degreesRing-doc.m2                                                         |
|s/denominator-doc.m2                                                         |
|s/det-doc.m2                                                                 |
|s/delete-doc.m2                                                              |
|s/demark-doc.m2                                                              |
|s/describe-doc.m2                                                            |
|s/diagonalMatrix-doc.m2                                                      |
|s/diff-doc.m2                                                                |
|s/dim-doc.m2                                                                 |
|s/directSum-doc.m2                                                           |
|s/drop-doc.m2                                                                |
|s/eigenvalues-doc.m2                                                         |
|s/eigenvectors-doc.m2                                                        |
|s/elements-doc.m2                                                            |
|s/entries-doc.m2                                                             |
|s/erf-doc.m2                                                                 |
|s/examples-doc.m2                                                            |
|s/export-doc.m2                                                              |
|s/Ext-doc.m2                                                                 |
|s/factor-doc.m2                                                              |
|s/fileExists-doc.m2                                                          |
|s/fileTime-doc.m2                                                            |
|s/findFiles-doc.m2                                                           |
|s/findProgram-doc.m2                                                         |
|s/findSynonyms-doc.m2                                                        |
|s/first-doc.m2                                                               |
|s/flatten-doc.m2                                                             |
|s/flattenRing-doc.m2                                                         |
|s/floor-doc.m2                                                               |
|s/forceGB-doc.m2                                                             |
|s/fold-doc.m2                                                                |
|s/frac-doc.m2                                                                |
|s/gb-doc.m2                                                                  |
|s/gbRemove-doc.m2                                                            |
|s/gbSnapshot-doc.m2                                                          |
|s/generators-doc.m2                                                          |
|s/genericMatrix-doc.m2                                                       |
|s/genericSkewMatrix-doc.m2                                                   |
|s/genericSymmetricMatrix-doc.m2                                              |
|s/getNonUnit-doc.m2                                                          |
|s/Gamma-doc.m2                                                               |
|s/GF-doc.m2                                                                  |
|s/Grassmannian-doc.m2                                                        |
|s/graphIdeal-doc.m2                                                          |
|s/graphRing-doc.m2                                                           |
|s/HH-doc.m2                                                                  |
|s/heft-doc.m2                                                                |
|s/hilbertFunction-doc.m2                                                     |
|s/hilbertPolynomial-doc.m2                                                   |
|s/hilbertSeries-doc.m2                                                       |
|s/Hom-doc.m2                                                                 |
|s/homology-doc.m2                                                            |
|s/hooks-doc.m2                                                               |
|s/horizontalJoin-doc.m2                                                      |
|s/html-doc.m2                                                                |
|s/ideal-doc.m2                                                               |
|s/image-doc.m2                                                               |
|s/independentSets-doc.m2                                                     |
|s/index-doc.m2                                                               |
|s/indices-doc.m2                                                             |
|s/inducedMap-doc.m2                                                          |
|s/insert-doc.m2                                                              |
|s/installAssignmentMethod-doc.m2                                             |
|s/instances-doc.m2                                                           |
|s/intersect-doc.m2                                                           |
|s/integrate-doc.m2                                                           |
|s/inverse-doc.m2                                                             |
|s/irreducibleCharacteristicSeries-doc.m2                                     |
|s/isAffineRing-doc.m2                                                        |
|s/isCommutative-doc.m2                                                       |
|s/isDirectory-doc.m2                                                         |
|s/isField-doc.m2                                                             |
|s/isFreeModule-doc.m2                                                        |
|s/isGlobalSymbol-doc.m2                                                      |
|s/isHomogeneous-doc.m2                                                       |
|s/isIdeal-doc.m2                                                             |
|s/isInjective-doc.m2                                                         |
|s/isModule-doc.m2                                                            |
|s/isMonomialIdeal-doc.m2                                                     |
|s/isPolynomialRing-doc.m2                                                    |
|s/isPrime-doc.m2                                                             |
|s/isQuotientModule-doc.m2                                                    |
|s/isQuotientRing-doc.m2                                                      |
|s/isRegularFile-doc.m2                                                       |
|s/isRing-doc.m2                                                              |
|s/isSkewCommutative-doc.m2                                                   |
|s/isSorted-doc.m2                                                            |
|s/isSquareFree-doc.m2                                                        |
|s/isSubmodule-doc.m2                                                         |
|s/isSubset-doc.m2                                                            |
|s/isUnit-doc.m2                                                              |
|s/isWellDefined-doc.m2                                                       |
|s/jacobian-doc.m2                                                            |
|s/join-doc.m2                                                                |
|s/kernel-doc.m2                                                              |
|s/koszul-doc.m2                                                              |
|s/last-doc.m2                                                                |
|s/leadCoefficient-doc.m2                                                     |
|s/leadComponent-doc.m2                                                       |
|s/leadMonomial-doc.m2                                                        |
|s/length-doc.m2                                                              |
|s/lift-doc.m2                                                                |
|s/liftable-doc.m2                                                            |
|s/locate-doc.m2                                                              |
|s/LU-doc.m2                                                                  |
|s/map-doc.m2                                                                 |
|s/max-doc.m2                                                                 |
|s/maxPosition-doc.m2                                                         |
|s/match-doc.m2                                                               |
|s/mathML-doc.m2                                                              |
|s/matrix-doc.m2                                                              |
|s/member-doc.m2                                                              |
|s/merge-doc.m2                                                               |
|ns/method-doc.m2                                                             |
|ns/min-doc.m2                                                                |
|ns/mingens-doc.m2                                                            |
|ns/mingle-doc.m2                                                             |
|ns/minimalBetti-doc.m2                                                       |
|ns/minimalPresentation-doc.m2                                                |
|ns/minors-doc.m2                                                             |
|ns/minPosition-doc.m2                                                        |
|ns/monoid-doc.m2                                                             |
|ns/monomialIdeal-doc.m2                                                      |
|ns/monomials-doc.m2                                                          |
|ns/net-doc.m2                                                                |
|ns/newRing-doc.m2                                                            |
|ns/nextPrime-doc.m2                                                          |
|ns/number-doc.m2                                                             |
|ns/numerator-doc.m2                                                          |
|ns/numgens-doc.m2                                                            |
|ns/options-doc.m2                                                            |
|ns/pack-doc.m2                                                               |
|ns/parallelism-doc.m2                                                        |
|ns/part-doc.m2                                                               |
|ns/parts-doc.m2                                                              |
|ns/partition-doc.m2                                                          |
|ns/partitions-doc.m2                                                         |
|ns/pdim-doc.m2                                                               |
|ns/peek-doc.m2                                                               |
|ns/permanents-doc.m2                                                         |
|ns/pfaffians-doc.m2                                                          |
|ns/pivots-doc.m2                                                             |
|ns/poincare-doc.m2                                                           |
|ns/polarize-doc.m2                                                           |
|ns/position-doc.m2                                                           |
|ns/positions-doc.m2                                                          |
|ns/preimage-doc.m2                                                           |
|ns/prepend-doc.m2                                                            |
|ns/presentation-doc.m2                                                       |
|ns/promote-doc.m2                                                            |
|ns/pseudoRemainder-doc.m2                                                    |
|ns/pushForward-doc.m2                                                        |
|ns/QRDecomposition-doc.m2                                                    |
|ns/quotient-remainder-doc.m2                                                 |
|ns/random-doc.m2                                                             |
|ns/rank-doc.m2                                                               |
|ns/readDirectory-doc.m2                                                      |
|ns/readlink-doc.m2                                                           |
|ns/realpath-doc.m2                                                           |
|ns/reducedRowEchelonForm-doc.m2                                              |
|ns/reduceHilbert-doc.m2                                                      |
|ns/regularity-doc.m2                                                         |
|ns/removeDirectory-doc.m2                                                    |
|ns/replace-doc.m2                                                            |
|ns/resolution-doc.m2                                                         |
|ns/reverse-doc.m2                                                            |
|ns/ring-doc.m2                                                               |
|ns/roots-doc.m2                                                              |
|ns/rsort-doc.m2                                                              |
|ns/runProgram-doc.m2                                                         |
|ns/same-doc.m2                                                               |
|ns/scan-doc.m2                                                               |
|ns/schreyerOrder-doc.m2                                                      |
|ns/select-doc.m2                                                             |
|ns/separate-doc.m2                                                           |
|ns/setRandomSeed-doc.m2                                                      |
|ns/setupLift-doc.m2                                                          |
|ns/setupPromote-doc.m2                                                       |
|ns/show-doc.m2                                                               |
|ns/sin-doc.m2                                                                |
|ns/sinh-doc.m2                                                               |
|ns/smithNormalForm-doc.m2                                                    |
|ns/solve-doc.m2                                                              |
|ns/someTerms-doc.m2                                                          |
|ns/sort-doc.m2                                                               |
|ns/sortColumns-doc.m2                                                        |
|ns/source-doc.m2                                                             |
|ns/splice-doc.m2                                                             |
|ns/standardPairs-doc.m2                                                      |
|ns/sublists-doc.m2                                                           |
|ns/submatrix-doc.m2                                                          |
|ns/subquotient-doc.m2                                                        |
|ns/subsets-doc.m2                                                            |
|ns/substring-doc.m2                                                          |
|ns/support-doc.m2                                                            |
|ns/SVD-doc.m2                                                                |
|ns/switch-doc.m2                                                             |
|ns/symbol-percent-doc.m2                                                     |
|ns/symbol-underscore-doc.m2                                                  |
|ns/symmetricAlgebra-doc.m2                                                   |
|ns/syz-doc.m2                                                                |
|ns/take-doc.m2                                                               |
|ns/tally-doc.m2                                                              |
|ns/tan-doc.m2                                                                |
|ns/tanh-doc.m2                                                               |
|ns/target-doc.m2                                                             |
|ns/tensor-doc.m2                                                             |
|ns/terms-doc.m2                                                              |
|ns/tests-doc.m2                                                              |
|ns/tex-doc.m2                                                                |
|ns/texMath-doc.m2                                                            |
|ns/toExternalString-doc.m2                                                   |
|ns/toField-doc.m2                                                            |
|ns/toList-doc.m2                                                             |
|ns/Tor-doc.m2                                                                |
|ns/toString-doc.m2                                                           |
|ns/topCoefficients-doc.m2                                                    |
|ns/transpose-doc.m2                                                          |
|ns/trim-doc.m2                                                               |
|ns/truncate-doc.m2                                                           |
|ns/uniform-doc.m2                                                            |
|ns/unique-doc.m2                                                             |
|ns/urlEncode-doc.m2                                                          |
|ns/use-doc.m2                                                                |
|ns/vars-doc.m2                                                               |
|ns/wedgeProduct-doc.m2                                                       |
|ns/weightRange-doc.m2                                                        |
|ns.m2                                                                        |
|m2                                                                           |
|2                                                                            |
|.m2                                                                          |
|rators.m2                                                                    |
|mented_assignment.m2                                                         |
|mic.m2                                                                       |
|.m2                                                                          |
|ented.m2                                                                     |
|ular-Book.m2                                                                 |
|2                                                                            |
|                                                                             |
|ex.m2                                                                        |
|tions.m2                                                                     |
|exMap.m2                                                                     |
|                                                                             |
|                                                                             |
|exDoc.m2                                                                     |
|exMapDoc.m2                                                                  |
|exTests.m2                                                                   |
|tionTests.m2                                                                 |
|                                                                             |
|m2                                                                           |
|Code.m2                                                                      |
|Documentation.m2                                                             |
|Tests.m2                                                                     |
|m2                                                                           |
|                                                                             |
|                                                                             |
|m2                                                                           |
|                                                                             |
|m2                                                                           |
|s.m2                                                                         |
|d.m2                                                                         |
|lic.m2                                                                       |
|sic.m2                                                                       |
|.m2                                                                          |
|n.m2                                                                         |
|ics.m2                                                                       |
|eral.m2                                                                      |
|                                                                             |
|tests.m2                                                                     |
|doc.m2                                                                       |
|m2                                                                           |
|stems.m2                                                                     |
|onicalSeries.m2                                                              |
|fOps.m2                                                                      |
|/tests.m2                                                                    |
|/canonicalSeries.m2                                                          |
|/main.m2                                                                     |
|/DiffOps.m2                                                                  |
|/Dsystems.m2                                                                 |
|/canonicalSeries.m2                                                          |
|                                                                             |
|BFunction.m2                                                                 |
|Function.m2                                                                  |
|ion.ideal.m2                                                                 |
|ion.module.m2                                                                |
|lierIdeals.m2                                                                |
|m2                                                                           |
|poly.m2                                                                      |
|osure.m2                                                                     |
|ution.m2                                                                     |
|iction.m2                                                                    |
|ize.m2                                                                       |
|2                                                                            |
|.m2                                                                          |
|ohom.m2                                                                      |
|                                                                             |
|ectionCohom.m2                                                               |
|sts.m2                                                                       |
|in.m2                                                                        |
|om.m2                                                                        |
|ocalize.m2                                                                   |
|estriction.m2                                                                |
|ylClosure.m2                                                                 |
|nFs.m2                                                                       |
|unctions.m2                                                                  |
|calCohom.m2                                                                  |
|tersectionCohom.m2                                                           |
|ltiplierIdeals.m2                                                            |
|co-anton-paper.m2                                                            |
|her.m2                                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * load -- read Macaulay2 commands

For the programmer
==================

The object loadedFiles, is a mutable hash table.

local -- get a local symbol
***************************

Description
===========

local s provides the local symbol s, creating a new symbol if necessary.  The
initial value of a local symbol is null.
+--------------------------+
|i1 : f = () -> ZZ[local t]|
|                          |
|o1 = f                    |
|                          |
|o1 : FunctionClosure      |
+--------------------------+
|i2 : f()                  |
|                          |
|o2 = ZZ[t]                |
|                          |
|o2 : PolynomialRing       |
+--------------------------+
|i3 : t                    |
|                          |
|o3 = t                    |
|                          |
|o3 : Symbol               |
+--------------------------+

See also
========

  * global -- get a global symbol
  * symbol -- get a symbol

For the programmer
==================

The object local, is a keyword.

localDictionaries -- get local dictionaries
*******************************************

Synopsis
========

  * Usage:
        localDictionaries f
  * Inputs:
      * f, () or a function, a symbol, an
        instance of the type PseudocodeClosure, or a
        dictionary,
  * Outputs:
      * a list, a list of the local dictionaries associated with
        the lexical scopes containing f

Description
===========

+-----------------------------------------------------------------------------+
|i1 : f := x -> y -> z -> 11;                                                 |
+-----------------------------------------------------------------------------+
|i2 : d := localDictionaries ((f 22) 33)                                      |
|                                                                             |
|o2 = {LocalDictionary{...1...}, LocalDictionary{...1...},                    |
|     ------------------------------------------------------------------------|
|     LocalDictionary{...2...}}                                               |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : peek d                                                                  |
|                                                                             |
|o3 = {LocalDictionary{"y" => y}, LocalDictionary{"x" => x},                  |
|                                                                             |
|     ------------------------------------------------------------------------|
|     LocalDictionary{"d" => d}}                                              |
|                     "f" => f                                                |
+-----------------------------------------------------------------------------+
|i4 : d#0#"y"                                                                 |
|                                                                             |
|o4 = y                                                                       |
|                                                                             |
|o4 : Symbol                                                                  |
+-----------------------------------------------------------------------------+
|i5 : value d#0#"y"                                                           |
|                                                                             |
|o5 = 33                                                                      |
+-----------------------------------------------------------------------------+
|i6 : peek localDictionaries()                                                |
|                                                                             |
|o6 = {LocalDictionary{"d" => d}}                                             |
|                      "f" => f                                               |
+-----------------------------------------------------------------------------+

Ways to use localDictionaries:
==============================

  * "localDictionaries(Dictionary)"
  * "localDictionaries(FunctionClosure)"
  * "localDictionaries(PseudocodeClosure)"
  * "localDictionaries(Symbol)"
  * localDictionaries(CompiledFunction) (missing documentation)
  * localDictionaries(CompiledFunctionClosure) (missing documentation)
  * localDictionaries(Sequence) (missing documentation)

For the programmer
==================

The object localDictionaries, is a compiled function.

LocalDictionary -- the class of all local dictionaries
******************************************************

Description
===========

A local dictionary is one used in connection with a local scope, such as one
that is bounded by the body of a function closure. A local dictionary is
created on the fly by the interpreter, and after the scope has been closed, the
dictionary can be enlarged no further. Accessing local dictionaries can be a
useful debugging tool.  The local dictionaries accessible to the user come with
frames, so their symbols have values; thus they may be referred to as
dictionary closures.

See also
========

  * localDictionaries -- get local dictionaries
  * GlobalDictionary -- the class of all global
    dictionaries

For the programmer
==================

The object LocalDictionary, is a type, with
ancestor classes Dictionary, < Thing.

locate -- locate source code
****************************

Synopsis
========

  * Usage:
        locate f
  * Inputs:
      * x, a function, a sequence, a
        symbol, a list, or an integer,
  * Outputs:
      * a file position, a list, or
        null, {filename, start,startcol, stop,stopcol, pos,poscol},
        respectively

Description
===========

For a symbol interpreted function f, returns a FilePosition{n,i,c,j,d,k,e}
describing the location of the definition in the source code:

The name of the source file is n;
---------------------------------

the code occupies line i column c through line j column d;
----------------------------------------------------------

the central point of interest located at line k column e.
---------------------------------------------------------

+-----------------------------------------------------------------------------+
|i1 : locate needs                                                            |
|                                                                             |
|o1 = /usr/local/share/Macaulay2/Core/Core.m2:115:8-117:56                    |
|                                                                             |
|o1 : FilePosition                                                            |
+-----------------------------------------------------------------------------+
|i2 : code needs                                                              |
|                                                                             |
|o2 = /usr/local/share/Macaulay2/Core/Core.m2:115:8-117:56:                   |
|     --source code:                                                          |
|     needs = filename -> if not filesLoaded#?filename then load filename else|
|          (filepath, filetime) := filesLoaded#filename;                      |
|          if filetime < fileTime filepath then load filepath)                |
|-----------------------------------------------------------------------------|
|(                                                                            |
+-----------------------------------------------------------------------------+

If f is a sequence, then lookup, is applied first, and the
location of the resulting function is provided.

+---------------------------------------------------------+
|i3 : locate(resolution, Module)                          |
|                                                         |
|o3 = /usr/local/share/Macaulay2/Core/res.m2:283:37-310:90|
|                                                         |
|o3 : FilePosition                                        |
+---------------------------------------------------------+

In particular, the output of methods, can be used as an input to
locate.

+-----------------------------------------------------------------------------+
|i4 : locate methods resolution                                               |
|                                                                             |
|o4 = {0 => (/usr/local/share/Macaulay2/Core/res.m2:282:37-282:78)}           |
|     {1 => (/usr/local/share/Macaulay2/Core/res.m2:283:37-310:90)}           |
|     {2 => (/usr/local/share/Macaulay2/Core/res.m2:312:40-313:69)}           |
|                                                                             |
|o4 : NumberedVerticalList                                                    |
+-----------------------------------------------------------------------------+
|i5 : methods doc                                                             |
|                                                                             |
|o5 = {0 => (doc, String)}                                                    |
|                                                                             |
|o5 : NumberedVerticalList                                                    |
+-----------------------------------------------------------------------------+
|i6 : locate 0                                                                |
|                                                                             |
|o6 = /usr/local/share/Macaulay2/SimpleDoc.m2:35:14-43:93                     |
|                                                                             |
|o6 : FilePosition                                                            |
+-----------------------------------------------------------------------------+
|i7 : peek oo                                                                 |
|                                                                             |
|o7 = FilePosition{/usr/local/share/Macaulay2/                                |
|     ------------------------------------------------------------------------|
|     SimpleDoc.m2, 35, 14, 43, 93, 35, 14}                                   |
+-----------------------------------------------------------------------------+

If the function f is compiled, or if f is null, then a location is
not available and null, is returned.

See also
========

  * code -- display source code
  * methods -- list methods
  * locate(DocumentTag) -- the class of all document tags

Ways to use locate:
===================

  * "locate(DocumentTag)" -- see DocumentTag, -- the class
    of all document tags
  * "locate(Function)"
  * "locate(FunctionBody)"
  * "locate(List)"
  * "locate(Nothing)"
  * "locate(Pseudocode)"
  * "locate(Sequence)"
  * "locate(Symbol)"
  * "locate(ZZ)"
  * locate(Command) (missing documentation)
  * "locate(TestInput)" -- see tests, -- locate a package's tests

For the programmer
==================

The object locate, is a method function with a single argument.

log -- logarithm function
*************************

Synopsis
========

  * Usage:
        log x
        log(b,x)
        log_b x
        log I
        log(b,I)
        log_b I
        log(J,x)
        log_J x
        log(J,I)
        log_J I
  * Inputs:
      * x, a real number,
      * b, a real number, the base for the logarithm
      * I, a real interval,
      * J, a real interval, an interval of bases for the logarithm
  * Outputs:
      * the logarithm of x
      * a real interval, an interval containing the logarithms of
        points of I
      * a real interval, an interval containing the logarithms for
        bases in J

Description
===========

+-------------------------------------+
|i1 : log 10                          |
|                                     |
|o1 = 2.302585092994046               |
|                                     |
|o1 : RR (of precision 53)            |
+-------------------------------------+
|i2 : log_2 10                        |
|                                     |
|o2 = 3.321928094887363               |
|                                     |
|o2 : RR (of precision 53)            |
+-------------------------------------+
|i3 : log_10 2p100                    |
|                                     |
|o3 = .3010299956639811952137388947246|
|                                     |
|o3 : RR (of precision 100)           |
+-------------------------------------+

Ways to use log:
================

  * "log(CC)"
  * "log(RR)"
  * "log(RR,CC)"
  * "log(RR,RR)"
  * "log(RR,RRi)"
  * "log(RRi)"
  * "log(RRi,RR)"
  * "log(RRi,RRi)"

For the programmer
==================

The object log, is a method function.

log1p -- logarithm of 1+x
*************************

Synopsis
========

  * Usage:
        log1p x
        log1p I
  * Inputs:
      * x, a complex number, or a real number,
      * I, a real interval,
  * Outputs:
      * a real number, or a complex number, the logarithm
        of 1+x
      * a real interval, an interval containing logarithm of 1 plus
        the points of I

Description
===========

+-----------------------------------------+
|i1 : log1p 1p100e-10                     |
|                                         |
|o1 = 9.999999999500000000033333333333e-11|
|                                         |
|o1 : RR (of precision 100)               |
+-----------------------------------------+
|i2 : log(1 + 1p100e-10)                  |
|                                         |
|o2 = 9.999999999500000000059340457244e-11|
|                                         |
|o2 : RR (of precision 100)               |
+-----------------------------------------+

Ways to use log1p:
==================

  * "log1p(CC)"
  * "log1p(RR)"
  * "log1p(RRi)"
  * log1p(RingElement) (missing documentation)

For the programmer
==================

The object log1p, is a method function.

LongPolynomial -- a Strategy option value
*****************************************

Description
===========

LongPolynomial -- a strategy used with the keyword Strategy.

Indicates that during computation of a Gröbner basis, the reduction routine
will be replaced by one that will handle long polynomials more efficiently
using "geobuckets", which accommodate the terms in buckets of geometrically
increasing length.  This method was first used successfully by Thomas Yan,
graduate student in CS at Cornell.

See also
========

  * gb(...,Strategy=>...) -- compute a Gröbner basis

For the programmer
==================

The object LongPolynomial, is a symbol.

lookup -- look up methods
*************************

Description
===========

lookup(M,A) -- provides the unary method named M for class A. The first place
to look is A#M.  The search proceeds with the parent of A, and so on.

lookup(M,A,B) -- provides the binary method named M for (A,B). The first place
to look is Y#(M,A,B) where Y is the younger of A and B.  The search proceeds
next with the parent of B, and so on.

lookup(M,A,B,C) -- provides the ternary method named M for (A,B,C).  The first
place to look is Y#(M,A,B,C) where Y is the youngest of A, B, and C.  The
search proceeds with the parent of C, and so on.

lookup(M,A,B,C,D) -- provides the quaternary method named M for (A,B,C,D).  The
first place to look is Y#(M,A,B,C,D) where Y is the youngest of A, B, C, and D.
The search proceeds with the parent of D, and so on.

lookup x -- where x is a symbol or function, returns x.

If no method is found, then null, is returned.

See also
========

  * # -- length or access to elements
  * installMethod -- install methods
  * youngest -- the youngest member of a sequence

For the programmer
==================

The object lookup, is a compiled function.

lookupCount -- reference count for a symbol
*******************************************

Description
===========

lookupCount s -- the number of times the symbol s has been encountered in
source code presented to the interpreter.

For the programmer
==================

The object lookupCount, is a compiled function.

LUdecomposition -- LU decomposition
***********************************

Synopsis
========

  * Usage:
        (P,L,U) = LUdecomposition A
  * Inputs:
      * A, a mutable matrix, or a matrix,
        of size m by n, over a a finite field ZZ/p, see RR, or
        CC,
  * Outputs:
      * P, a list, of integers in [0, ..., m-1] forming a
        permutation
      * L, a mutable matrix, or a matrix,
        an m by min(m,n) lower triangular matrix, with 1's on the diagonal
      * U, a mutable matrix, or a matrix,
        a min(m,n) by n upper triangular matrix

Description
===========

The output matrices are mutable exactly when the input matrix is, but the
matrix A is not modified

If Q is the m by m permutation matrix such that Q_(P_i,i) = 1, and all other
entries are zero, then A = QLU.

There are several restrictions.  The first is that there are only a limited
number of rings for which this function is implemented. Second, if A is a
mutable matrix  defined over RR or CC, then A must be densely encoded.  This
restriction is not present if A is a matrix.

+--------------------------------------------------+
|i1 : kk = ZZ/101                                  |
|                                                  |
|o1 = kk                                           |
|                                                  |
|o1 : QuotientRing                                 |
+--------------------------------------------------+
|i2 : A = matrix"1,2,3,4;1,3,6,10;19,7,11,13" ** kk|
|                                                  |
|o2 = | 1  2 3  4  |                               |
|     | 1  3 6  10 |                               |
|     | 19 7 11 13 |                               |
|                                                  |
|              3       4                           |
|o2 : Matrix kk  <-- kk                            |
+--------------------------------------------------+
|i3 : (P,L,U) = LUdecomposition A                  |
|                                                  |
|o3 = ({0, 1, 2}, | 1  0   0 |, | 1 2 3  4  |)     |
|                 | 1  1   0 |  | 0 1 3  6  |      |
|                 | 19 -31 1 |  | 0 0 47 22 |      |
|                                                  |
|o3 : Sequence                                     |
+--------------------------------------------------+
|i4 : Q = id_(kk^3) _ P                            |
|                                                  |
|o4 = | 1 0 0 |                                    |
|     | 0 1 0 |                                    |
|     | 0 0 1 |                                    |
|                                                  |
|              3       3                           |
|o4 : Matrix kk  <-- kk                            |
+--------------------------------------------------+
|i5 : Q * L * U == matrix A                        |
|                                                  |
|o5 = true                                         |
+--------------------------------------------------+
For matrices over RR or CC, this function calls the lapack routines, which are
restricted to 53 bits of precision.
+-----------------------------------------------------------------------------+
|i6 : A = matrix"1,2,3,4,5,6;1,3,6,12,13,16;19,7,11,47,48,21" ** RR           |
|                                                                             |
|o6 = | 1  2 3  4  5  6  |                                                    |
|     | 1  3 6  12 13 16 |                                                    |
|     | 19 7 11 47 48 21 |                                                    |
|                                                                             |
|                3         6                                                  |
|o6 : Matrix RR    <-- RR                                                     |
|              53        53                                                   |
+-----------------------------------------------------------------------------+
|i7 : (P,L,U) = LUdecomposition A                                             |
|                                                                             |
|o7 = ({2, 1, 0}, | 1        0   0 |, | 19 7       11      47      48         |
|                 | .0526316 1   0 |  | 0  2.63158 5.42105 9.52632 10.4737    |
|                 | .0526316 .62 1 |  | 0  0       -.94    -4.38   -4.02      |
|     ------------------------------------------------------------------------|
|     21      |)                                                              |
|     14.8947 |                                                               |
|     -4.34   |                                                               |
|                                                                             |
|o7 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i8 : Q = id_ (RR^3) _ P                                                      |
|                                                                             |
|o8 = | 0 0 1 |                                                               |
|     | 0 1 0 |                                                               |
|     | 1 0 0 |                                                               |
|                                                                             |
|                3         3                                                  |
|o8 : Matrix RR    <-- RR                                                     |
|              53        53                                                   |
+-----------------------------------------------------------------------------+
|i9 : Q * L * U - A                                                           |
|                                                                             |
|o9 = | 0 -2.22045e-16 0 0 0 0 |                                              |
|     | 0 0            0 0 0 0 |                                              |
|     | 0 0            0 0 0 0 |                                              |
|                                                                             |
|                3         6                                                  |
|o9 : Matrix RR    <-- RR                                                     |
|              53        53                                                   |
+-----------------------------------------------------------------------------+
|i10 : clean(1e-15,oo)                                                        |
|                                                                             |
|o10 = | 0 0 0 0 0 0 |                                                        |
|      | 0 0 0 0 0 0 |                                                        |
|      | 0 0 0 0 0 0 |                                                        |
|                                                                             |
|                 3         6                                                 |
|o10 : Matrix RR    <-- RR                                                    |
|               53        53                                                  |
+-----------------------------------------------------------------------------+
Mutable matrices can sometimes be useful for speed, and/or space. If A is a
mutable matrix, it must be densely encoded (which is the default).
+-----------------------------------------------------------------------------+
|i11 : A = mutableMatrix(CC,5,10, Dense=>true)                                |
|                                                                             |
|o11 = | 0 0 0 0 0 0 0 0 0 0 |                                                |
|      | 0 0 0 0 0 0 0 0 0 0 |                                                |
|      | 0 0 0 0 0 0 0 0 0 0 |                                                |
|      | 0 0 0 0 0 0 0 0 0 0 |                                                |
|      | 0 0 0 0 0 0 0 0 0 0 |                                                |
|                                                                             |
|o11 : MutableMatrix                                                          |
+-----------------------------------------------------------------------------+
|i12 : printingPrecision = 2                                                  |
|                                                                             |
|o12 = 2                                                                      |
+-----------------------------------------------------------------------------+
|i13 : setRandomSeed 0                                                        |
|                                                                             |
|o13 = 0                                                                      |
+-----------------------------------------------------------------------------+
|i14 : fillMatrix A                                                           |
|                                                                             |
|o14 = | .89+.67ii  .91+.31ii  .35+.56ii .19+.4ii   .28+.61ii  .034+.51ii     |
|      | .29+.63ii  .074+.81ii .25+.15ii .62+.015ii .97+.68ii  .15+.66ii      |
|      | .026+.71ii .36+.71ii  .83+.54ii .22+.39ii  .91+.89ii  .17+.63ii      |
|      | .89+.23ii  .13+.25ii  .87+.42ii .56+.87ii  .17+.97ii  .35+.38ii      |
|      | .46+.78ii  .74+.11ii  .61+.85ii .7+.68ii   .065+.88ii .24+.12ii      |
|                                                                             |
|o14 : MutableMatrix                                                          |
|-----------------------------------------------------------------------------|
|.44+.64ii  .47+.4ii  .48+.82ii  .5+.15ii   |                                 |
|.19+.52ii  .16+.71ii .98+.06ii  .47+.77ii  |                                 |
|.99+.57ii  .91+.57ii .065+.28ii .31+.54ii  |                                 |
|.18+.37ii  .31+.73ii .98+.21ii  .21+.28ii  |                                 |
|.34+.062ii .56+.63ii .59+.83ii  .096+.61ii |                                 |
+-----------------------------------------------------------------------------+
|i15 : (P,L,U) = LUdecomposition A;                                           |
+-----------------------------------------------------------------------------+
|i16 : Q = id_(CC^5) _ P                                                      |
|                                                                             |
|o16 = | 1 0 0 0 0 |                                                          |
|      | 0 0 0 0 1 |                                                          |
|      | 0 0 1 0 0 |                                                          |
|      | 0 1 0 0 0 |                                                          |
|      | 0 0 0 1 0 |                                                          |
|                                                                             |
|                 5         5                                                 |
|o16 : Matrix CC    <-- CC                                                    |
|               53        53                                                  |
+-----------------------------------------------------------------------------+
|i17 : matrix Q * matrix L * matrix U - matrix A                              |
|                                                                             |
|o17 = | 0                  0          0                 0                    |
|      | -5.6e-17           0          -5.6e-17          1.1e-16              |
|      | -5.6e-17-1.1e-16ii 0          0                 0                    |
|      | -1.1e-16           0          0                 0                    |
|      | -1.1e-16-1.1e-16ii -5.6e-17ii 1.1e-16+1.1e-16ii 0                    |
|      -----------------------------------------------------------------------|
|      0                  0         0       0 0        0 |                    |
|      1.1e-16ii          -2.8e-17  5.6e-17 0 -1.1e-16 0 |                    |
|      -1.1e-16ii         0         0       0 2.8e-17  0 |                    |
|      0                  0         0       0 0        0 |                    |
|      -2.8e-17-1.1e-16ii 5.6e-17ii 0       0 0        0 |                    |
|                                                                             |
|                 5         10                                                |
|o17 : Matrix CC    <-- CC                                                    |
|               53        53                                                  |
+-----------------------------------------------------------------------------+
|i18 : clean(1e-15,oo)                                                        |
|                                                                             |
|o18 = | 0 0 0 0 0 0 0 0 0 0 |                                                |
|      | 0 0 0 0 0 0 0 0 0 0 |                                                |
|      | 0 0 0 0 0 0 0 0 0 0 |                                                |
|      | 0 0 0 0 0 0 0 0 0 0 |                                                |
|      | 0 0 0 0 0 0 0 0 0 0 |                                                |
|                                                                             |
|                 5         10                                                |
|o18 : Matrix CC    <-- CC                                                    |
|               53        53                                                  |
+-----------------------------------------------------------------------------+

Caveat
======

This function is limited in scope, but is sometimes useful for very large
matrices

See also
========

  * solve -- solve linear equation(s)
  * SVD -- singular value decomposition of a matrix
  * MutableMatrix -- the class of all mutable matrices
  * fillMatrix -- fill a mutable matrix with random numbers
  * clean -- Set to zero elements that are approximately zero
  * norm

Ways to use LUdecomposition:
============================

  * "LUdecomposition(Matrix)"
  * "LUdecomposition(MutableMatrix)"

For the programmer
==================

The object LUdecomposition, is a method function.

making modules from matrices
****************************

Let's make some matrices.
+----------------------+
|i1 : R = ZZ/101[a..c];|
+----------------------+
|i2 : f = vars R       |
|                      |
|o2 = | a b c |        |
|                      |
|             1      3 |
|o2 : Matrix R  <-- R  |
+----------------------+
We can easily compute a kernel, image, or cokernel.
+------------------------------+
|i3 : ker f                    |
|                              |
|o3 = image {1} | -b 0  -c |   |
|           {1} | a  -c 0  |   |
|           {1} | 0  b  a  |   |
|                              |
|                             3|
|o3 : R-module, submodule of R |
+------------------------------+
|i4 : coker f                  |
|                              |
|o4 = cokernel | a b c |       |
|                              |
|                            1 |
|o4 : R-module, quotient of R  |
+------------------------------+
|i5 : image f                  |
|                              |
|o5 = image | a b c |          |
|                              |
|                             1|
|o5 : R-module, submodule of R |
+------------------------------+
Every module is represented internally as a submodule of a quotient module.
Such modules often appear in computations, for example, when taking the direct
sum of a quotient module and a submodule.
+-----------------------------------------+
|i6 : image f ++ coker f                  |
|                                         |
|o6 = subquotient (| a b c 0 |, | 0 0 0 |)|
|                  | 0 0 0 1 |  | a b c | |
|                                         |
|                               2         |
|o6 : R-module, subquotient of R          |
+-----------------------------------------+
We may use subquotient, to make such modules directly,
although it's usually more convenient to use other operations.  The first
argument is the matrix whose columns are the generators, and the second
argument is the matrix whose columns are the relations.
+-------------------------------------+
|i7 : M = subquotient(f, matrix {{a}})|
|                                     |
|o7 = subquotient (| a b c |, | a |)  |
|                                     |
|                               1     |
|o7 : R-module, subquotient of R      |
+-------------------------------------+
|i8 : prune M                         |
|                                     |
|o8 = cokernel {1} | a -c 0 |         |
|              {1} | 0 b  a |         |
|                                     |
|                            2        |
|o8 : R-module, quotient of R         |
+-------------------------------------+

manipulating modules
********************

Suppose we have a module that is represented as an image of a matrix, and we
want to represent it as a cokernel of a matrix. This task may be accomplished
with prune.
+------------------------------+
|i1 : R = QQ[x,y];             |
+------------------------------+
|i2 : I = ideal vars R         |
|                              |
|o2 = ideal (x, y)             |
|                              |
|o2 : Ideal of R               |
+------------------------------+
|i3 : M = image vars R         |
|                              |
|o3 = image | x y |            |
|                              |
|                             1|
|o3 : R-module, submodule of R |
+------------------------------+
|i4 : N = prune M              |
|                              |
|o4 = cokernel {1} | -y |      |
|              {1} | x  |      |
|                              |
|                            2 |
|o4 : R-module, quotient of R  |
+------------------------------+
The isomorphism between them may be found under the key pruningMap.
+---------------------------+
|i5 : f = N.cache.pruningMap|
|                           |
|o5 = {1} | 1 0 |           |
|     {1} | 0 1 |           |
|                           |
|o5 : Matrix M <-- N        |
+---------------------------+
|i6 : isIsomorphism f       |
|                           |
|o6 = true                  |
+---------------------------+
|i7 : f^-1                  |
|                           |
|o7 = {1} | 1 0 |           |
|     {1} | 0 1 |           |
|                           |
|o7 : Matrix N <-- M        |
+---------------------------+
The matrix form of f looks nondescript, but the map knows its source and target
+------------------------------+
|i8 : source f                 |
|                              |
|o8 = cokernel {1} | -y |      |
|              {1} | x  |      |
|                              |
|                            2 |
|o8 : R-module, quotient of R  |
+------------------------------+
|i9 : target f                 |
|                              |
|o9 = image | x y |            |
|                              |
|                             1|
|o9 : R-module, submodule of R |
+------------------------------+
It's a 2 by 2 matrix because M and N are both represented as modules with two
generators.

Functions for finding related modules:
  * ambient -- ambient free module of a subquotient, or ambient
    ring
  * cover -- get the covering free module
  * super -- get the ambient module
+-----------------------------------+
|i10 : super M                      |
|                                   |
|       1                           |
|o10 = R                            |
|                                   |
|o10 : R-module, free               |
+-----------------------------------+
|i11 : cover N                      |
|                                   |
|       2                           |
|o11 = R                            |
|                                   |
|o11 : R-module, free, degrees {2:1}|
+-----------------------------------+
Some simple operations on modules:
  * Module ^ ZZ -- direct sum
  * Module ++ Module -- direct sum of modules
  * Module ** Module -- tensor product of
    modules
+-----------------------------------------------+
|i12 : M ++ N                                   |
|                                               |
|o12 = subquotient ({0} | x y 0 0 |, {0} | 0  |)|
|                   {1} | 0 0 1 0 |  {1} | -y | |
|                   {1} | 0 0 0 1 |  {1} | x  | |
|                                               |
|                                3              |
|o12 : R-module, subquotient of R               |
+-----------------------------------------------+
|i13 : M ** N                                   |
|                                               |
|o13 = cokernel {2} | -y 0  -y 0  |             |
|               {2} | x  0  0  -y |             |
|               {2} | 0  -y x  0  |             |
|               {2} | 0  x  0  x  |             |
|                                               |
|                             4                 |
|o13 : R-module, quotient of R                  |
+-----------------------------------------------+
Ideals and modules behave differently when making powers:
+-------------------------------+
|i14 : M^3                      |
|                               |
|o14 = image | x y 0 0 0 0 |    |
|            | 0 0 x y 0 0 |    |
|            | 0 0 0 0 x y |    |
|                               |
|                              3|
|o14 : R-module, submodule of R |
+-------------------------------+
|i15 : I^3                      |
|                               |
|              3   2      2   3 |
|o15 = ideal (x , x y, x*y , y )|
|                               |
|o15 : Ideal of R               |
+-------------------------------+

Manipulator -- the class of all file manipulators
*************************************************

Description
===========

A file manipulator is a type of list that, when put out to a file with
<<, causes a chosen function to be applied to the file.  Alternatively, a
manipulator can be used the way a function is used.
+--------------------------------------+
|i1 : f = new Manipulator from identity|
|                                      |
|o1 = f                                |
|                                      |
|o1 : Manipulator                      |
+--------------------------------------+
|i2 : stdio << f                       |
|                                      |
|o2 = stdio                            |
|                                      |
|o2 : File                             |
+--------------------------------------+
|i3 : f stdio                          |
|                                      |
|o3 = stdio                            |
|                                      |
|o3 : File                             |
+--------------------------------------+

Functions and methods returning a manipulator:
==============================================

  * "new Manipulator from Function"

Methods that use a manipulator:
===============================

  * "File << Manipulator" -- see File << Thing, -- print
    to a file
  * "Nothing << Manipulator" -- see File << Thing, --
    print to a file
  * "Manipulator Database"
  * "Manipulator File"
  * "Manipulator Nothing"
  * "methods(Manipulator)" -- see methods, -- list methods
  * "Manipulator NetFile" -- see NetFile, -- the class of all
    net files
  * "NetFile << Manipulator" -- see NetFile, -- the class of all
    net files

Protected objects of class Manipulator:
=======================================

  * close -- close a file
  * closeIn -- close an input file
  * closeOut -- close an output file
  * endl -- end an output line
  * flush -- flush output to file

For the programmer
==================

The object Manipulator, is a type, with
ancestor classes BasicList, < Thing.

map -- make a map
*****************

Synopsis
========

  * Usage:
        map(Y,X,d) or map(Y,X)
  * Inputs:
      * Y, an object, such as a ring, module, or chain complex
      * X, another object of the same type
      * d, a specification, such as a function, list, or matrix, or if omitted,
        understood to specify the identity map
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * a map to Y from X defined by data d.

Description
===========

The function map provides a general mechanism for constructing a map
(homomorphism) between rings (a ring map), modules (a
matrix), chain complexes (a chain complex map),
or between objects in other categories.

See also the function matrix, which focuses on creating new
matrices from rectangular arrays of ring elements or matrices.

Ways to use map:
================

  * map(ChainComplex,ChainComplex,ChainComplexMap) (missing documentation)
  * map(ChainComplex,ChainComplex,Function)
    -- make a map of chain
    complexes
  * "map(GradedModule,GradedModule,Function)" -- see
    map(ChainComplex,ChainComplex,Function),
    -- make a map of chain
    complexes
  * map(CoherentSheaf,CoherentSheaf,Matrix) (missing documentation)
  * map(CoherentSheaf,CoherentSheaf,Matrix,InfiniteNumber) (missing
    documentation)
  * map(CoherentSheaf,CoherentSheaf,Matrix,ZZ) (missing documentation)
  * map(GaloisField,GaloisField) (missing documentation)
  * map(Matrix) -- make a matrix with a different
    degree
  * map(Module) -- identity map
  * map(Module,Module,Function), --
    create a matrix by specifying a function that gives each entry
  * map(Module,Module,List) -- create a
    matrix by giving a sparse or dense list of entries
  * map(Module,Module,Matrix), --
    create the matrix induced on generators by a given matrix
  * "map(Module,Module,Number)" -- see map(Module,Module,RingElement),
    -- construct the map induced by
    multiplication by a ring element on the generators
  * map(Module,Module,RingElement)
    -- construct the map induced by
    multiplication by a ring element on the generators
  * "map(Module,Module,ZZ)" -- see map(Module,Module,RingElement),
    -- construct the map induced by
    multiplication by a ring element on the generators
  * "map(Module,ZZ,ZZ)" -- see map(Module,Module,RingElement),
    -- construct the map induced by
    multiplication by a ring element on the generators
  * "map(Module,Module,RingMap,List)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * map(Module,Module,RingMap,Matrix)
    -- homomorphism of modules
    over different rings
  * "map(Module,Nothing,RingMap,List)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * "map(Module,Nothing,RingMap,Matrix)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * "map(Module,RingMap)" -- see map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * map(Module,Nothing,List) -- create
    a matrix by giving a doubly nested list of ring elements
  * map(Module,Nothing,Matrix), --
    recast a matrix to have a new target, and a free module as source
  * map(Module,ZZ,Function) -- create a
    matrix from a free module by specifying a function that gives each entry
  * map(Module,ZZ,List) -- create a matrix
    by giving a sparse or dense list of entries
  * map(Ring,Matrix) -- make a ring map
  * map(Ring,Ring) -- make a ring map, using the
    names of the variables
  * map(Ring,Ring,List) -- make a ring map
  * map(Ring,Ring,Matrix) -- make a ring
    map
  * "map(Ring,Ring,RingMap)" -- see map(Ring,Ring,Matrix),
    -- make a ring map

For the programmer
==================

The object map, is a method function with options.

Creating a map (matrix) between modules

Creating a map between modules, where the source module is computed

Creating a map with a different degree

Creating a map between modules over different rings

Creating a map between rings

Creating a map between chain complexes

map(Module,Module,Function) -- create a matrix by specifying a function that gives each entry
*********************************************************************************************

Synopsis
========

  * Function: map,
  * Usage:
        map(M,N,f)
  * Inputs:
      * M
      * N
      * f
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * a map from the module N to the module M whose matrix entry h_(i,j) is
        obtained from the function f by evaluating f(i,j).

Description
===========

Recall that all indices in Macaulay2 start at 0, so the upper left-most entry
of a matrix f is f_(0,0).

This function is often used when you already know the source and target
modules, including their gradings.  If you wish Macaulay2 to compute the column
degrees for you (so the resulting matrix will be homogeneous if possible), use
map(Module,ZZ,Function).
+-----------------------------------------------+
|i1 : R = ZZ[a..c];                             |
+-----------------------------------------------+
|i2 : f = map(R^3,R^{0,-1,-2,-3},(i,j) -> R_i^j)|
|                                               |
|o2 = | 1 a a2 a3 |                             |
|     | 1 b b2 b3 |                             |
|     | 1 c c2 c3 |                             |
|                                               |
|             3      4                          |
|o2 : Matrix R  <-- R                           |
+-----------------------------------------------+
We specified the degrees of the source basis elements explicitly to ensure the
matrix would be homogeneous.
+--------------------+
|i3 : isHomogeneous f|
|                    |
|o3 = true           |
+--------------------+

Alternate approaches
====================

We could have let Macaulay2 take care of that for us, by replacing the source
module by its desired rank.
+--------------------------------------------+
|i4 : g = map(R^3,4,(i,j) -> R_i^j)          |
|                                            |
|o4 = | 1 a a2 a3 |                          |
|     | 1 b b2 b3 |                          |
|     | 1 c c2 c3 |                          |
|                                            |
|             3      4                       |
|o4 : Matrix R  <-- R                        |
+--------------------------------------------+
|i5 : degrees g                              |
|                                            |
|o5 = {{{0}, {0}, {0}}, {{0}, {1}, {2}, {3}}}|
|                                            |
|o5 : List                                   |
+--------------------------------------------+
|i6 : isHomogeneous g                        |
|                                            |
|o6 = true                                   |
+--------------------------------------------+

Another way would be to let matrix, take care of that for us.
+--------------------------------------------+
|i7 : h = matrix table(3,4,(i,j) -> R_i^j)   |
|                                            |
|o7 = | 1 a a2 a3 |                          |
|     | 1 b b2 b3 |                          |
|     | 1 c c2 c3 |                          |
|                                            |
|             3      4                       |
|o7 : Matrix R  <-- R                        |
+--------------------------------------------+
|i8 : degrees h                              |
|                                            |
|o8 = {{{0}, {0}, {0}}, {{0}, {1}, {2}, {3}}}|
|                                            |
|o8 : List                                   |
+--------------------------------------------+
|i9 : isHomogeneous h                        |
|                                            |
|o9 = true                                   |
+--------------------------------------------+

Ways to use this method:
========================

  * map(Module,Module,Function), --
    create a matrix by specifying a function that gives each entry

map(Module,Module,List) -- create a matrix by giving a sparse or dense list of entries
**************************************************************************************

Synopsis
========

  * Function: map,
  * Usage:
        map(M,N,v)
  * Inputs:
      * M
      * N
      * v
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * A matrix M <-- N whose entries are obtained from v

Description
===========

The list v is either a doubly nested list of ring elements, or a list of
elements (i,j) => f.  The first version provides all of the elements of the
output matrix, row by row.  The second form provides only the non-zero elements
of the output matrix h: h_(i,j) = f, for every (i,j) => f in the list v.

In each case, the modules M and N should have the same base ring R, and the
ring elements appearing in v should be over R, or over a base ring of R.

In the first form, each list in v gives a row of the matrix. The length of the
list v should be the number of generators of M, and the length of each element
of v (which is itself a list of ring elements) should be the number of
generators of the source module N.
+---------------------------------------------------+
|i1 : R = ZZ/101[x,y,z];                            |
+---------------------------------------------------+
|i2 : p = map(R^2,R^{-2,-2,0},{{x^2,0,3},{0,y^2,5}})|
|                                                   |
|o2 = | x2 0  3 |                                   |
|     | 0  y2 5 |                                   |
|                                                   |
|             2      3                              |
|o2 : Matrix R  <-- R                               |
+---------------------------------------------------+
|i3 : isHomogeneous p                               |
|                                                   |
|o3 = true                                          |
+---------------------------------------------------+
In the second form, if an index (i,j) occurs more than once, only the last is
taken.
+-----------------------------------------------------------------------------+
|i4 : p = map(R^2,R^3,{(0,0) => x+y, (1,1) => x^2, (0,2) => x-1, (0,0) =>     |
|                                                                             |
|o4 = | x-y 0  x-1 |                                                          |
|     | 0   x2 0   |                                                          |
|                                                                             |
|             2      3                                                        |
|o4 : Matrix R  <-- R                                                         |
|-----------------------------------------------------------------------------|
|x-y})                                                                        |
+-----------------------------------------------------------------------------+

See also
========

  * matrix -- make a matrix
  * map(Module,Nothing,List) -- create
    a matrix by giving a doubly nested list of ring elements
  * inputting a matrix

Ways to use this method:
========================

  * map(Module,Module,List) -- create a
    matrix by giving a sparse or dense list of entries

map(Module,Module,RingElement) -- construct the map induced by multiplication by a ring element on the generators
*****************************************************************************************************************

Synopsis
========

  * Function: map,
  * Usage:
        map(M,N,r)
  * Inputs:
      * M
      * N, over the same ring R as M.  An integer here stands for the free
        module of that rank.
      * r, in the ring R
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * The map induced by multiplication by r on the generators

Description
===========

If r is not zero, then either M and N should be equal, or they should have the
same number of generators.  This gives the same map as r * map(M,N,1).
map(M,N,1) is the map induced by the identity on the generators of M and N.
+---------------------------+
|i1 : R = QQ[x];            |
+---------------------------+
|i2 : map(R^2,R^3,0)        |
|                           |
|o2 = 0                     |
|                           |
|             2      3      |
|o2 : Matrix R  <-- R       |
+---------------------------+
|i3 : f = map(R^2,R^2,x)    |
|                           |
|o3 = | x 0 |               |
|     | 0 x |               |
|                           |
|             2      2      |
|o3 : Matrix R  <-- R       |
+---------------------------+
|i4 : f == x *map(R^2,R^2,1)|
|                           |
|o4 = true                  |
+---------------------------+

Caveat
======

If M or N is not free, then we do not check that the result is a well defined
homomorphism.

See also
========

  * inducedMap -- compute an induced map

Ways to use this method:
========================

  * "map(Module,Module,Number)"
  * map(Module,Module,RingElement)
    -- construct the map induced by
    multiplication by a ring element on the generators
  * "map(Module,Module,ZZ)"
  * "map(Module,ZZ,ZZ)"

map(Module,Module,Matrix) -- create the matrix induced on generators by a given matrix
**************************************************************************************

Synopsis
========

  * Function: map,
  * Usage:
        map(M,N,p)
  * Inputs:
      * M
      * N
      * p
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * A matrix with the same entries as p, but whose target is M and source
        is N

Description
===========

M and N should be modules over the same ring, and have the same number of
generators as target p and source p, respectively.
+-------------------------+
|i1 : R = QQ[x,y,z];      |
+-------------------------+
|i2 : p = matrix {{x,y,z}}|
|                         |
|o2 = | x y z |           |
|                         |
|             1      3    |
|o2 : Matrix R  <-- R     |
+-------------------------+
|i3 : q = map(R^1,R^3,p)  |
|                         |
|o3 = | x y z |           |
|                         |
|             1      3    |
|o3 : Matrix R  <-- R     |
+-------------------------+
|i4 : degrees source p    |
|                         |
|o4 = {{1}, {1}, {1}}     |
|                         |
|o4 : List                |
+-------------------------+
|i5 : degrees source q    |
|                         |
|o5 = {{0}, {0}, {0}}     |
|                         |
|o5 : List                |
+-------------------------+

Caveat
======

If M or N is not free, then we do not check that the result is a well defined
homomorphism.

See also
========

  * inducedMap -- compute an induced map

Ways to use this method:
========================

  * map(Module,Module,Matrix), --
    create the matrix induced on generators by a given matrix

map(Module,ZZ,Function) -- create a matrix from a free module by specifying a function that gives each entry
************************************************************************************************************

Synopsis
========

  * Function: map,
  * Usage:
        map(M,n,f)
  * Inputs:
      * M
      * n
      * f
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * a map from a graded free module of rank n to the module M whose matrix
        entry h_(i,j) is obtained from the function f by evaluating f(i,j).

Description
===========

This is the same as calling map(M,R^n,f), except that the degrees of the basis
elements of the source module are chosen in an attempt to ensure that the
resulting map is homogeneous of degree zero.
+--------------------------------------------------+
|i1 : R = GF(9,Variable=>a)[x,y,z];                |
+--------------------------------------------------+
|i2 : f = map(R^1, 3, (i,j) -> (a^j * x - y)^(j+1))|
|                                                  |
|o2 = | x-y (a+1)x2+axy+y2 (-a-1)x3-y3 |           |
|                                                  |
|             1      3                             |
|o2 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i3 : source f                                     |
|                                                  |
|      3                                           |
|o3 = R                                            |
|                                                  |
|o3 : R-module, free, degrees {1..3}               |
+--------------------------------------------------+
|i4 : isHomogeneous f                              |
|                                                  |
|o4 = true                                         |
+--------------------------------------------------+

See also
========

  * map(Module,Module,Function), --
    create a matrix by specifying a function that gives each entry
  * source(Matrix) -- find the source module of
    matrix
  * isHomogeneous(Matrix) -- whether something is
    homogeneous (graded)

Ways to use this method:
========================

  * map(Module,ZZ,Function) -- create a
    matrix from a free module by specifying a function that gives each entry

map(Module,Nothing,List) -- create a matrix by giving a doubly nested list of ring elements
*******************************************************************************************

Synopsis
========

  * Function: map,
  * Usage:
        map(M,v)
  * Inputs:
      * M
      * v
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * A matrix M <-- R^n whose entries are obtained from v, where R  is the
        ring of M, and the source of the result is a graded free module chosen
        in an attempt to make the result homogeneous of degree zero

Description
===========

The list v must be a doubly nested list of ring elements, which are used to
fill the matrix, row by row.

The ring elements appearing in v should be in R, or in a base ring of R.

Each list in v gives a row of the matrix. The length of the list v should be
the number of generators of M, and the length of each element of v (which is
itself a list of ring elements) should be the number of generators of the
source module N.
+----------------------------------------+
|i1 : R = ZZ/101[x,y,z]                  |
|                                        |
|o1 = R                                  |
|                                        |
|o1 : PolynomialRing                     |
+----------------------------------------+
|i2 : p = map(R^2,,{{x^2,0,3},{0,y^2,5}})|
|                                        |
|o2 = | x2 0  3 |                        |
|     | 0  y2 5 |                        |
|                                        |
|             2      3                   |
|o2 : Matrix R  <-- R                    |
+----------------------------------------+
|i3 : isHomogeneous p                    |
|                                        |
|o3 = true                               |
+----------------------------------------+
Another way is to use the matrix(List), routine:
+-------------------------------------+
|i4 : p = matrix {{x^2,0,3},{0,y^2,5}}|
|                                     |
|o4 = | x2 0  3 |                     |
|     | 0  y2 5 |                     |
|                                     |
|             2      3                |
|o4 : Matrix R  <-- R                 |
+-------------------------------------+

The absence of the second argument indicates that the source of the map is to
be a free module constructed with an attempt made to assign degrees to its
basis elements so as to make the map homogeneous of degree zero.

+--------------------------------------+
|i5 : R = ZZ/101[x,y]                  |
|                                      |
|o5 = R                                |
|                                      |
|o5 : PolynomialRing                   |
+--------------------------------------+
|i6 : f = map(R^2,,{{x^2,y^2},{x*y,0}})|
|                                      |
|o6 = | x2 y2 |                        |
|     | xy 0  |                        |
|                                      |
|             2      2                 |
|o6 : Matrix R  <-- R                  |
+--------------------------------------+
|i7 : degrees source f                 |
|                                      |
|o7 = {{2}, {2}}                       |
|                                      |
|o7 : List                             |
+--------------------------------------+
|i8 : isHomogeneous f                  |
|                                      |
|o8 = true                             |
+--------------------------------------+

See also
========

  * matrix -- make a matrix
  * map(Module,Module,List) -- create a
    matrix by giving a sparse or dense list of entries

Ways to use this method:
========================

  * map(Module,Nothing,List) -- create
    a matrix by giving a doubly nested list of ring elements

map(Module,ZZ,List) -- create a matrix by giving a sparse or dense list of entries
**********************************************************************************

Synopsis
========

  * Function: map,
  * Usage:
        map(M,n,v)
  * Inputs:
      * M
      * n
      * v
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * A matrix M <-- R^n whose entries are obtained from v, where R  is the
        ring of M, and the source of the result is a graded free module chosen
        in an attempt to make the result homogeneous of degree zero

Description
===========

The list v is either a doubly nested list of ring elements, or a list of
elements (i,j) => f.  The first version provides all of the elements of the
output matrix, row by row.  The second form provides only the non-zero elements
of the output matrix h: h_(i,j) = f, for every (i,j) => f in the list v.

The ring elements appearing in v should be in R, or in a base ring of R.

In the first form, each list in v gives a row of the matrix. The length of the
list v should be the number of generators of M, and the length of each element
of v (which is itself a list of ring elements) should be the number of
generators of the source module N.
+-----------------------------------------+
|i1 : R = ZZ/101[x,y,z];                  |
+-----------------------------------------+
|i2 : p = map(R^2,3,{{x^2,0,3},{0,y^2,5}})|
|                                         |
|o2 = | x2 0  3 |                         |
|     | 0  y2 5 |                         |
|                                         |
|             2      3                    |
|o2 : Matrix R  <-- R                     |
+-----------------------------------------+
|i3 : isHomogeneous p                     |
|                                         |
|o3 = true                                |
+-----------------------------------------+
In the second form, if an index (i,j) occurs more than once, only the last is
taken.
+----------------------------------------------------------------------------+
|i4 : p = map(R^2,3,{(0,0) => x+y, (1,1) => x^2, (0,2) => x-1, (0,0) => x-y})|
|                                                                            |
|o4 = | x-y 0  x-1 |                                                         |
|     | 0   x2 0   |                                                         |
|                                                                            |
|             2      3                                                       |
|o4 : Matrix R  <-- R                                                        |
+----------------------------------------------------------------------------+

See also
========

  * matrix -- make a matrix
  * map(Module,Nothing,List) -- create
    a matrix by giving a doubly nested list of ring elements

Ways to use this method:
========================

  * map(Module,ZZ,List) -- create a matrix
    by giving a sparse or dense list of entries

map(Module,Nothing,Matrix) -- recast a matrix to have a new target, and a free module as source
***********************************************************************************************

Synopsis
========

  * Function: map,
  * Usage:
        map(M,,f)
  * Inputs:
      * M
      * f, whose target has the same number of generators as M
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * A map with a free source module, and target M, whose entries are those
        of f.

Description
===========

+----------------------+
|i1 : R = ZZ/101[x,y]; |
+----------------------+
|i2 : p = matrix{{x,y}}|
|                      |
|o2 = | x y |          |
|                      |
|             1      2 |
|o2 : Matrix R  <-- R  |
+----------------------+
|i3 : q = map(R^{3},,p)|
|                      |
|o3 = {-3} | x y |     |
|                      |
|             1      2 |
|o3 : Matrix R  <-- R  |
+----------------------+
|i4 : degrees target q |
|                      |
|o4 = {{-3}}           |
|                      |
|o4 : List             |
+----------------------+
|i5 : degrees source q |
|                      |
|o5 = {{-2}, {-2}}     |
|                      |
|o5 : List             |
+----------------------+

See also
========

  * matrix -- make a matrix

Ways to use this method:
========================

  * map(Module,Nothing,Matrix), --
    recast a matrix to have a new target, and a free module as source

map(Matrix) -- make a matrix with a different degree
****************************************************

Synopsis
========

  * Function: map,
  * Usage:
        map(f, Degree => d)
  * Inputs:
      * f, a matrix,
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * a map identical to f, except that it has degree d, and the source
        module has been tensored by a graded free module of rank 1 of the
        appropriate degree.

Description
===========

The input d should be an integer, or a list of integers.

This routine is often used to take a matrix that has a non-zero degree, and
make the degree zero.

For example, multiplication of a matrix by a scalar increases the degree,
leaving the source and target fixed:
+--------------------------+
|i1 : R = QQ[a,b];         |
+--------------------------+
|i2 : f1 = matrix{{a,b}}   |
|                          |
|o2 = | a b |              |
|                          |
|             1      2     |
|o2 : Matrix R  <-- R      |
+--------------------------+
|i3 : f = a * f1           |
|                          |
|o3 = | a2 ab |            |
|                          |
|             1      2     |
|o3 : Matrix R  <-- R      |
+--------------------------+
|i4 : degree f             |
|                          |
|o4 = {1}                  |
|                          |
|o4 : List                 |
+--------------------------+
|i5 : source f == source f1|
|                          |
|o5 = true                 |
+--------------------------+
One solution is to change the degree:
+-------------------------------------+
|i6 : g = map(f, Degree => 0)         |
|                                     |
|o6 = | a2 ab |                       |
|                                     |
|             1      2                |
|o6 : Matrix R  <-- R                 |
+-------------------------------------+
|i7 : degree g                        |
|                                     |
|o7 = {0}                             |
|                                     |
|o7 : List                            |
+-------------------------------------+
|i8 : source g == (source f) ** R^{-1}|
|                                     |
|o8 = true                            |
+-------------------------------------+
An alternate solution would be to use tensor product with the scalar.
+----------------------------+
|i9 : g2 = a ** matrix{{a,b}}|
|                            |
|o9 = | a2 ab |              |
|                            |
|             1      2       |
|o9 : Matrix R  <-- R        |
+----------------------------+
|i10 : degree g2             |
|                            |
|o10 = {0}                   |
|                            |
|o10 : List                  |
+----------------------------+
|i11 : isHomogeneous g2      |
|                            |
|o11 = true                  |
+----------------------------+

Ways to use this method:
========================

  * map(Matrix) -- make a matrix with a different
    degree

map(Module,Module,RingMap,Matrix) -- homomorphism of modules over different rings
*********************************************************************************

Synopsis
========

  * Function: map,
  * Usage:
        g = map(M,N,p,f)
        g = map(M,,p,f)
        g = map(M,p)
  * Inputs:
      * M
      * N, or null,
      * p, from the ring of N to the ring of M
      * f, to the ring of M, from the cover of N tensored with the ring of M
        along p. Alternatively, f can be represented by its doubly nested list
        of entries.
  * Optional inputs,:
      * Degree, => a list, default value null, a
        list of integers of length equal to the degree length of the ring of M,
        providing the degree of g. By default, the degree of g is zero.
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * g, a matrix, the homomorphism to M from N defined by f

Description
===========

+------------------------------------------------+
|i1 : R = QQ[x,y]                                |
|                                                |
|o1 = R                                          |
|                                                |
|o1 : PolynomialRing                             |
+------------------------------------------------+
|i2 : p = map(R,QQ)                              |
|                                                |
|o2 = map (R, QQ, {})                            |
|                                                |
|o2 : RingMap R <-- QQ                           |
+------------------------------------------------+
|i3 : f = matrix {{x-y, x+2*y, 3*x-y}};          |
|                                                |
|             1      3                           |
|o3 : Matrix R  <-- R                            |
+------------------------------------------------+
|i4 : kernel f                                   |
|                                                |
|o4 = image {1} | -7 -x-2y |                     |
|           {1} | -2 x-y   |                     |
|           {1} | 3  0     |                     |
|                                                |
|                             3                  |
|o4 : R-module, submodule of R                   |
+------------------------------------------------+
|i5 : g = map(R^1,QQ^3,p,f)                      |
|                                                |
|o5 = | x-y x+2y 3x-y |                          |
|                                                |
|             1       3                          |
|o5 : Matrix R  <-- QQ                           |
+------------------------------------------------+
|i6 : g === map(R^1,QQ^3,p,{{x-y, x+2*y, 3*x-y}})|
|                                                |
|o6 = true                                       |
+------------------------------------------------+
|i7 : isHomogeneous g                            |
|                                                |
|o7 = false                                      |
+------------------------------------------------+
|i8 : kernel g                                   |
|                                                |
|o8 = image | -7 |                               |
|           | -2 |                               |
|           | 3  |                               |
|                                                |
|                               3                |
|o8 : QQ-module, submodule of QQ                 |
+------------------------------------------------+
|i9 : coimage g                                  |
|                                                |
|o9 = cokernel | -7 |                            |
|              | -2 |                            |
|              | 3  |                            |
|                                                |
|                              3                 |
|o9 : QQ-module, quotient of QQ                  |
+------------------------------------------------+
|i10 : rank oo                                   |
|                                                |
|o10 = 2                                         |
+------------------------------------------------+

If the module N is replaced by null, which is entered
automatically between consecutive commas, then a free module will be used for
N, whose degrees are obtained by lifting the degrees of the cover of the source
of g, minus the degree of g, along the degree map of p

+--------------------------------------+
|i11 : g2 = map(R^1,,p,f,Degree => {1})|
|                                      |
|o11 = | x-y x+2y 3x-y |               |
|                                      |
|              1       3               |
|o11 : Matrix R  <-- QQ                |
+--------------------------------------+
|i12 : g === g2                        |
|                                      |
|o12 = true                            |
+--------------------------------------+

If N and f are both omitted, along with their commas, then for f the matrix of
generators of M is used.

+----------------------------------+
|i13 : M' = image f                |
|                                  |
|o13 = image | x-y x+2y 3x-y |     |
|                                  |
|                              1   |
|o13 : R-module, submodule of R    |
+----------------------------------+
|i14 : g3 = map(M',p,Degree => {1})|
|                                  |
|o14 = {1} | 1 0 7/3 |             |
|      {1} | 0 1 2/3 |             |
|      {1} | 0 0 0   |             |
|                                  |
|                      3           |
|o14 : Matrix M' <-- QQ            |
+----------------------------------+
|i15 : isHomogeneous g3            |
|                                  |
|o15 = true                        |
+----------------------------------+
|i16 : kernel g3                   |
|                                  |
|o16 = image | -7 |                |
|            | -2 |                |
|            | 3  |                |
|                                  |
|                                3 |
|o16 : QQ-module, submodule of QQ  |
+----------------------------------+
|i17 : oo == kernel g              |
|                                  |
|o17 = true                        |
+----------------------------------+

The degree of the homomorphism enters into the determination of its
homogeneity.

+--------------------------------------------------+
|i18 : R = QQ[x, Degrees => {{2:1}}];              |
+--------------------------------------------------+
|i19 : M = R^1                                     |
|                                                  |
|       1                                          |
|o19 = R                                           |
|                                                  |
|o19 : R-module, free                              |
+--------------------------------------------------+
|i20 : S = QQ[z];                                  |
+--------------------------------------------------+
|i21 : N = S^1                                     |
|                                                  |
|       1                                          |
|o21 = S                                           |
|                                                  |
|o21 : S-module, free                              |
+--------------------------------------------------+
|i22 : p = map(R,S,{x},DegreeMap => x -> join(x,x))|
|                                                  |
|o22 = map (R, S, {x})                             |
|                                                  |
|o22 : RingMap R <-- S                             |
+--------------------------------------------------+
|i23 : isHomogeneous p                             |
|                                                  |
|o23 = true                                        |
+--------------------------------------------------+
|i24 : f = matrix {{x^3}}                          |
|                                                  |
|o24 = | x3 |                                      |
|                                                  |
|              1      1                            |
|o24 : Matrix R  <-- R                             |
+--------------------------------------------------+
|i25 : g = map(M,N,p,f,Degree => {3,3})            |
|                                                  |
|o25 = | x3 |                                      |
|                                                  |
|              1      1                            |
|o25 : Matrix R  <-- S                             |
+--------------------------------------------------+
|i26 : isHomogeneous g                             |
|                                                  |
|o26 = true                                        |
+--------------------------------------------------+
|i27 : kernel g                                    |
|                                                  |
|o27 = image 0                                     |
|                                                  |
|                              1                   |
|o27 : S-module, submodule of S                    |
+--------------------------------------------------+
|i28 : coimage g                                   |
|                                                  |
|       1                                          |
|o28 = S                                           |
|                                                  |
|o28 : S-module, free                              |
+--------------------------------------------------+

See also
========

  * map(Ring,Ring,List) -- make a ring map
  * isHomogeneous -- whether something is homogeneous
    (graded)
  * kernel(Matrix) -- kernel of a matrix
  * coimage(Matrix) -- coimage of a map

Ways to use this method:
========================

  * "map(Module,Module,RingMap,List)"
  * map(Module,Module,RingMap,Matrix)
    -- homomorphism of modules
    over different rings
  * "map(Module,Nothing,RingMap,List)"
  * "map(Module,Nothing,RingMap,Matrix)"
  * "map(Module,RingMap)"

map(Ring,Ring) -- make a ring map, using the names of the variables
*******************************************************************

Synopsis
========

  * Function: map,
  * Usage:
        map(R,S)
  * Inputs:
      * R
      * S
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * a ring map, a map S --> R which maps any variable of S
        to a variable with the same name in R, if any, and zero otherwise

Description
===========

For example, consider the following rings.
+----------------------------+
|i1 : A = QQ[a..e];          |
+----------------------------+
|i2 : B = A[x,y,Join=>false];|
+----------------------------+
|i3 : C = QQ[a..e,x,y];      |
+----------------------------+
The natural inclusion and projection maps between A and B are
+--------------------------------------+
|i4 : map(B,A)                         |
|                                      |
|o4 = map (B, A, {a, b, c, d, e})      |
|                                      |
|o4 : RingMap B <-- A                  |
+--------------------------------------+
|i5 : map(A,B)                         |
|                                      |
|o5 = map (A, B, {0, 0, a, b, c, d, e})|
|                                      |
|o5 : RingMap A <-- B                  |
+--------------------------------------+
The isomorphisms between B and C:
+---------------------------------------+
|i6 : F = map(B,C)                      |
|                                       |
|o6 = map (B, C, {a, b, c, d, e, x, y}) |
|                                       |
|o6 : RingMap B <-- C                   |
+---------------------------------------+
|i7 : G = map(C,B)                      |
|                                       |
|o7 = map (C, B, {x, y, a, b, c, d, e}) |
|                                       |
|o7 : RingMap C <-- B                   |
+---------------------------------------+
|i8 : F*G                               |
|                                       |
|o8 = map (B, B, {x, y, a, b, c, d, e}) |
|                                       |
|o8 : RingMap B <-- B                   |
+---------------------------------------+
|i9 : oo === id_B                       |
|                                       |
|o9 = true                              |
+---------------------------------------+
|i10 : G*F                              |
|                                       |
|o10 = map (C, C, {a, b, c, d, e, x, y})|
|                                       |
|o10 : RingMap C <-- C                  |
+---------------------------------------+
|i11 : oo === id_C                      |
|                                       |
|o11 = true                             |
+---------------------------------------+

The ring maps that are created are not always mathematically well-defined. For
example, the map F below is the natural quotient map, but the map G is not
mathematically well-defined, although we can use it in Macaulay2 to lift
elements of E to D.
+---------------------------+
|i12 : D = QQ[x,y,z];       |
+---------------------------+
|i13 : E = D/(x^2-z-1,y);   |
+---------------------------+
|i14 : F = map(E,D)         |
|                           |
|o14 = map (E, D, {x, 0, z})|
|                           |
|o14 : RingMap E <-- D      |
+---------------------------+
|i15 : G = map(D,E)         |
|                           |
|o15 = map (D, E, {x, y, z})|
|                           |
|o15 : RingMap D <-- E      |
+---------------------------+
|i16 : x^3                  |
|                           |
|o16 = x*z + x              |
|                           |
|o16 : E                    |
+---------------------------+
|i17 : G x^3                |
|                           |
|o17 = x*z + x              |
|                           |
|o17 : D                    |
+---------------------------+

Caveat
======

The map is not always a mathematically well-defined ring map

See also
========

  * substitution and maps between rings

Ways to use this method:
========================

  * map(Ring,Ring) -- make a ring map, using the
    names of the variables

map(Ring,Ring,List) -- make a ring map
**************************************

Synopsis
========

  * Function: map,
  * Usage:
        map(R,S,m)
  * Inputs:
      * R, the target ring
      * S, the source ring
      * m, of n elements of R, where n is the number of variables in the
        polynomial ring S, or a list of pairs x => r, where x is a generator of
        S and r is an element of R, specifying that x is to be sent to r.
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * the ring homomorphism from S to R which sends the i-th variable of S to
        the i-th entry in m, or in the second case, performs the indicated
        substitutions.

Description
===========

+----------------------------------------+
|i1 : R = ZZ[x,y];                       |
+----------------------------------------+
|i2 : S = ZZ[a,b,c];                     |
+----------------------------------------+
|i3 : f = map(R,S,{x^2,x*y,y^2})         |
|                                        |
|                  2        2            |
|o3 = map (R, S, {x , x*y, y })          |
|                                        |
|o3 : RingMap R <-- S                    |
+----------------------------------------+
|i4 : f(a+b+c^2)                         |
|                                        |
|      4    2                            |
|o4 = y  + x  + x*y                      |
|                                        |
|o4 : R                                  |
+----------------------------------------+
|i5 : g = map(R,S,{a=>x^2,b=>x*y,c=>y^2})|
|                                        |
|                  2        2            |
|o5 = map (R, S, {x , x*y, y })          |
|                                        |
|o5 : RingMap R <-- S                    |
+----------------------------------------+
|i6 : g(a+b+c^2)                         |
|                                        |
|      4    2                            |
|o6 = y  + x  + x*y                      |
|                                        |
|o6 : R                                  |
+----------------------------------------+

See also
========

  * substitution and maps between rings
  * map(Ring,Ring,Matrix) -- make a ring
    map

Ways to use this method:
========================

  * map(Ring,Ring,List) -- make a ring map

map(Ring,Ring,Matrix) -- make a ring map
****************************************

Synopsis
========

  * Function: map,
  * Usage:
        map(R,S,m)
  * Inputs:
      * R, the target ring
      * S, the source ring
      * m, a 1 by n matrix over R, where n is the number of variables in the
        polynomial ring S, or a matrix over the common coefficient ring of the
        two rings.  If a ring map is used here, (just) its matrix will be used
        instead.
  * Optional inputs,:
      * DegreeMap => a function, default value null, the
        degree map: a (linear) function from the multidegrees of S to the
        multidegrees of R, to be used in determining homogeneity and in
        determining degrees in tensor products. If the two rings have the same
        degree length, then the default degree map is the identity function.
      * DegreeLift => a function, default value null, the
        degree lift function: a (partial) inverse of the degree map, giving an
        error when lifting is not possible.  If the degree map is the identity,
        then by default the identity map will be provided.  If the degree
        length of R is 0, then by default a suitable degree lift function will
        be provided.
      * Degree, => ..., default value null, specify the degree of
        a map
  * Outputs:
      * the ring homomorphism from S to R which, in case m is a matrix over R,
        sends the i-th variable of S to the i-th entry in m, or, in case m is a
        matrix over the common coefficient ring, is the linear change of
        coordinates corresponding to m

Description
===========

+-------------------------------------------+
|i1 : R = ZZ[x,y];                          |
+-------------------------------------------+
|i2 : S = ZZ[a,b,c];                        |
+-------------------------------------------+
|i3 : f = map(R,S,matrix {{x^2,x*y,y^2}})   |
|                                           |
|                  2        2               |
|o3 = map (R, S, {x , x*y, y })             |
|                                           |
|o3 : RingMap R <-- S                       |
+-------------------------------------------+
|i4 : f(a+b+c^2)                            |
|                                           |
|      4    2                               |
|o4 = y  + x  + x*y                         |
|                                           |
|o4 : R                                     |
+-------------------------------------------+
|i5 : g = map(R,S,matrix {{1,2,3},{4,5,6}}) |
|                                           |
|o5 = map (R, S, {x + 4y, 2x + 5y, 3x + 6y})|
|                                           |
|o5 : RingMap R <-- S                       |
+-------------------------------------------+
|i6 : g(a+b)                                |
|                                           |
|o6 = 3x + 9y                               |
|                                           |
|o6 : R                                     |
+-------------------------------------------+
If the coefficient ring of S is itself a polynomial ring, then one may
optionally include values to which its variables should be sent: they should
appear last in the matrix m.
+------------------------------------+
|i7 : S = ZZ[a][b,c];                |
+------------------------------------+
|i8 : h = map(S,S,matrix {{b,c,2*a}})|
|                                    |
|o8 = map (S, S, {b, c, 2a})         |
|                                    |
|o8 : RingMap S <-- S                |
+------------------------------------+
|i9 : h(a^7 + b^3 + c)               |
|                                    |
|      3           7                 |
|o9 = b  + c + 128a                  |
|                                    |
|o9 : S                              |
+------------------------------------+
|i10 : k = map(S,S,matrix {{c,b}})   |
|                                    |
|o10 = map (S, S, {c, b, a})         |
|                                    |
|o10 : RingMap S <-- S               |
+------------------------------------+
|i11 : k(a^7 + b^3 + c)              |
|                                    |
|       3        7                   |
|o11 = c  + b + a                    |
|                                    |
|o11 : S                             |
+------------------------------------+
Specifying a degree map is a useful way to preserve homogeneity, which can
speed computation.
+------------------------------------------------------+
|i12 : R = QQ[x,y,z];                                  |
+------------------------------------------------------+
|i13 : S = QQ[t,u];                                    |
+------------------------------------------------------+
|i14 : f = map(S,R,{t^2,t*u,u^2},DegreeMap => i -> 2*i)|
|                                                      |
|                   2        2                         |
|o14 = map (S, R, {t , t*u, u })                       |
|                                                      |
|o14 : RingMap S <-- R                                 |
+------------------------------------------------------+
|i15 : isHomogeneous f                                 |
|                                                      |
|o15 = true                                            |
+------------------------------------------------------+
|i16 : M = R^{1,2}                                     |
|                                                      |
|       2                                              |
|o16 = R                                               |
|                                                      |
|o16 : R-module, free, degrees {-1, -2}                |
+------------------------------------------------------+
|i17 : f M                                             |
|                                                      |
|       2                                              |
|o17 = S                                               |
|                                                      |
|o17 : S-module, free, degrees {-2, -4}                |
+------------------------------------------------------+
|i18 : f ** M                                          |
|                                                      |
|       2                                              |
|o18 = S                                               |
|                                                      |
|o18 : S-module, free, degrees {-2, -4}                |
+------------------------------------------------------+

See also
========

  * substitution and maps between rings

Ways to use this method:
========================

  * map(Ring,Ring,Matrix) -- make a ring
    map
  * "map(Ring,Ring,RingMap)"

map(ChainComplex,ChainComplex,Function) -- make a map of chain complexes
************************************************************************

Synopsis
========

  * Function: map,
  * Usage:
        map(C,D,f) or map(C,D,f,Degree=>d)
  * Inputs:
      * C
      * D
      * f, a function such that f(i) is a matrix D_i --> C_(i+d)
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * a chain complex map, a map of chain complexes D
        --> C

Description
===========

If the degree d is not given, then d=0 is assumed.

The function f is called only for those indices that represent spots occupied
in both the source and target chain complexes.

Caveat
======

This function does not check that the maps f(i) commute with the differential
of the chain complexes.

See also
========

  * extend -- extend a module map to a chain map, if possible
  * ChainComplex -- the class of all chain complexes

Ways to use this method:
========================

  * map(ChainComplex,ChainComplex,Function)
    -- make a map of chain
    complexes
  * "map(GradedModule,GradedModule,Function)"

map(Module) -- identity map
***************************

Synopsis
========

  * Function: map,
  * Usage:
        map M
  * Inputs:
      * M
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * a matrix, the identity map on M

Description
===========

+-----------------------+
|i1 : f = map ZZ^3      |
|                       |
|o1 = | 1 0 0 |         |
|     | 0 1 0 |         |
|     | 0 0 1 |         |
|                       |
|              3       3|
|o1 : Matrix ZZ  <-- ZZ |
+-----------------------+
|i2 : g = id_(ZZ^3)     |
|                       |
|o2 = | 1 0 0 |         |
|     | 0 1 0 |         |
|     | 0 0 1 |         |
|                       |
|              3       3|
|o2 : Matrix ZZ  <-- ZZ |
+-----------------------+
|i3 : f === g           |
|                       |
|o3 = true              |
+-----------------------+

Caveat
======

may be removed

See also
========

  * id _ Module -- identity map

Ways to use this method:
========================

  * map(Module) -- identity map

map(Ring,Matrix) -- make a ring map
***********************************

Synopsis
========

  * Function: map,
  * Usage:
        map(R,m)
  * Inputs:
      * R
      * m, a one row matrix
  * Optional inputs,:
      * Degree, => ..., default value null, specify the degree of
        a map
      * DegreeLift, => ..., default value
        null, make a ring map
      * DegreeMap, => ..., default value
        null, make a ring map
  * Outputs:
      * a ring map, A ring map f : R --> (ring m), where the
        entries of m are the images of the variables of R.

Description
===========

This is equivalent to map(ring m, R, m).
+-------------------------------------------------------+
|i1 : R = QQ[a..d];                                     |
+-------------------------------------------------------+
|i2 : S = QQ[s,t];                                      |
+-------------------------------------------------------+
|i3 : F = map(R,matrix{{s^4,s^3*t,s*t^3,t^4}})          |
|                                                       |
|                  4   3      3   4                     |
|o3 = map (S, R, {s , s t, s*t , t })                   |
|                                                       |
|o3 : RingMap S <-- R                                   |
+-------------------------------------------------------+
|i4 : kernel F                                          |
|                                                       |
|                        3      2     2    2    3    2  |
|o4 = ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c)|
|                                                       |
|o4 : Ideal of R                                        |
+-------------------------------------------------------+

See also
========

  * substitution and maps between rings
  * map(Ring,Ring,Matrix) -- make a ring
    map

Ways to use this method:
========================

  * map(Ring,Matrix) -- make a ring map

MapExpression -- the class of map expressions
*********************************************

Description
===========

MapExpression is a type of Expression, representing a map.

+--------------------------------------+
|i1 : MapExpression {a,b,c}            |
|                                      |
|o1 = a <----- b                       |
|          c                           |
|                                      |
|o1 : Expression of class MapExpression|
+--------------------------------------+

For the programmer
==================

The object MapExpression, is a header type,
with ancestor classes Expression, <
BasicList < Thing.

maps between modules
********************

Maps between free modules are usually specified as matrices, as described in
the section on matrices.  In this section we cover a few other
techniques.

Let's set up a ring, a matrix, and a free module.
+-----------------------+
|i1 : R = ZZ/101[x,y,z];|
+-----------------------+
|i2 : f = vars R        |
|                       |
|o2 = | x y z |         |
|                       |
|             1      3  |
|o2 : Matrix R  <-- R   |
+-----------------------+
|i3 : M = R^4           |
|                       |
|      4                |
|o3 = R                 |
|                       |
|o3 : R-module, free    |
+-----------------------+
We can use Module ^ List, and Module _ List,
to produce projection maps to quotient modules and injection maps
from submodules corresponding to specified basis vectors.
+---------------------+
|i4 : M^{0,1}         |
|                     |
|o4 = | 1 0 0 0 |     |
|     | 0 1 0 0 |     |
|                     |
|             2      4|
|o4 : Matrix R  <-- R |
+---------------------+
|i5 : M_{2,3}         |
|                     |
|o5 = | 0 0 |         |
|     | 0 0 |         |
|     | 1 0 |         |
|     | 0 1 |         |
|                     |
|             4      2|
|o5 : Matrix R  <-- R |
+---------------------+

Natural maps between modules can be obtained with inducedMap,;
the first argument is the desired target, and the second is the
source.
+----------------------------------+
|i6 : inducedMap(source f, ker f)  |
|                                  |
|o6 = {1} | -y 0  -z |             |
|     {1} | x  -z 0  |             |
|     {1} | 0  y  x  |             |
|                                  |
|o6 : Matrix                       |
+----------------------------------+
|i7 : inducedMap(coker f, target f)|
|                                  |
|o7 = | 1 |                        |
|                                  |
|o7 : Matrix                       |
+----------------------------------+

markedGB(Matrix,Matrix) -- make a marked Gröbner basis
******************************************************

Synopsis
========

  * Function: markedGB,
  * Usage:
        markedGB(lt,m)
  * Inputs:
      * lt, the matrix of monomials in (the columns of) m to mark as lead
        terms, with respect to an unspecified monomial ordering
      * m, the matrix whose columns are to form the generators of a Gröbner
        basis
  * Optional inputs,:
      * SyzygyMatrix => a matrix, default value null, the matrix
        of syzygies
      * MinimalMatrix => a matrix, default value null, the
        matrix of minimal generators
      * ChangeMatrix => a matrix, default value null, the
        change-of-basis matrix
  * Outputs:
      * a Gröbner basis, the resulting Gröbner basis

Ways to use this method:
========================

  * markedGB(Matrix,Matrix) -- make a
    marked Gröbner basis

mathML -- convert to MathML format
**********************************

Synopsis
========

  * Usage:
        mathML x
  * Inputs:
      * x, any Macaulay2 object
  * Outputs:
      * a string, x converted to ML format

Description
===========

+-----------------------------------------------------------------------------+
|i1 : R = ZZ[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : mathML (x+2*y-1)^2                                                      |
|                                                                             |
|o2 = <mrow><msup><mi>x</mi><mn>2</mn></msup>                                 |
|     <mo>+</mo><mrow><mn>4</mn><mo></mo><mi>x</mi><mo>*</mo><mi>y</mi></     |
|     <mo>+</mo><mrow><mn>4</mn><mo></mo><msup><mi>y</mi><mn>2</mn></msup     |
|     <mo>-</mo><mrow><mn>2</mn><mo></mo><mi>x</mi></mrow>                    |
|     <mo>-</mo><mrow><mn>4</mn><mo></mo><mi>y</mi></mrow>                    |
|     <mo>+</mo><mn>1</mn>                                                    |
|     </mrow>                                                                 |
|-----------------------------------------------------------------------------|
|mrow>                                                                        |
|></mrow>                                                                     |
+-----------------------------------------------------------------------------+
+-----------------------------------------------+
|i3 : mathML matrix {{x,y},{x^2+2,0}}           |
|                                               |
|o3 = <mrow><mo>(</mo><mtable align="baseline1">|
|     <mtr><mtd><mi>x</mi></mtd>                |
|     </mtr>                                    |
|     <mtr><mtd><mi>y</mi></mtd>                |
|     </mtr>                                    |
|     </mtable>                                 |
|     <mo>)</mo></mrow>                         |
+-----------------------------------------------+

See also
========

  * tex -- convert to $\TeX$ format
  * texMath -- convert to TeX math format

For the programmer
==================

The object mathML, is a method function with a single argument.

Matrix -- the class of all matrices
***********************************

Description
===========

A matrix is a homomorphism between two modules, together with an integer (or
vector of integers) called its degree, which is used when determining whether
the map is homogeneous.  The matrix is stored in the usual way as a rectangular
array of ring elements. When the source or target modules are not free, the
matrix is interpreted as a linear transformation in terms of the generators of
the modules.

A matrix f is an immutable object, so if you want to cache information about
it, put it in the hash table f.cache.

Common ways to make a matrix:
  * map -- make a map
  * matrix -- make a matrix
Common ways to get information about matrices:
  * degree(Matrix) (missing documentation)
  * isHomogeneous(Matrix) -- whether something is
    homogeneous (graded)
  * matrix(Matrix) -- the matrix between generators
Common operations on matrices:
  * Matrix + Matrix -- a unary or binary operator, usually used for
    addition
  * Matrix - Matrix -- a unary or binary operator, usually used for
    negation or subtraction
  * RingElement * Matrix -- a binary operator, usually used for
    multiplication
  * Matrix * Matrix -- matrix multiplication
  * Matrix == Matrix (missing documentation)
  * Matrix ++ Matrix -- direct sum of maps
  * Matrix ** Matrix -- tensor product
  * Matrix % Matrix -- normal
    form of ring elements and matrices
  * Matrix // Matrix -- factor a map through another
  * Matrix | Matrix -- join matrices horizontally
  * Matrix || Matrix -- join matrices vertically
  * Matrix ^ List -- select rows
  * Matrix _ List -- select columns
Common ways to use a matrix:
  * cokernel(Matrix) -- cokernel of a map of modules, graded
    modules, or chaincomplexes
  * image(Matrix) -- image of a map
  * kernel(Matrix) -- kernel of a matrix
  * homology(Matrix,Matrix) -- homology
    of a pair of maps

See also
========

  * matrices

Functions and methods returning a matrix:
=========================================

  * "Matrix + Matrix" -- see +, -- a unary or binary operator, usually
    used for addition
  * "- Matrix" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "Matrix - Matrix" -- see -, -- a unary or binary operator, usually
    used for negation or subtraction
  * "adjoint'(Matrix,Module,Module)" -- see adjoint, -- the
    tensor-Hom adjunction maps
  * "adjoint(Matrix,Module,Module)" -- see adjoint, -- the
    tensor-Hom adjunction maps
  * ambient(Matrix) -- get the map between the
    ambient free modules
  * basis -- basis or generating set of all or part of a ring,
    ideal or module
  * "basis(List,RingMap)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(RingMap)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(Sequence,RingMap)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(ZZ,RingMap)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * borel(Matrix) -- make a Borel fixed submodule
  * ChainComplexMap _ ZZ -- component map
  * "GradedModuleMap _ ZZ" -- see ChainComplexMap _ ZZ,
    -- component map
  * complement(Matrix) -- find the minimal
    generators for cokernel of a matrix (low level form)
  * "compose(Module,Module,Module)" -- see compose, --
    composition as a pairing on Hom-modules
  * "compress(Matrix)" -- see compress, -- extract nonzero
    columns from a matrix
  * contract'(Matrix,Matrix) -- contract
    a matrix by a matrix, the dual notion
  * contract(Matrix,Matrix) -- contract a
    matrix by a matrix
  * cover(Matrix) -- get the map between the covering
    free modules
  * coverMap(Module) -- the surjective map from a
    free module to a module corresponding to the generators
  * diagonalMatrix -- make a diagonal matrix
  * diff'(Matrix,Matrix) -- differentiate a
    matrix by a matrix, the dual notion
  * diff(Matrix,Matrix) -- differentiate a
    matrix by a matrix
  * "divideByVariable(Matrix,RingElement)" -- see divideByVariable,
    -- divide all columns by a (power of a) variable
  * "divideByVariable(Matrix,RingElement,ZZ)" -- see divideByVariable,
    -- divide all columns by a (power of a) variable
  * dual(Matrix) -- dual of a map
  * effGenerators (missing documentation)
  * Ext^ZZ(CoherentSheaf,SheafMap) (missing documentation)
  * "Ext^ZZ(Matrix,Ideal)" -- see Ext^ZZ(Matrix,Module),
    -- map between Ext modules
  * Ext^ZZ(Matrix,Module) -- map between
    Ext modules
  * "Ext^ZZ(Matrix,Ring)" -- see Ext^ZZ(Matrix,Module),
    -- map between Ext modules
  * "Ext^ZZ(Ideal,Matrix)" -- see Ext^ZZ(Module,Matrix),
    -- map between Ext modules
  * Ext^ZZ(Module,Matrix) -- map between
    Ext modules
  * Ext^ZZ(Ring,Matrix) (missing documentation)
  * exteriorPower(ZZ,Matrix) -- exterior
    power of a matrix
  * "flatten(Matrix)" -- see flatten, -- flatten a nested list
    or a matrix
  * "flip(Module,Module)" -- see flip, -- isomorphism map of
    commutativity of tensor product
  * generators(GroebnerBasis) -- the
    generator matrix of a Gröbner basis
  * generators(Ideal) -- the generator matrix of
    an ideal
  * generators(Module) -- the generator matrix
    of a module
  * genericMatrix -- make a generic matrix of variables
  * genericSkewMatrix -- make a generic skew
    symmetric matrix of variables
  * genericSymmetricMatrix -- make a generic
    symmetric matrix
  * "getChangeMatrix(GroebnerBasis)" -- see getChangeMatrix,
    -- get the change of basis matrix
  * groebnerBasis -- Gröbner basis, as a matrix
  * HH^ZZ ChainComplexMap -- cohomology of a
    chain complex map
  * HH^ZZ SheafMap (missing documentation)
  * HH^ZZ(ProjectiveVariety,SheafMap) (missing documentation)
  * HH_ZZ ChainComplexMap -- homology of a
    chain complex map
  * hilbertBasis(Matrix) (missing documentation)
  * "Hom(Matrix,Matrix)" -- see Hom(Module,Matrix),
    -- induced map on Hom
  * "Hom(Matrix,Module)" -- see Hom(Module,Matrix),
    -- induced map on Hom
  * Hom(Module,Matrix) -- induced map on Hom
  * "homogenize(Matrix,RingElement)" -- see homogenize, --
    homogenize with respect to a variable
  * "homogenize(Matrix,RingElement,List)" -- see homogenize,
    -- homogenize with respect to a variable
  * "homogenize(RingElement,RingElement)" -- see homogenize,
    -- homogenize with respect to a variable
  * "homomorphism'(Matrix)" -- see homomorphism', -- get
    the element of Hom from a homomorphism
  * "icFractions(Ring)" -- see icFractions (IntegralClosure),
    -- fractions integral over an affine domain
  * inducedMap(Module,Module), --
    compute the map induced by the identity
  * inducedMap(Module,Module,Matrix)
    -- compute the induced map
  * interiorPoint (Polyhedra) -- computes a point in the
    relative interior of the Polyhedron
  * interiorVector (Polyhedra) -- computes a vector in
    the relative interior of a Cone
  * jacobian(Ideal) -- the Jacobian matrix of the
    generators of an ideal
  * jacobian(Matrix) -- the matrix of partial
    derivatives of polynomials in a matrix
  * jacobian(Ring) -- the Jacobian matrix of the
    polynomials defining a quotient ring
  * jacobian(RingElement) (missing documentation)
  * koszul(ZZ,Matrix) -- a differential in a
    Koszul complex
  * leadTerm(Ideal) -- get the ideal of greatest
    terms
  * "leadTerm(GroebnerBasis)" -- see leadTerm(Matrix),
    -- get the greatest term of each column
  * leadTerm(Matrix) -- get the greatest term of
    each column
  * leadTerm(ZZ,Ideal) -- get the ideal of
    lead polynomials
  * leadTerm(ZZ,Matrix) -- get the matrix of
    lead polynomials of each column
  * "lift(Matrix,type of Number)" -- see lift, -- lift to another
    ring
  * "lift(Matrix,type of RingElement)" -- see lift, -- lift to
    another ring
  * lift(MutableMatrix,type of InexactNumber') (missing documentation)
  * lift(MutableMatrix,type of Number) (missing documentation)
  * lift(MutableMatrix,type of RingElement) (missing documentation)
  * linealitySpace (Polyhedra) -- computes a basis of the
    lineality space
  * linSpace (Polyhedra) -- Deprecated version of @TO
    "linealitySpace"@
  * map(Matrix) -- make a matrix with a different
    degree
  * map(Module) -- identity map
  * map(Module,Module,Function), --
    create a matrix by specifying a function that gives each entry
  * map(Module,Module,List) -- create a
    matrix by giving a sparse or dense list of entries
  * map(Module,Module,Matrix), --
    create the matrix induced on generators by a given matrix
  * "map(Module,Module,Number)" -- see map(Module,Module,RingElement),
    -- construct the map induced by
    multiplication by a ring element on the generators
  * map(Module,Module,RingElement)
    -- construct the map induced by
    multiplication by a ring element on the generators
  * "map(Module,Module,ZZ)" -- see map(Module,Module,RingElement),
    -- construct the map induced by
    multiplication by a ring element on the generators
  * "map(Module,ZZ,ZZ)" -- see map(Module,Module,RingElement),
    -- construct the map induced by
    multiplication by a ring element on the generators
  * "map(Module,Module,RingMap,List)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * map(Module,Module,RingMap,Matrix)
    -- homomorphism of modules
    over different rings
  * "map(Module,Nothing,RingMap,List)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * "map(Module,Nothing,RingMap,Matrix)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * "map(Module,RingMap)" -- see map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * map(Module,Nothing,List) -- create
    a matrix by giving a doubly nested list of ring elements
  * map(Module,Nothing,Matrix), --
    recast a matrix to have a new target, and a free module as source
  * map(Module,ZZ,Function) -- create a
    matrix from a free module by specifying a function that gives each entry
  * map(Module,ZZ,List) -- create a matrix
    by giving a sparse or dense list of entries
  * Matrix % GroebnerBasis -- calculate the
    normal form of ring elements and matrices using a (partially computed)
    Gröbner basis
  * Matrix * Matrix -- matrix multiplication
  * Matrix ** Ring -- tensor product
  * "Ring ** Matrix" -- see Matrix ** Ring, -- tensor
    product
  * Matrix ++ Matrix -- direct sum of maps
  * "Matrix ++ RingElement" -- see Matrix ++ Matrix, --
    direct sum of maps
  * "RingElement ++ Matrix" -- see Matrix ++ Matrix, --
    direct sum of maps
  * "RingElement ++ RingElement" -- see Matrix ++ Matrix,
    -- direct sum of maps
  * "Matrix // GroebnerBasis" -- see Matrix // Matrix,
    -- factor a map through another
  * Matrix // Matrix -- factor a map through another
  * "Matrix // MonomialIdeal" -- see Matrix // Matrix,
    -- factor a map through another
  * "RingElement // GroebnerBasis" -- see Matrix // Matrix,
    -- factor a map through another
  * Matrix ^ Array -- component of map corresponding to
    summand of target
  * Matrix ^ List -- select rows
  * Matrix ^ ZZ -- power
  * Matrix _ Array -- component of map corresponding
    to summand of source
  * Matrix _ List -- select columns
  * Matrix | Matrix -- join matrices horizontally
  * "RingElement | RingElement" -- see Matrix | Matrix,
    -- join matrices horizontally
  * Matrix || Matrix -- join matrices vertically
  * "RingElement || RingElement" -- see Matrix || Matrix,
    -- join matrices vertically
  * matrix(List) -- create a matrix from a
    doubly-nested list of ring elements or matrices
  * matrix(Matrix) -- the matrix between generators
  * matrix(Ring,List) -- create a matrix from a
    doubly nested list of ring elements or matrices
  * "matrix(RingFamily,List)" -- see matrix(Ring,List),
    -- create a matrix from a doubly nested list of
    ring elements or matrices
  * matrix(SheafMap) (missing documentation)
  * matrix(String) (Classic) -- make a matrix using
    classic Macaulay syntax
  * "Matrix % Ideal" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "Matrix % Matrix" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "Matrix % Module" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "Matrix % MonomialIdeal" -- see methods for normal forms and remainder,
    -- normal form of ring
    elements and matrices
  * mingens(GroebnerBasis) -- (partially
    constructed) minimal generator matrix
  * "mingens(Ideal)" -- see mingens(Module), --
    minimal generator matrix
  * mingens(Module) -- minimal generator matrix
  * minimalPresentation(Matrix), --
    minimally present source and target of a matrix
  * "prune(Matrix)" -- see minimalPresentation(Matrix),
    -- minimally present source and target of
    a matrix
  * Module ^ Array -- projection onto summand
  * Module ^ List -- projection onto summand
  * Module _ Array -- inclusion from summand
  * Module _ List -- map from free module to some
    generators
  * modulo(Matrix,Matrix) -- find the
    pre-image (pullback) of image of a map (low level version)
  * "modulo(Matrix,Nothing)" -- see modulo(Matrix,Matrix),
    -- find the pre-image (pullback) of image of a
    map (low level version)
  * "modulo(Nothing,Matrix)" -- see modulo(Matrix,Matrix),
    -- find the pre-image (pullback) of image of a
    map (low level version)
  * MutableMatrix ^ List (missing documentation)
  * MutableMatrix _ List (missing documentation)
  * nefGenerators (missing documentation)
  * presentation(Module) -- presentation of a
    module
  * "presentation(QuotientRing)" -- see
    presentation(PolynomialRing,QuotientRing),
    -- presentation of a
    quotient ring
  * proximum (Polyhedra) -- computes the proximum of the
    Polyhedron/Cone to a point in euclidean metric
  * "quotient'(Matrix,Matrix)" -- see quotient', -- matrix
    quotient (opposite)
  * quotient(Matrix,GroebnerBasis),
    -- matrix quotient
  * "quotient(Matrix,Matrix)" -- see quotient(Matrix,GroebnerBasis),
    -- matrix quotient
  * "quotientRemainder(Matrix,GroebnerBasis)" -- see quotientRemainder,
    -- matrix quotient and remainder
  * "quotientRemainder(Matrix,Matrix)" -- see quotientRemainder,
    -- matrix quotient and remainder
  * "quotientRemainder'(Matrix,Matrix)" -- see quotientRemainder',
    -- matrix quotient and remainder (opposite)
  * random(Module,Module) -- get a random
    map of module
  * rays(Matrix) (missing documentation)
  * "relations(Module)" -- see relations, -- the defining
    relations
  * "remainder(Matrix,GroebnerBasis)" -- see remainder, --
    matrix remainder
  * "remainder(Matrix,Matrix)" -- see remainder, -- matrix
    remainder
  * "remainder'(Matrix,Matrix)" -- see remainder', -- matrix
    quotient and remainder (opposite)
  * "reshape(Module,Module,Matrix)" -- see reshape, -- reshape a
    matrix
  * "RingMap Matrix" -- see RingMap RingElement, --
    apply a ring map
  * schreyerOrder(Matrix) -- create a matrix
    with the same entries whose source free module has a Schreyer monomial
    order
  * schreyerOrder(Module) -- obtain Schreyer
    order information
  * "selectInSubring(ZZ,Matrix)" -- see selectInSubring,
    -- select columns in a subring
  * sublatticeBasis (Polyhedra) -- computes a basis for
    the sublattice generated by integral vectors or lattice points of a
    polytope
  * submatrix
  * submatrix' -- exclude rows and/or columns of a matrix
  * "substitute(Matrix,List)" -- see substitute, --
    substituting values for variables
  * "substitute(Matrix,Matrix)" -- see substitute, --
    substituting values for variables
  * "substitute(Matrix,Ring)" -- see substitute, --
    substituting values for variables
  * "substitute(Matrix,RingFamily)" -- see substitute, --
    substituting values for variables
  * "substitute(Matrix,ZZ)" -- see substitute, --
    substituting values for variables
  * sum(ChainComplexMap) -- direct sum of the
    components of a chain map
  * "super(Matrix)" -- see super, -- get the ambient module
  * "sylvesterMatrix" -- see
    sylvesterMatrix(RingElement,RingElement,RingElement) (Elimination),
  * "symmetricPower(ZZ,Matrix)" -- see symmetricPower, --
    symmetric power
  * syz -- the syzygy matrix
  * syz(GroebnerBasis) -- retrieve the syzygy
    matrix
  * syz(Matrix) -- compute the syzygy matrix
  * "Matrix ** Matrix" -- see tensor(Matrix,Matrix),
    -- tensor product
  * tensor(Matrix,Matrix) -- tensor product
  * "Matrix ** Module" -- see tensor(Matrix,Module),
    -- tensor product
  * "Module ** Matrix" -- see tensor(Matrix,Module),
    -- tensor product
  * tensor(Matrix,Module) -- tensor product
  * "tensor(Module,Matrix)" -- see tensor(Matrix,Module),
    -- tensor product
  * "RingMap ** Matrix" -- see tensor(RingMap,Matrix),
    -- tensor product via a ring map
  * tensor(RingMap,Matrix) -- tensor
    product via a ring map
  * "tensorAssociativity(Module,Module,Module)" -- see
    tensorAssociativity, -- associativity isomorphisms for
    tensor products
  * "toDual(ZZ,Ideal)" -- see toDual (InverseSystems), -- finds
    the inverse system to an ideal up to a given degree
  * "toDual(ZZ,Matrix)" -- see toDual (InverseSystems), -- finds
    the inverse system to an ideal up to a given degree
  * Tor_ZZ(Matrix,Module) (missing documentation)
  * Tor_ZZ(Module,Matrix) (missing documentation)
  * transpose(Matrix) -- transpose a matrix
  * truncate(List,Matrix) (Truncations), --
    truncation of a map of free modules
  * vars(Ring) -- row matrix of the variables
  * "versalEmbedding(Ideal)" -- see versalEmbedding (ReesAlgebra),
    -- Compute a versal embedding
  * "versalEmbedding(Module)" -- see versalEmbedding (ReesAlgebra),
    -- Compute a versal embedding
  * vertexEdgeMatrix (Polyhedra) -- computes the
    vertex-edge-relations matrix
  * vertexFacetMatrix (Polyhedra) -- computes the
    vertex-facet-relations matrix
  * wedgeProduct(ZZ,ZZ,Module), --
    the exterior multiplication map

Methods that use a matrix:
==========================

  * "Matrix * Number" -- see *, -- a binary operator, usually used
    for multiplication
  * "Matrix * RingElement" -- see *, -- a binary operator, usually
    used for multiplication
  * "Matrix * Vector" -- see *, -- a binary operator, usually used
    for multiplication
  * "Number * Matrix" -- see *, -- a binary operator, usually used
    for multiplication
  * "RingElement * Matrix" -- see *, -- a binary operator, usually
    used for multiplication
  * "Matrix + Number" -- see +, -- a unary or binary operator, usually
    used for addition
  * "Matrix + RingElement" -- see +, -- a unary or binary operator,
    usually used for addition
  * "Number + Matrix" -- see +, -- a unary or binary operator, usually
    used for addition
  * "RingElement + Matrix" -- see +, -- a unary or binary operator,
    usually used for addition
  * "Matrix - Number" -- see -, -- a unary or binary operator, usually
    used for negation or subtraction
  * "Matrix - RingElement" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "Number - Matrix" -- see -, -- a unary or binary operator, usually
    used for negation or subtraction
  * "RingElement - Matrix" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "Matrix // Number" -- see //, -- a binary operator, usually used
    for quotient
  * "Number // Matrix" -- see //, -- a binary operator, usually used
    for quotient
  * "affineImage(Cone,Matrix)" -- see affineImage(Matrix,Cone,Matrix) (Polyhedra),
    -- computes the affine
    image of a cone
  * "affineImage(Matrix,Cone)" -- see affineImage(Matrix,Cone,Matrix) (Polyhedra),
    -- computes the affine
    image of a cone
  * affineImage(Matrix,Cone,Matrix) (Polyhedra)
    -- computes the affine
    image of a cone
  * "affineImage(Matrix,Polyhedron)" -- see
    affineImage(Matrix,Polyhedron,Matrix) (Polyhedra),
    -- computes the
    affine image of a polyhedron
  * affineImage(Matrix,Polyhedron,Matrix) (Polyhedra)
    -- computes the
    affine image of a polyhedron
  * "affineImage(Polyhedron,Matrix)" -- see
    affineImage(Matrix,Polyhedron,Matrix) (Polyhedra),
    -- computes the
    affine image of a polyhedron
  * "affinePreimage(Cone,Matrix)" -- see
    affinePreimage(Matrix,Cone,Matrix) (Polyhedra),
    -- computes the
    affine preimage of a cone
  * "affinePreimage(Matrix,Cone)" -- see
    affinePreimage(Matrix,Cone,Matrix) (Polyhedra),
    -- computes the
    affine preimage of a cone
  * affinePreimage(Matrix,Cone,Matrix) (Polyhedra)
    -- computes the
    affine preimage of a cone
  * "affinePreimage(Matrix,Polyhedron)" -- see
    affinePreimage(Matrix,Polyhedron,Matrix) (Polyhedra),
    -- computes
    the affine preimage of a polyhedron
  * affinePreimage(Matrix,Polyhedron,Matrix) (Polyhedra)
    -- computes
    the affine preimage of a polyhedron
  * "affinePreimage(Polyhedron,Matrix)" -- see
    affinePreimage(Matrix,Polyhedron,Matrix) (Polyhedra),
    -- computes
    the affine preimage of a polyhedron
  * "basis(InfiniteNumber,InfiniteNumber,Matrix)" -- see basis, --
    basis or generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,List,Matrix)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,ZZ,Matrix)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,InfiniteNumber,Matrix)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,List,Matrix)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,Matrix)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(List,ZZ,Matrix)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(Matrix)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(ZZ,InfiniteNumber,Matrix)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(ZZ,List,Matrix)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(ZZ,Matrix)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(ZZ,ZZ,Matrix)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "betti(Matrix)" -- see betti, -- display or modify a Betti
    diagram
  * "ccRefinement(Matrix)" -- see ccRefinement (Polyhedra),
    -- computes the coarsest common refinement of a set of rays
  * "cellDecompose(Polyhedron,Matrix)" -- see cellDecompose (Polyhedra),
    -- Deprecated variant of {\tt regularSubdivision}
  * chainComplex(Matrix) -- make a small chain
    complex
  * "checkDegrees(Matrix,Matrix)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * "clean(RR,Matrix)" -- see clean, -- Set to zero elements that
    are approximately zero
  * "coefficients(Matrix)" -- see coefficients, --
    monomials and their coefficients
  * "coimage(Matrix)" -- see coimage, -- coimage of a map
  * "cokernel(Matrix)" -- see cokernel, -- cokernel of a map of
    modules, graded modules, or chaincomplexes
  * "components(Matrix)" -- see components, -- list the
    components of a direct sum
  * "coneFromHData(Matrix)" -- see coneFromHData (Polyhedra),
    -- Constructing a polyhedral cone as intersection
    of halfspaces.
  * "coneFromHData(Matrix,Matrix)" -- see coneFromHData (Polyhedra),
    -- Constructing a polyhedral cone as intersection
    of halfspaces.
  * "coneFromVData(Matrix)" -- see coneFromVData (Polyhedra),
    -- computes the positive hull of rays, cones, and
    the cone over a polyhedron
  * "coneFromVData(Matrix,Matrix)" -- see coneFromVData (Polyhedra),
    -- computes the positive hull of rays, cones, and
    the cone over a polyhedron
  * "contains(Cone,Matrix)" -- see contains (Polyhedra), --
    checks if the first argument contains the second argument
  * "contains(Polyhedron,Matrix)" -- see contains (Polyhedra),
    -- checks if the first argument contains the second argument
  * "contract(Matrix,Number)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Matrix,RingElement)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Matrix,Vector)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Number,Matrix)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(RingElement,Matrix)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Vector,Matrix)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "convexHull(Matrix)" -- see convexHull (Polyhedra), --
    computing the convex hull of points, rays and polyhedra
  * "convexHull(Matrix,Matrix)" -- see convexHull (Polyhedra),
    -- computing the convex hull of points, rays and polyhedra
  * "convexHull(Matrix,Matrix,Matrix)" -- see convexHull (Polyhedra),
    -- computing the convex hull of points, rays and
    polyhedra
  * degree(Matrix) (missing documentation)
  * degrees(Matrix) -- degrees of target and source
  * "describe(Matrix)" -- see describe, -- real description
  * "determinant(Matrix)" -- see determinant, -- determinant
    of a matrix
  * diagonalMatrix(Matrix) -- make a
    diagonal matrix from entries of a matrix
  * "diff(Matrix,Vector)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * "diff(Vector,Matrix)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * diff(Matrix,RingElement), --
    differentiation
  * diff(RingElement,Matrix), --
    differentiate each entry of a matrix
  * "directSum(Matrix)" -- see directSum, -- direct sum of
    modules or maps
  * eagonNorthcott(Matrix), --
    Eagon-Northcott complex of a matrix of linear forms
  * "eigenvalues(Matrix)" -- see eigenvalues, -- find
    eigenvalues of a matrix
  * "eigenvectors(Matrix)" -- see eigenvectors, -- find
    eigenvectors of a matrix over RR or CC
  * "entries(Matrix)" -- see entries, -- lists the entries of a
    matrix
  * extend(ChainComplex,ChainComplex,Matrix)
    -- extend a module map to
    a chain map, if possible
  * "fan(Matrix,List)" -- see fan(Matrix,Matrix,List) (Polyhedra),
    -- Constructing a fan.
  * fan(Matrix,Matrix,List) (Polyhedra),
    -- Constructing a fan.
  * "fan(Matrix,Matrix,Sequence)" -- see fan(Matrix,Matrix,List) (Polyhedra),
    -- Constructing a fan.
  * "fan(Matrix,Sequence)" -- see fan(Matrix,Matrix,List) (Polyhedra),
    -- Constructing a fan.
  * fittingIdeal(ZZ,Matrix) (missing documentation)
  * "forceGB(Matrix)" -- see forceGB, -- declare that the
    columns of a matrix are a Gröbner basis
  * "fromDividedPowers(Matrix)" -- see fromDividedPowers (InverseSystems),
    -- Translates from divided power
    monomial basis to ordinary monomial basis
  * "fromDual(Matrix)" -- see fromDual (InverseSystems), --
    Ideal from inverse system
  * "gb(Matrix)" -- see gb, -- compute a Gröbner basis
  * "gbRemove(Matrix)" -- see gbRemove, -- remove Gröbner basis
  * "gbSnapshot(Matrix)" -- see gbSnapshot, -- the Gröbner
    basis matrix as so far computed
  * "Matrix _ ZZ" -- see generators of ideals and modules,
  * "gradedModuleMap(Matrix)" -- see gradedModuleMap, --
    make a map of graded modules
  * gramm(Matrix) (missing documentation)
  * "groebnerBasis(Matrix)" -- see groebnerBasis, --
    Gröbner basis, as a matrix
  * hermite(Matrix) (missing documentation)
  * homology(Matrix,Matrix) -- homology
    of a pair of maps
  * "homomorphism(Matrix)" -- see homomorphism, -- get the
    homomorphism from element of Hom
  * ideal(Matrix) -- make an ideal
  * "image(Matrix)" -- see image, -- image of a map
  * "imageFan(Matrix,Cone)" -- see imageFan (Polyhedra), --
    computes the fan of the image
  * "indices(Matrix)" -- see indices(RingElement),
    -- indices of variables occurring in a polynomial
  * "inducedMap(Module,Nothing,Matrix)" -- see
    inducedMap(Module,Module,Matrix),
    -- compute the induced map
  * "inducedMap(Nothing,Module,Matrix)" -- see
    inducedMap(Module,Module,Matrix),
    -- compute the induced map
  * "inducedMap(Nothing,Nothing,Matrix)" -- see
    inducedMap(Module,Module,Matrix),
    -- compute the induced map
  * "inducesWellDefinedMap(Module,Module,Matrix)" -- see
    inducesWellDefinedMap, -- whether a map is well
    defined
  * "inducesWellDefinedMap(Module,Nothing,Matrix)" -- see
    inducesWellDefinedMap, -- whether a map is well
    defined
  * "inducesWellDefinedMap(Nothing,Module,Matrix)" -- see
    inducesWellDefinedMap, -- whether a map is well
    defined
  * "inducesWellDefinedMap(Nothing,Nothing,Matrix)" -- see
    inducesWellDefinedMap, -- whether a map is well
    defined
  * InfiniteNumber * Matrix (missing documentation)
  * "inInterior(Matrix,Cone)" -- see inInterior (Polyhedra),
    -- checks if a point lies in the relative interior of a Cone/Polyhedron
  * "inInterior(Matrix,Polyhedron)" -- see inInterior (Polyhedra),
    -- checks if a point lies in the relative interior
    of a Cone/Polyhedron
  * installHilbertFunction(Matrix,RingElement) (missing documentation)
  * intersection(Matrix) (Polyhedra), --
    Deprecated variant of {\tt coneFromHData}
  * intersection(Matrix,Matrix) (Polyhedra)
    -- Deprecated variants of
    {\tt polyhedronFromHData} and {\tt coneFromHData}
  * "intersection(Matrix,Matrix,Matrix,Matrix)" -- see
    intersection(Matrix,Matrix) (Polyhedra),
    -- Deprecated variants of {\tt polyhedronFromHData} and {\tt coneFromHData}
  * inverse(Matrix) -- compute the inverse
  * "inverseSystem(Matrix)" -- see inverseSystem (InverseSystems),
    -- Inverse systems with equivariance
  * "inverseSystem(ZZ,Matrix)" -- see inverseSystem (InverseSystems),
    -- Inverse systems with equivariance
  * "isHomogeneous(Matrix)" -- see isHomogeneous, --
    whether something is homogeneous (graded)
  * "isInjective(Matrix)" -- see isInjective, -- whether a
    map is injective
  * "isIsomorphic(Matrix,Matrix)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * "isIsomorphism(Matrix)" -- see isIsomorphism, --
    whether a map is an isomorphism
  * isLiftable(Matrix,Matrix) (missing documentation)
  * "isLLL(Matrix)" -- see isLLL (LLLBases), -- is a basis an LLL
    basis?
  * "isSurjective(Matrix)" -- see isSurjective, -- whether
    a map is surjective
  * "isWellDefined(Matrix)" -- see isWellDefined, --
    whether a map is well defined
  * "jacobianDual(Matrix)" -- see jacobianDual (ReesAlgebra),
    -- Computes the 'jacobian dual', part of a
    method of finding generators for Rees Algebra ideals
  * "jacobianDual(Matrix,Matrix,Matrix)" -- see jacobianDual (ReesAlgebra),
    -- Computes the 'jacobian dual', part of a
    method of finding generators for Rees Algebra ideals
  * kernel(Matrix) -- kernel of a matrix
  * kernelLLL(Matrix) (missing documentation)
  * koszul(Matrix) -- the Koszul complex
  * "leadComponent(Matrix)" -- see leadComponent, -- the
    leading component(s) of a vector or matrix
  * "lift(Matrix,type of CC_*,type of QQ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of CC_*,type of RR_*)" -- see lift, -- lift
    to another ring
  * "lift(Matrix,type of CC_*,type of ZZ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of QQ,type of QQ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of QQ,type of ZZ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of RR_*,type of QQ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of RR_*,type of ZZ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of RRi_*,type of QQ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of RRi_*,type of RR_*)" -- see lift, -- lift
    to another ring
  * "lift(Matrix,type of RRi_*,type of ZZ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of ZZ,type of ZZ)" -- see lift, -- lift to
    another ring
  * lift(Matrix,type of CC_*,type of CC_*) (missing documentation)
  * lift(Matrix,type of RR_*,type of RR_*) (missing documentation)
  * linearTransform(Fan,Matrix) (missing documentation)
  * "LLL(Matrix)" -- see LLL (LLLBases), -- compute an LLL basis
  * "LUdecomposition(Matrix)" -- see LUdecomposition, --
    LU decomposition
  * map(CoherentSheaf,CoherentSheaf,Matrix) (missing documentation)
  * map(CoherentSheaf,CoherentSheaf,Matrix,InfiniteNumber) (missing
    documentation)
  * map(CoherentSheaf,CoherentSheaf,Matrix,ZZ) (missing documentation)
  * map(Ring,Matrix) -- make a ring map
  * map(Ring,Ring,Matrix) -- make a ring
    map
  * markedGB(Matrix,Matrix) -- make a
    marked Gröbner basis
  * Matrix * InfiniteNumber (missing documentation)
  * Matrix ** RingElement -- a binary
    operator, usually used for tensor product or Cartesian product
  * Matrix / Number -- scalar division
  * "Matrix / RingElement" -- see Matrix / Number, --
    scalar division
  * "Matrix // RingElement" -- see Matrix // Matrix, --
    factor a map through another
  * "RingElement // Matrix" -- see Matrix // Matrix, --
    factor a map through another
  * Matrix == Matrix (missing documentation)
  * Matrix == Number (missing documentation)
  * Matrix == RingElement (missing documentation)
  * Matrix == ZZ (missing documentation)
  * Matrix \\ Matrix (missing documentation)
  * Matrix \\ Number (missing documentation)
  * Matrix \\ RingElement (missing documentation)
  * Matrix _ Sequence -- get entry of matrix
  * "Matrix | Number" -- see Matrix | Matrix, -- join
    matrices horizontally
  * "Matrix | RingElement" -- see Matrix | Matrix, --
    join matrices horizontally
  * "Number | Matrix" -- see Matrix | Matrix, -- join
    matrices horizontally
  * "RingElement | Matrix" -- see Matrix | Matrix, --
    join matrices horizontally
  * "Matrix || Number" -- see Matrix || Matrix, -- join
    matrices vertically
  * "Matrix || RingElement" -- see Matrix || Matrix, --
    join matrices vertically
  * "Number || Matrix" -- see Matrix || Matrix, -- join
    matrices vertically
  * "RingElement || Matrix" -- see Matrix || Matrix, --
    join matrices vertically
  * Matrix Vector (missing documentation)
  * "maxFace(Matrix,Cone)" -- see maxFace (Polyhedra), --
    computes the face of a Polyhedron or Cone where a weight attains its
    maximum
  * "maxFace(Matrix,Polyhedron)" -- see maxFace (Polyhedra), --
    computes the face of a Polyhedron or Cone where a weight attains its
    maximum
  * "Matrix % RingElement" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "RingElement % Matrix" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "minFace(Matrix,Cone)" -- see minFace (Polyhedra), --
    computes the face of a Polyhedron or Cone where a weight attains its
    minimum
  * "minFace(Matrix,Polyhedron)" -- see minFace (Polyhedra), --
    computes the face of a Polyhedron or Cone where a weight attains its
    minimum
  * minors(ZZ,Matrix) -- ideal generated by
    minors
  * monomialIdeal(Matrix) -- monomial ideal
    of lead monomials
  * "monomials(Matrix)" -- see monomials, -- matrix of
    monomials in a ring element or matrix
  * "mutableMatrix(Matrix)" -- see mutableMatrix, -- make
    a mutable matrix
  * "newCoordinateSystem(PolynomialRing,Matrix)" -- see
    newCoordinateSystem, -- change variables
  * "norm(InfiniteNumber,Matrix)" -- see norm,
  * "norm(Matrix)" -- see norm,
  * "norm(RR,Matrix)" -- see norm,
  * Number == Matrix (missing documentation)
  * Number \\ Matrix (missing documentation)
  * numColumns(Matrix) -- number of columns in a
    matrix or mutable matrix
  * "numeric(Matrix)" -- see numeric, -- convert to floating
    point
  * "numeric(ZZ,Matrix)" -- see numeric, -- convert to floating
    point
  * numRows(Matrix) -- number of rows in a matrix
    or mutable matrix
  * "permanents(ZZ,Matrix)" -- see permanents, -- ideal
    generated by square permanents of a matrix
  * "pfaffians(ZZ,Matrix)" -- see pfaffians, -- ideal
    generated by Pfaffians
  * pivots(Matrix) -- list of pivot locations of a
    matrix
  * "polyhedralComplex(Matrix,List)" -- see
    polyhedralComplex(Matrix,Matrix,Matrix,List) (Polyhedra),
    --
    Constructing a polyhedral complex.
  * "polyhedralComplex(Matrix,Matrix,List)" -- see
    polyhedralComplex(Matrix,Matrix,Matrix,List) (Polyhedra),
    --
    Constructing a polyhedral complex.
  * polyhedralComplex(Matrix,Matrix,Matrix,List) (Polyhedra),
    --
    Constructing a polyhedral complex.
  * "polyhedronFromHData(Matrix,Matrix)" -- see polyhedronFromHData (Polyhedra),
    -- Constructing a polyhedron from its
    H-representation, i.e. inequalities and equations
  * "polyhedronFromHData(Matrix,Matrix,Matrix,Matrix)" -- see
    polyhedronFromHData (Polyhedra), -- Constructing a
    polyhedron from its H-representation, i.e. inequalities and equations
  * "precision(Matrix)" -- see precision,
  * "preimage(Matrix,Module)" -- see preimage, -- preimage of a
    map
  * "proximum(Matrix,Cone)" -- see proximum (Polyhedra), --
    computes the proximum of the Polyhedron/Cone to a point in euclidean metric
  * "proximum(Matrix,Polyhedron)" -- see proximum (Polyhedra),
    -- computes the proximum of the Polyhedron/Cone to a point in euclidean
    metric
  * pullback(Matrix,Matrix) (missing documentation)
  * pushout(Matrix,Matrix) (missing documentation)
  * "QRDecomposition(Matrix)" -- see QRDecomposition, --
    compute a QR decomposition of a real matrix
  * "rank(Matrix)" -- see rank, -- compute the rank
  * "reducedRowEchelonForm(Matrix)" -- see reducedRowEchelonForm,
    -- compute the reduced row echelon form of a matrix
    or mutable matrix over a field
  * "regularSubdivision(Matrix,Matrix)" -- see regularSubdivision (Polyhedra),
    -- Computes the regular cell decomposition
  * "regularSubdivision(Polyhedron,Matrix)" -- see regularSubdivision (Polyhedra),
    -- Computes the regular cell decomposition
  * resolution(Matrix) -- given a module map
    represented by a matrix, produce a comparison map between resolutions of
    its source and target
  * "ring(Matrix)" -- see ring, -- get the associated ring of an
    object
  * RingElement == Matrix (missing documentation)
  * RingElement \\ Matrix (missing documentation)
  * "ringFromFractions(Matrix,RingElement)" -- see ringFromFractions (IntegralClosure),
    -- find presentation for f.g. ring
  * "rsort(Matrix)" -- see rsort, -- sort a list or matrix in
    reverse order
  * sheafMap(Matrix) (missing documentation)
  * sheafMap(Matrix,ZZ) (missing documentation)
  * "simpleDocFrob(ZZ,Matrix)" -- see simpleDocFrob (SimpleDoc),
    -- a sample documentation node
  * "smallestFace(Matrix,Cone)" -- see smallestFace (Polyhedra),
    -- determines the smallest face of the
    Cone/Polyhedron containing a point
  * "smallestFace(Matrix,Polyhedron)" -- see smallestFace (Polyhedra),
    -- determines the smallest face of the
    Cone/Polyhedron containing a point
  * smithNormalForm(Matrix) -- smith normal
    form for a matrix over ZZ or a PID
  * "solve(Matrix,Matrix)" -- see solve, -- solve linear
    equation(s)
  * solve(Matrix,Vector) (missing documentation)
  * sort(Matrix) -- sort the columns of a matrix
  * "sortColumns(Matrix)" -- see sortColumns, -- permutation
    giving sort order
  * source(Matrix) -- find the source module of
    matrix
  * "stellarSubdivision(Fan,Matrix)" -- see stellarSubdivision (Polyhedra),
    -- computes the stellar subdivision of the
    fan by a ray
  * "sublatticeBasis(Matrix)" -- see sublatticeBasis (Polyhedra),
    -- computes a basis for the sublattice
    generated by integral vectors or lattice points of a polytope
  * "submatrix'(Matrix,Nothing,Nothing)" -- see submatrix',
    -- exclude rows and/or columns of a matrix
  * "submatrix'(Matrix,Nothing,VisibleList)" -- see submatrix',
    -- exclude rows and/or columns of a matrix
  * "submatrix'(Matrix,VisibleList)" -- see submatrix', --
    exclude rows and/or columns of a matrix
  * "submatrix'(Matrix,VisibleList,Nothing)" -- see submatrix',
    -- exclude rows and/or columns of a matrix
  * "submatrix'(Matrix,VisibleList,VisibleList)" -- see submatrix',
    -- exclude rows and/or columns of a matrix
  * submatrix(Matrix,VisibleList),
    -- select columns
  * submatrix(Matrix,VisibleList,VisibleList)
    -- select part of a
    matrix
  * "submatrixByDegrees(Matrix,List,List)" -- see submatrixByDegrees,
    -- submatrix consisting of rows and columns in an
    interval or box of degrees
  * "submatrixByDegrees(Matrix,Sequence,Sequence)" -- see
    submatrixByDegrees, -- submatrix consisting of rows and
    columns in an interval or box of degrees
  * "submatrixByDegrees(Matrix,ZZ,ZZ)" -- see submatrixByDegrees,
    -- submatrix consisting of rows and columns in an
    interval or box of degrees
  * "subquotient(Matrix,Matrix)" -- see subquotient, -- make
    a subquotient module
  * "subquotient(Matrix,Nothing)" -- see subquotient, --
    make a subquotient module
  * "subquotient(Module,Matrix,Matrix)" -- see subquotient,
    -- make a subquotient module
  * "subquotient(Module,Matrix,Nothing)" -- see subquotient,
    -- make a subquotient module
  * "subquotient(Module,Nothing,Matrix)" -- see subquotient,
    -- make a subquotient module
  * "subquotient(Nothing,Matrix)" -- see subquotient, --
    make a subquotient module
  * "substitute(Ideal,Matrix)" -- see substitute, --
    substituting values for variables
  * "substitute(Matrix,Option)" -- see substitute, --
    substituting values for variables
  * "substitute(Module,Matrix)" -- see substitute, --
    substituting values for variables
  * "substitute(RingElement,Matrix)" -- see substitute, --
    substituting values for variables
  * "substitute(Vector,Matrix)" -- see substitute, --
    substituting values for variables
  * "support(Matrix)" -- see support, -- list of variables
    occurring in a polynomial or matrix
  * "SVD(Matrix)" -- see SVD, -- singular value decomposition of a
    matrix
  * "symmetricAlgebra(Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricAlgebra(Nothing,Nothing,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricAlgebra(Nothing,Ring,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricAlgebra(Ring,Nothing,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricAlgebra(Ring,Ring,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricKernel(Matrix)" -- see symmetricKernel (ReesAlgebra),
    -- Compute the Rees ring of the image of a
    matrix
  * target(Matrix) -- find the target module of
    matrix
  * "toDividedPowers(Matrix)" -- see toDividedPowers (InverseSystems),
    -- Translates to divided power monomial
    basis from ordinary monomial basis
  * "topCoefficients(Matrix)" -- see topCoefficients, --
    first variable and its coefficient of a polynomial or matrix
  * Tor_ZZ(Ideal,Matrix) (missing documentation)
  * Tor_ZZ(Matrix,Ideal) (missing documentation)
  * Tor_ZZ(Matrix,Ring) (missing documentation)
  * Tor_ZZ(Ring,Matrix) (missing documentation)
  * trace(Matrix) -- trace of a matrix
  * "truncate(ZZ,Matrix)" -- see truncate(List,Matrix) (Truncations),
    -- truncation of a map of free
    modules
  * "vector(Matrix)" -- see vector, -- make a vector
  * "vector(Module,Matrix)" -- see vector, -- make a vector

For the programmer
==================

The object Matrix, is a type, with ancestor classes
HashTable < Thing.

matrix -- make a matrix
***********************

Description
===========

The simplest use of this function is to define a matrix by giving a doubly
nested list of ring elements.  One may also explicitly provide the ring, or
give a matrix as a doubly-nested list of matrices.
+----------------------------+
|i1 : matrix{{1,2,3},{4,5,6}}|
|                            |
|o1 = | 1 2 3 |              |
|     | 4 5 6 |              |
|                            |
|              2       3     |
|o1 : Matrix ZZ  <-- ZZ      |
+----------------------------+
|i2 : R = QQ[x,y,z];         |
+----------------------------+
|i3 : matrix{{x,0,2},{1,2,y}}|
|                            |
|o3 = | x 0 2 |              |
|     | 1 2 y |              |
|                            |
|             2      3       |
|o3 : Matrix R  <-- R        |
+----------------------------+
The map, function provides other methods to define a matrix.

Ways to use matrix:
===================

  * matrix(List) -- create a matrix from a
    doubly-nested list of ring elements or matrices
  * matrix(Matrix) -- the matrix between generators
  * matrix(MutableMatrix) -- make a matrix
    from a mutable one
  * matrix(Ring,List) -- create a matrix from a
    doubly nested list of ring elements or matrices
  * "matrix(RingFamily,List)" -- see matrix(Ring,List),
    -- create a matrix from a doubly nested list of
    ring elements or matrices
  * "matrix(Number)" -- see matrix(RingElement),
    -- make a matrix from a ring element
  * matrix(RingElement) -- make a matrix from a
    ring element
  * matrix(RingMap) -- the matrix associated to a
    ring map
  * matrix(SheafMap) (missing documentation)
  * matrix(String) (Classic) -- make a matrix using
    classic Macaulay syntax
  * matrix(Vector) -- make a matrix

For the programmer
==================

The object matrix, is a method function with options.

Matrix % GroebnerBasis -- calculate the normal form of ring elements and matrices using a (partially computed) Gröbner basis
****************************************************************************************************************************

Synopsis
========

  * Operator: %,
  * Usage:
        f % G
  * Inputs:
      * f, a ring element, or a matrix,
      * G
  * Outputs:
      * the normal form of f with respect to the partially computed Gröbner
        basis G

Description
===========

In the following example, the seventh power of the trace of the matrix M is in
the ideal generated by the entries of the cube of M.  Since the ideal I is
homogeneous, it is only required to compute the Gröbner basis in degrees at
most seven.
+---------------------------------------------------------------------------+
|i1 : R = QQ[a..i];                                                         |
+---------------------------------------------------------------------------+
|i2 : M = genericMatrix(R,a,3,3)                                            |
|                                                                           |
|o2 = | a d g |                                                             |
|     | b e h |                                                             |
|     | c f i |                                                             |
|                                                                           |
|             3      3                                                      |
|o2 : Matrix R  <-- R                                                       |
+---------------------------------------------------------------------------+
|i3 : I = ideal(M^3);                                                       |
|                                                                           |
|o3 : Ideal of R                                                            |
+---------------------------------------------------------------------------+
|i4 : f = trace M                                                           |
|                                                                           |
|o4 = a + e + i                                                             |
|                                                                           |
|o4 : R                                                                     |
+---------------------------------------------------------------------------+
|i5 : G = gb(I, DegreeLimit=>3)                                             |
|                                                                           |
|o5 = GroebnerBasis[status: DegreeLimit; all S-pairs handled up to degree 3]|
|                                                                           |
|o5 : GroebnerBasis                                                         |
+---------------------------------------------------------------------------+
|i6 : f^7 % G == 0                                                          |
|                                                                           |
|o6 = false                                                                 |
+---------------------------------------------------------------------------+
|i7 : gb(I, DegreeLimit=>7)                                                 |
|                                                                           |
|o7 = GroebnerBasis[status: DegreeLimit; all S-pairs handled up to degree 7]|
|                                                                           |
|o7 : GroebnerBasis                                                         |
+---------------------------------------------------------------------------+
|i8 : f^7 % G                                                               |
|                                                                           |
|o8 = 0                                                                     |
|                                                                           |
|o8 : R                                                                     |
+---------------------------------------------------------------------------+
|i9 : gb I                                                                  |
|                                                                           |
|o9 = GroebnerBasis[status: done; S-pairs encountered up to degree 9]       |
|                                                                           |
|o9 : GroebnerBasis                                                         |
+---------------------------------------------------------------------------+
In these homogeneous situations, Macaulay2 only computes the Gröbner basis as
far as required, as shown below.
+-----------------------------------------------------------------------------+
|i10 : I = ideal(M^3);                                                        |
|                                                                             |
|o10 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i11 : G = gb(I, StopBeforeComputation=>true)                                 |
|                                                                             |
|o11 = GroebnerBasis[status: not started; all S-pairs handled up to degree -1]|
|                                                                             |
|o11 : GroebnerBasis                                                          |
+-----------------------------------------------------------------------------+
|i12 : f^7 % I                                                                |
|                                                                             |
|o12 = 0                                                                      |
|                                                                             |
|o12 : R                                                                      |
+-----------------------------------------------------------------------------+
|i13 : status G                                                               |
|                                                                             |
|o13 = status: DegreeLimit; all S-pairs handled up to degree 7                |
+-----------------------------------------------------------------------------+

See also
========

  * methods for normal forms and remainder
    -- normal form of ring elements and matrices
  * Gröbner bases
  * genericMatrix -- make a generic matrix of variables

Ways to use this method:
========================

  * Matrix % GroebnerBasis -- calculate the
    normal form of ring elements and matrices using a (partially computed)
    Gröbner basis
  * "RingElement % GroebnerBasis"

Matrix * Matrix -- matrix multiplication
****************************************

Synopsis
========

  * Operator: *,
  * Usage:
        f * g
  * Inputs:
      * f
      * g
  * Outputs:
      * a matrix,

Description
===========

Multiplication of matrices corresponds to composition of maps, and when the
target Q of g equals the source P of f, the product f*g is defined, its source
is the source of g, and its target is the target of f.
+----------------------------+
|i1 : R = QQ[a,b,c,x,y,z];   |
+----------------------------+
|i2 : f = matrix{{x},{y},{z}}|
|                            |
|o2 = | x |                  |
|     | y |                  |
|     | z |                  |
|                            |
|             3      1       |
|o2 : Matrix R  <-- R        |
+----------------------------+
|i3 : g = matrix{{a,b,c}}    |
|                            |
|o3 = | a b c |              |
|                            |
|             1      3       |
|o3 : Matrix R  <-- R        |
+----------------------------+
|i4 : f*g                    |
|                            |
|o4 = | ax bx cx |           |
|     | ay by cy |           |
|     | az bz cz |           |
|                            |
|             3      3       |
|o4 : Matrix R  <-- R        |
+----------------------------+

The degree of f*g is the sum of the degrees of f and of g.

The product is also defined when P != Q, provided only that P and Q are free
modules of the same rank.  If the degrees of P differ from the corresponding
degrees of Q by the same degree d, then the degree of f*g is adjusted by d so
it will have a good chance to be homogeneous, and the target and source of f*g
are as before.
+-----------------------------+
|i5 : target (f*g) == target f|
|                             |
|o5 = true                    |
+-----------------------------+
|i6 : source (f*g) == source g|
|                             |
|o6 = true                    |
+-----------------------------+
|i7 : isHomogeneous (f*g)     |
|                             |
|o7 = true                    |
+-----------------------------+
|i8 : degree(f*g)             |
|                             |
|o8 = {1}                     |
|                             |
|o8 : List                    |
+-----------------------------+
Sometimes, it is useful to make this a map of degree zero.  Use
map(Matrix), for this purpose.
+---------------------------+
|i9 : h = map(f*g,Degree=>0)|
|                           |
|o9 = | ax bx cx |          |
|     | ay by cy |          |
|     | az bz cz |          |
|                           |
|             3      3      |
|o9 : Matrix R  <-- R       |
+---------------------------+
|i10 : degree h             |
|                           |
|o10 = {0}                  |
|                           |
|o10 : List                 |
+---------------------------+
|i11 : degrees source h     |
|                           |
|o11 = {{2}, {2}, {2}}      |
|                           |
|o11 : List                 |
+---------------------------+

See also
========

  * degree(Matrix) (missing documentation)
  * degrees -- degrees of generators

Ways to use this method:
========================

  * Matrix * Matrix -- matrix multiplication

Matrix ** Ring -- tensor product
********************************

Synopsis
========

  * Operator: **,
  * Usage:
        f ** R
        R ** f
  * Inputs:
      * f, a matrix,
      * R, a ring,
  * Outputs:
      * a matrix, over $R$, obtained by forming the tensor
        product of the map $f$ with $R$

Description
===========

The ring of $f$ should be a base ring of $R$.  The degree of the map is
preserved.

+---------------------+
|i1 : R = ZZ[a..c];   |
+---------------------+
|i2 : S = R/(a+b+c);  |
+---------------------+
|i3 : f = vars R      |
|                     |
|o3 = | a b c |       |
|                     |
|             1      3|
|o3 : Matrix R  <-- R |
+---------------------+
|i4 : f ** S          |
|                     |
|o4 = | -b-c b c |    |
|                     |
|             1      3|
|o4 : Matrix S  <-- S |
+---------------------+

Ways to use this method:
========================

  * Matrix ** Ring -- tensor product
  * "Ring ** Matrix"

Matrix ** RingElement -- a binary operator, usually used for tensor product or Cartesian product
************************************************************************************************

Synopsis
========

  * Operator: **,
  * Usage:
        f ** r
  * Inputs:
      * f
      * r
  * Outputs:
      * the tensor product of f with r

Description
===========

+-----------------------------+
|i1 : f = matrix "2,3,4;5,6,7"|
|                             |
|o1 = | 2 3 4 |               |
|     | 5 6 7 |               |
|                             |
|              2       3      |
|o1 : Matrix ZZ  <-- ZZ       |
+-----------------------------+
|i2 : f ** 10                 |
|                             |
|o2 = | 20 30 40 |            |
|     | 50 60 70 |            |
|                             |
|              2       3      |
|o2 : Matrix ZZ  <-- ZZ       |
+-----------------------------+

When the ring element is homogeneous, the degrees of the source module can
change, which is what makes this operation different from scalar
multiplication.

+---------------------------------------+
|i3 : QQ[x,y]                           |
|                                       |
|o3 = QQ[x..y]                          |
|                                       |
|o3 : PolynomialRing                    |
+---------------------------------------+
|i4 : f = matrix "x,y"                  |
|                                       |
|o4 = | x y |                           |
|                                       |
|                      1               2|
|o4 : Matrix (QQ[x..y])  <-- (QQ[x..y]) |
+---------------------------------------+
|i5 : g = f ** y^7                      |
|                                       |
|o5 = | xy7 y8 |                        |
|                                       |
|                      1               2|
|o5 : Matrix (QQ[x..y])  <-- (QQ[x..y]) |
+---------------------------------------+
|i6 : h = f * y^7                       |
|                                       |
|o6 = | xy7 y8 |                        |
|                                       |
|                      1               2|
|o6 : Matrix (QQ[x..y])  <-- (QQ[x..y]) |
+---------------------------------------+
|i7 : degrees g                         |
|                                       |
|o7 = {{{0}}, {{8}, {8}}}               |
|                                       |
|o7 : List                              |
+---------------------------------------+
|i8 : degrees h                         |
|                                       |
|o8 = {{{0}}, {{1}, {1}}}               |
|                                       |
|o8 : List                              |
+---------------------------------------+

Ways to use this method:
========================

  * Matrix ** RingElement -- a binary
    operator, usually used for tensor product or Cartesian product

Matrix ++ Matrix -- direct sum of maps
**************************************

Synopsis
========

  * Operator: ++,

Description
===========

f++g -- computes the direct sum of two maps between modules.

If an argument is a ring element or integer, it is promoted to a one by one
matrix.
+-------------------------------+
|i1 : R = ZZ/101[a..c];         |
+-------------------------------+
|i2 : vars R ++ transpose vars R|
|                               |
|o2 = {0}  | a b c 0 |          |
|     {-1} | 0 0 0 a |          |
|     {-1} | 0 0 0 b |          |
|     {-1} | 0 0 0 c |          |
|                               |
|             4      4          |
|o2 : Matrix R  <-- R           |
+-------------------------------+
|i3 : oo^[1]                    |
|                               |
|o3 = {-1} | 0 0 0 a |          |
|     {-1} | 0 0 0 b |          |
|     {-1} | 0 0 0 c |          |
|                               |
|             3      4          |
|o3 : Matrix R  <-- R           |
+-------------------------------+
|i4 : a++b++c                   |
|                               |
|o4 = | a 0 0 |                 |
|     | 0 b 0 |                 |
|     | 0 0 c |                 |
|                               |
|             3      3          |
|o4 : Matrix R  <-- R           |
+-------------------------------+
Selecting rows or columns of blocks:
  * Matrix ^ Array -- component of map corresponding to
    summand of target
  * Matrix _ Array -- component of map corresponding
    to summand of source

See also
========

  * directSum -- direct sum of modules or maps
  * Matrix | Matrix -- join matrices horizontally
  * Matrix || Matrix -- join matrices vertically

Ways to use this method:
========================

  * "GradedModuleMap ++ GradedModuleMap"
  * Matrix ++ Matrix -- direct sum of maps
  * "Matrix ++ RingElement"
  * "RingElement ++ Matrix"
  * "RingElement ++ RingElement"

Matrix / Number -- scalar division
**********************************

Synopsis
========

  * Operator: /,
  * Usage:
        v / c
  * Inputs:
      * v, a matrix, or a vector,
      * c, a number, or a ring element,
  * Outputs:
      * a matrix, or a vector,

Description
===========

This operation is equivalent to right scalar multiplication by the
multiplicative inverse of c, i.e., v * (1/c).

+------------------------------------------------+
|i1 : R = QQ[a,b,c,d]                            |
|                                                |
|o1 = R                                          |
|                                                |
|o1 : PolynomialRing                             |
+------------------------------------------------+
|i2 : matrix {{d, -b}, {-c, a}} / (a * d - b * c)|
|                                                |
|o2 = | (-d)/(bc-ad) b/(bc-ad)    |              |
|     | c/(bc-ad)    (-a)/(bc-ad) |              |
|                                                |
|                    2             2             |
|o2 : Matrix (frac R)  <-- (frac R)              |
+------------------------------------------------+

Caveat
======

The base ring of the output will be a field containing the base ring of v.

Ways to use this method:
========================

  * Matrix / Number -- scalar division
  * "Matrix / RingElement"
  * "Vector / Number"
  * "Vector / RingElement"

Matrix // Matrix -- factor a map through another
************************************************

Synopsis
========

  * Operator: //,
  * Usage:
        f//g
  * Inputs:
      * f, between modules F --> H, or a ring element,
      * g, between modules G --> H, a ring element, a
        monomial ideal, or a Gröbner basis,
  * Outputs:
      * a matrix, a matrix h : F --> G

Description
===========

If f is a matrix, and g is a matrix or Gröbner basis, then quotient(f,g) is an
alternate notation for f//g.

If either f or g is a ring element, then it is taken to be a scalar matrix
acting on H.  If both are ring elements, then the result is also a ring
element.  If g is a MonomialIdeal, then it is taken to be
the matrix of generators of g.  Finally, if g is a GroebnerBasis,
object, then the Gröbner basis as so far computed is used.  In
these latter two cases, no Gröbner bases will be computed.

The resulting matrix h is such that f - g*h is the reduction of f modulo a
Gröbner basis for the image of g.

If the remainder f - g*h is zero, then the quotient f//g satisfies the equation
f === g * (f//g).

One common use is the following.  If an ideal contains 1, then we may write 1
in terms of the generators of the ideal.  First we make an ideal.
+-----------------------------------------------------------------------------+
|i1 : A = ZZ/101[x,y,z]                                                       |
|                                                                             |
|o1 = A                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : F = x^4 - y*z*(1-x)^2 - z - y^3                                         |
|                                                                             |
|      4    2       3                                                         |
|o2 = x  - x y*z - y  + 2x*y*z - y*z - z                                      |
|                                                                             |
|o2 : A                                                                       |
+-----------------------------------------------------------------------------+
|i3 : I = ideal(F,diff(x,F),diff(y,F),diff(z,F))                              |
|                                                                             |
|             4    2       3                       3                     2    |
|o3 = ideal (x  - x y*z - y  + 2x*y*z - y*z - z, 4x  - 2x*y*z + 2y*z, - x z - |
|     ------------------------------------------------------------------------|
|       2                2                                                    |
|     3y  + 2x*z - z, - x y + 2x*y - y - 1)                                   |
|                                                                             |
|o3 : Ideal of A                                                              |
+-----------------------------------------------------------------------------+
Transposing the (row) matrix of generators of the ideal puts the generators on
separate lines and shows the degrees.
+----------------------------------+
|i4 : transpose gens I             |
|                                  |
|o4 = {-4} | x4-x2yz-y3+2xyz-yz-z ||
|     {-3} | 4x3-2xyz+2yz         ||
|     {-3} | -x2z-3y2+2xz-z       ||
|     {-3} | -x2y+2xy-y-1         ||
|                                  |
|             4      1             |
|o4 : Matrix A  <-- A              |
+----------------------------------+
Next we test whether 1 is in the ideal.
+----------+
|i5 : 1 % I|
|          |
|o5 = 0    |
|          |
|o5 : A    |
+----------+
We see that 1 is in the ideal.  Now we represent 1 in terms of the generators
of I.
+-----------------------------------------------------------------------------+
|i6 : h = 1 // gens I                                                         |
|                                                                             |
|o6 = {4} | -46x3y2-4x2y3+11x4z+4x3yz-2x2y2z+22x3z2+50x2yz2+8x3y+36x2y2-xy3+14|
|     {3} | -39x4y2+x3y3-28x5z-x4yz-50x3y2z+45x4z2+38x3yz2-2x4y-9x3y2-25x2y3+4|
|     {3} | 49x3y3+35x2y4+30x4yz-35x3y2z-33x2y3z-41x3yz2+17x2y2z2+31x3y2-12x2y|
|     {3} | -26x3y2z-33x2y3z+15x4z2+33x3yz2+34x2y2z2+30x3z3-42x2yz3-35x3yz-29x|
|     ------------------------------------------------------------------------|
|     x3z+48xy2z+11x2z2-26xyz2-12x3-49x2y-7xy2+5y3-44x2z+12xyz-16y2z-13xz2-46y|
|     7x4z-12x2y2z-28x3z2-44x2yz2+3x4-13x3y+8x2y2+24xy3+11x3z-32x2yz+41xy2z-22|
|     3+34xy4+29x3yz-16xy3z+30x2yz2-25xy2z2+4x3y+50x2y2+36xy3+32y4-19x2yz-4xy2|
|     2y2z+15xy3z+20x3z2+2x2yz2-9xy2z2+26x2z3-38xyz3+25x3y-13x3z-25x2yz-50xy2z|
|     ------------------------------------------------------------------------|
|     z2+19x2-28xy-y2+22xz+9yz-15z2-49x-11y-35z+28                            |
|     x2z2+4xyz2-30x3+7x2y-12xy2+45x2z-17xyz+21y2z+29xz2+2yz2-13x2+28xy-20y2- |
|     z+39y3z+38xyz2+49y2z2-40x2y+43xy2+34y3-26x2z+27xyz-3y2z+49xz2+5yz2-2x2+ |
|     -37y3z-27x2z2-43xyz2+19y2z2-15xz3+yz3+x2y-14x2z+49xyz+7y2z+15xz2-39yz2- |
|     ------------------------------------------------------------------------|
|                                             |                               |
|     17xz+26yz-7x-19y-47z                    |                               |
|     50xy-30y2+15xz-38yz-40z2+35x-43y+26z-34 |                               |
|     46z3-2xy+47xz+20yz+9z2+y+6z-1           |                               |
|                                                                             |
|             4      1                                                        |
|o6 : Matrix A  <-- A                                                         |
+-----------------------------------------------------------------------------+
|i7 : gens I * h                                                              |
|                                                                             |
|o7 = | 1 |                                                                   |
|                                                                             |
|             1      1                                                        |
|o7 : Matrix A  <-- A                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * Matrix % Matrix -- normal
    form of ring elements and matrices
  * generators -- provide matrix or list of generators
  * diff -- differentiate or take difference
  * substitute -- substituting values for variables
  * quotient -- quotient or division
  * remainder -- matrix remainder
  * quotientRemainder -- matrix quotient and
    remainder

Ways to use this method:
========================

  * "Matrix // GroebnerBasis"
  * Matrix // Matrix -- factor a map through another
  * "Matrix // MonomialIdeal"
  * "Matrix // RingElement"
  * "RingElement // GroebnerBasis"
  * "RingElement // Matrix"
  * "RingElement // MonomialIdeal"
  * "RingElement // RingElement"

Matrix ^ ZZ -- power
********************

Synopsis
========

  * Operator: ^,
  * Usage:
        f^n
  * Inputs:
      * f
      * n
  * Outputs:
      * a matrix, f^n

Description
===========

+-----------------------------------------+
|i1 : R = ZZ/7[x]/(x^6-3*x-4)             |
|                                         |
|o1 = R                                   |
|                                         |
|o1 : QuotientRing                        |
+-----------------------------------------+
|i2 : f = matrix{{x,x+1},{x-1,2*x}}       |
|                                         |
|o2 = | x   x+1 |                         |
|     | x-1 2x  |                         |
|                                         |
|             2      2                    |
|o2 : Matrix R  <-- R                     |
+-----------------------------------------+
|i3 : f^2                                 |
|                                         |
|o3 = | 2x2-1  3x2+3x |                   |
|     | 3x2-3x -2x2-1 |                   |
|                                         |
|             2      2                    |
|o3 : Matrix R  <-- R                     |
+-----------------------------------------+
|i4 : f^1000                              |
|                                         |
|o4 = | 3x5-2x4-2x2+2x+3 -2x5+x3-x2+x+1  ||
|     | x5+x4-2x2-3x+1   -x5+2x4-3x3+x-3 ||
|                                         |
|             2      2                    |
|o4 : Matrix R  <-- R                     |
+-----------------------------------------+

If the matrix is invertible, then f^-1 is the inverse.
+---------------------------------------------+
|i5 : M = matrix(QQ,{{1,2,3},{1,5,9},{8,3,1}})|
|                                             |
|o5 = | 1 2 3 |                               |
|     | 1 5 9 |                               |
|     | 8 3 1 |                               |
|                                             |
|              3       3                      |
|o5 : Matrix QQ  <-- QQ                       |
+---------------------------------------------+
|i6 : det M                                   |
|                                             |
|o6 = 9                                       |
|                                             |
|o6 : QQ                                      |
+---------------------------------------------+
|i7 : M^-1                                    |
|                                             |
|o7 = | -22/9 7/9   1/3  |                    |
|     | 71/9  -23/9 -2/3 |                    |
|     | -37/9 13/9  1/3  |                    |
|                                             |
|              3       3                      |
|o7 : Matrix QQ  <-- QQ                       |
+---------------------------------------------+
|i8 : M^-1 * M                                |
|                                             |
|o8 = | 1 0 0 |                               |
|     | 0 1 0 |                               |
|     | 0 0 1 |                               |
|                                             |
|              3       3                      |
|o8 : Matrix QQ  <-- QQ                       |
+---------------------------------------------+
|i9 : R = QQ[x]                               |
|                                             |
|o9 = R                                       |
|                                             |
|o9 : PolynomialRing                          |
+---------------------------------------------+
|i10 : N = matrix{{x^3,x+1},{x^2-x+1,1}}      |
|                                             |
|o10 = | x3     x+1 |                         |
|      | x2-x+1 1   |                         |
|                                             |
|              2      2                       |
|o10 : Matrix R  <-- R                        |
+---------------------------------------------+
|i11 : det N                                  |
|                                             |
|o11 = -1                                     |
|                                             |
|o11 : R                                      |
+---------------------------------------------+
|i12 : N^-1                                   |
|                                             |
|o12 = {3} | -1     x+1 |                     |
|      {1} | x2-x+1 -x3 |                     |
|                                             |
|              2      2                       |
|o12 : Matrix R  <-- R                        |
+---------------------------------------------+
|i13 : N^-1 * N                               |
|                                             |
|o13 = {3} | 1 0 |                            |
|      {1} | 0 1 |                            |
|                                             |
|              2      2                       |
|o13 : Matrix R  <-- R                        |
+---------------------------------------------+

See also
========

  * determinant -- determinant of a matrix

Ways to use this method:
========================

  * Matrix ^ ZZ -- power

Matrix _ Sequence -- get entry of matrix
****************************************

Synopsis
========

  * Operator: _,
  * Usage:
        M_(i,j)
  * Inputs:
      * M, or a mutable matrix,
      * i, both integers
  * Outputs:
      * the (i,j)-th entry of the matrix M, where M_(0,0) is the top left
        entry, a ring element,

Description
===========

All indexing in Macaulay2 is zero-based, so the indices start at zero.
+--------------------------------+
|i1 : M = matrix{{1,2,3},{0,5,6}}|
|                                |
|o1 = | 1 2 3 |                  |
|     | 0 5 6 |                  |
|                                |
|              2       3         |
|o1 : Matrix ZZ  <-- ZZ          |
+--------------------------------+
|i2 : M_(1,2)                    |
|                                |
|o2 = 6                          |
+--------------------------------+
The matrix may be a a mutable matrix, too:
+------------------------+
|i3 : N = mutableMatrix M|
|                        |
|o3 = | 1 2 3 |          |
|     | 0 5 6 |          |
|                        |
|o3 : MutableMatrix      |
+------------------------+
|i4 : N_(1,0)            |
|                        |
|o4 = 0                  |
+------------------------+
Entries of mutable matrices can be changed:
+------------------+
|i5 : N_(1,0) = 37 |
|                  |
|o5 = 37           |
+------------------+
|i6 : N            |
|                  |
|o6 = | 1  2 3 |   |
|     | 37 5 6 |   |
|                  |
|o6 : MutableMatrix|
+------------------+

See also
========

  * Matrix -- the class of all matrices
  * MutableMatrix -- the class of all mutable matrices

Ways to use this method:
========================

  * Matrix _ Sequence -- get entry of matrix
  * "MutableMatrix _ Sequence"

Matrix | Matrix -- join matrices horizontally
*********************************************

Synopsis
========

  * Operator: |,
  * Usage:
        f = g | h
  * Inputs:
      * g, a m by n matrix
      * h, a m by r matrix
  * Outputs:
      * f, the m by n+r matrix, obtained from matrices g and h by concatenating
        the rows

Description
===========

+-----------------------------+
|i1 : R = ZZ[i..p];           |
+-----------------------------+
|i2 : g = matrix {{i,j},{k,l}}|
|                             |
|o2 = | i j |                 |
|     | k l |                 |
|                             |
|             2      2        |
|o2 : Matrix R  <-- R         |
+-----------------------------+
|i3 : h = matrix {{m,n},{o,p}}|
|                             |
|o3 = | m n |                 |
|     | o p |                 |
|                             |
|             2      2        |
|o3 : Matrix R  <-- R         |
+-----------------------------+
|i4 : f= g | h                |
|                             |
|o4 = | i j m n |             |
|     | k l o p |             |
|                             |
|             2      4        |
|o4 : Matrix R  <-- R         |
+-----------------------------+
If one of the arguments is a ring element or a number, then it will be
multiplied by a suitable identity matrix.
+------------------------+
|i5 : f | (m-n)          |
|                        |
|o5 = | i j m n m-n 0   ||
|     | k l o p 0   m-n ||
|                        |
|             2      6   |
|o5 : Matrix R  <-- R    |
+------------------------+

Caveat
======

It is assumed that the matrices g and h have the same Ring.

See also
========

  * Matrix || Matrix -- join matrices vertically
  * ring(Matrix) -- get the associated ring of an object

Ways to use this method:
========================

  * Matrix | Matrix -- join matrices horizontally
  * "Matrix | Number"
  * "Matrix | RingElement"
  * "Number | Matrix"
  * "RingElement | Matrix"
  * "RingElement | RingElement"

Matrix || Matrix -- join matrices vertically
********************************************

Synopsis
========

  * Operator: ||,
  * Usage:
        f = g || h
  * Inputs:
      * g, a m by n matrix.
      * h, a r by n matrix.
  * Outputs:
      * f, the m+r by n matrix, obtained from matrices g and h by concatenating
        the columns.

Description
===========

+-----------------------------+
|i1 : R = ZZ[i..p];           |
+-----------------------------+
|i2 : g = matrix {{i,j},{k,l}}|
|                             |
|o2 = | i j |                 |
|     | k l |                 |
|                             |
|             2      2        |
|o2 : Matrix R  <-- R         |
+-----------------------------+
|i3 : h = matrix {{m,n},{o,p}}|
|                             |
|o3 = | m n |                 |
|     | o p |                 |
|                             |
|             2      2        |
|o3 : Matrix R  <-- R         |
+-----------------------------+
|i4 : f= g || h               |
|                             |
|o4 = | i j |                 |
|     | k l |                 |
|     | m n |                 |
|     | o p |                 |
|                             |
|             4      2        |
|o4 : Matrix R  <-- R         |
+-----------------------------+
If one of the arguments is a ring element or a number, then it will be
multiplied by a suitable identity matrix.
+---------------------+
|i5 : f || 33         |
|                     |
|o5 = {0} | i  j  |   |
|     {0} | k  l  |   |
|     {0} | m  n  |   |
|     {0} | o  p  |   |
|     {1} | 33 0  |   |
|     {1} | 0  33 |   |
|                     |
|             6      2|
|o5 : Matrix R  <-- R |
+---------------------+

Caveat
======

It is assumed that the matrices g and h have the same Ring.

See also
========

  * Matrix | Matrix -- join matrices horizontally
  * ring(Matrix) -- get the associated ring of an object

Ways to use this method:
========================

  * Matrix || Matrix -- join matrices vertically
  * "Matrix || Number"
  * "Matrix || RingElement"
  * "Number || Matrix"
  * "RingElement || Matrix"
  * "RingElement || RingElement"

matrix(List) -- create a matrix from a doubly-nested list of ring elements or matrices
**************************************************************************************

Synopsis
========

  * Function: matrix,
  * Usage:
        matrix v
  * Inputs:
      * v, a list of lists of either ring elements or matrices
  * Optional inputs,:
      * Degree => ..., default value null, an integer or a list of integers, to
        serve as the degree of the matrix
  * Outputs:
      * A matrix where the first list of v gives the first row (or set of rows,
        if the elements are matrices), the second list is the second row, etc.

Description
===========

An attempt is made to coerce the ring elements and matrices to a common ring.
If the entries are ring elements, they are used as the entries of the matrix,
and if the entries are matrices, then they are used to provide blocks of
entries in the resulting matrix.

An attempt is made to set up the degrees of the generators of the free module
serving as source so that the map will be homogeneous and of degree zero.

+-------------------------+
|i1 : R = ZZ/101[x,y,z]   |
|                         |
|o1 = R                   |
|                         |
|o1 : PolynomialRing      |
+-------------------------+
|i2 : p = matrix {{x,y,z}}|
|                         |
|o2 = | x y z |           |
|                         |
|             1      3    |
|o2 : Matrix R  <-- R     |
+-------------------------+
|i3 : degrees source p    |
|                         |
|o3 = {{1}, {1}, {1}}     |
|                         |
|o3 : List                |
+-------------------------+
|i4 : isHomogeneous p     |
|                         |
|o4 = true                |
+-------------------------+
Notice that the degrees were set up so that p is homogeneous, because the
source module is not explicitly specified by the user.  The next example
involves block matrices.
+--------------------------+
|i5 : q = vars R           |
|                          |
|o5 = | x y z |            |
|                          |
|             1      3     |
|o5 : Matrix R  <-- R      |
+--------------------------+
|i6 : matrix {{q,q,q}}     |
|                          |
|o6 = | x y z x y z x y z ||
|                          |
|             1      9     |
|o6 : Matrix R  <-- R      |
+--------------------------+
|i7 : matrix {{q},{q},{q}} |
|                          |
|o7 = | x y z |            |
|     | x y z |            |
|     | x y z |            |
|                          |
|             3      3     |
|o7 : Matrix R  <-- R      |
+--------------------------+
Here we construct a matrix from column vectors.
+---------------------------------------------+
|i8 : F = R^3                                 |
|                                             |
|      3                                      |
|o8 = R                                       |
|                                             |
|o8 : R-module, free                          |
+---------------------------------------------+
|i9 : matrix {F_2, F_1, x*F_0 + y*F_1 + z*F_2}|
|                                             |
|o9 = | 0 0 x |                               |
|     | 0 1 y |                               |
|     | 1 0 z |                               |
|                                             |
|             3      3                        |
|o9 : Matrix R  <-- R                         |
+---------------------------------------------+

See also
========

  * map -- make a map

Ways to use this method:
========================

  * matrix(List) -- create a matrix from a
    doubly-nested list of ring elements or matrices

matrix(Matrix) -- the matrix between generators
***********************************************

Synopsis
========

  * Function: matrix,
  * Usage:
        matrix f
  * Inputs:
      * f, a map of modules
  * Optional inputs,:
      * Degree, => ..., default value null, create a
        matrix from a doubly-nested list of ring elements or matrices
  * Outputs:
      * a matrix, If the source and target of f are free, then
        the result is f itself.  Otherwise, the source and target will be
        replaced by the free modules whose basis elements correspond to the
        generators of the modules.

Description
===========

Each homomorphism of modules $f : M \rightarrow N$ in Macaulay2 is induced from
a matrix $f0 : \mathtt{cover} M \rightarrow \mathtt{cover} N$. This function
returns this matrix.
+------------------------------------+
|i1 : R = QQ[a..d];                  |
+------------------------------------+
|i2 : I = ideal(a^2,b^2,c*d)         |
|                                    |
|             2   2                  |
|o2 = ideal (a , b , c*d)            |
|                                    |
|o2 : Ideal of R                     |
+------------------------------------+
|i3 : f = basis(3,I)                 |
|                                    |
|o3 = {2} | a b c d 0 0 0 0 0 0 0 0 ||
|     {2} | 0 0 0 0 a b c d 0 0 0 0 ||
|     {2} | 0 0 0 0 0 0 0 0 a b c d ||
|                                    |
|o3 : Matrix                         |
+------------------------------------+
|i4 : source f                       |
|                                    |
|      12                            |
|o4 = R                              |
|                                    |
|o4 : R-module, free, degrees {12:3} |
+------------------------------------+
|i5 : target f                       |
|                                    |
|o5 = image | a2 b2 cd |             |
|                                    |
|                             1      |
|o5 : R-module, submodule of R       |
+------------------------------------+
The map f is induced by the following 3 by 12 matrix from R^12 to the 3
generators of I.
+------------------------------------+
|i6 : matrix f                       |
|                                    |
|o6 = {2} | a b c d 0 0 0 0 0 0 0 0 ||
|     {2} | 0 0 0 0 a b c d 0 0 0 0 ||
|     {2} | 0 0 0 0 0 0 0 0 a b c d ||
|                                    |
|             3      12              |
|o6 : Matrix R  <-- R                |
+------------------------------------+
To obtain the map that is the composite of this with the inclusion of I onto R,
use super(Matrix).
+------------------------------------------------------+
|i7 : super f                                          |
|                                                      |
|o7 = | a3 a2b a2c a2d ab2 b3 b2c b2d acd bcd c2d cd2 ||
|                                                      |
|             1      12                                |
|o7 : Matrix R  <-- R                                  |
+------------------------------------------------------+

See also
========

  * cover -- get the covering free module
  * super -- get the ambient module
  * basis -- basis or generating set of all or part of a ring,
    ideal or module

Ways to use this method:
========================

  * matrix(Matrix) -- the matrix between generators

matrix(MutableMatrix) -- make a matrix from a mutable one
*********************************************************

Synopsis
========

  * Function: matrix,
  * Usage:
        matrix m
  * Inputs:
      * m
  * Optional inputs,:
      * Degree, => ..., default value null, create a
        matrix from a doubly-nested list of ring elements or matrices
  * Outputs:
      * a matrix, the same matrix as m, but not mutable.

Description
===========

There are many more operations available for matrices than for immutable
matrices, but mutable matrices are sometimes easier to construct.
+------------------------------+
|i1 : m = mutableMatrix(ZZ,3,5)|
|                              |
|o1 = 0                        |
|                              |
|o1 : MutableMatrix            |
+------------------------------+
|i2 : m_(1,2) = 3              |
|                              |
|o2 = 3                        |
+------------------------------+
|i3 : m_(2,4) = 54             |
|                              |
|o3 = 54                       |
+------------------------------+
|i4 : m_(0,0) = -12            |
|                              |
|o4 = -12                      |
+------------------------------+
|i5 : m                        |
|                              |
|o5 = | -12 0 0 0 0  |         |
|     | 0   0 3 0 0  |         |
|     | 0   0 0 0 54 |         |
|                              |
|o5 : MutableMatrix            |
+------------------------------+
|i6 : matrix m                 |
|                              |
|o6 = | -12 0 0 0 0  |         |
|     | 0   0 3 0 0  |         |
|     | 0   0 0 0 54 |         |
|                              |
|              3       5       |
|o6 : Matrix ZZ  <-- ZZ        |
+------------------------------+

See also
========

  * mutableMatrix -- make a mutable matrix
  * mutableIdentity -- make a mutable
    identity matrix
  * MutableMatrix -- the class of all mutable matrices

Ways to use this method:
========================

  * matrix(MutableMatrix) -- make a matrix
    from a mutable one

matrix(Ring,List) -- create a matrix from a doubly nested list of ring elements or matrices
*******************************************************************************************

Synopsis
========

  * Function: matrix,
  * Usage:
        matrix(R, v)
  * Inputs:
      * R
      * v, a list of vectors; or a doubly nested list of ring elements and/or
        matrices
  * Optional inputs,:
      * Degree, => ..., default value null, create a
        matrix from a doubly-nested list of ring elements or matrices
  * Outputs:
      * A matrix over R, whose source and target are both free, formed by the
        elements of v.

Description
===========

All of the vectors, ring elements, or matrices must be defined over the ring R,
or a base ring of R.

If a doubly nested list of matrices is given, then ring elements can be used
for 1 by 1 blocks, and 0 represents a zero block.

This is essentially the same as matrix(List), together
with the specification of the ring.

+----------------------------+
|i1 : R = QQ[a..d];          |
+----------------------------+
|i2 : f = matrix{{a,b},{c,0}}|
|                            |
|o2 = | a b |                |
|     | c 0 |                |
|                            |
|             2      2       |
|o2 : Matrix R  <-- R        |
+----------------------------+
|i3 : h = matrix{{f,f},{f,0}}|
|                            |
|o3 = | a b a b |            |
|     | c 0 c 0 |            |
|     | a b 0 0 |            |
|     | c 0 0 0 |            |
|                            |
|             4      4       |
|o3 : Matrix R  <-- R        |
+----------------------------+

Ways to use this method:
========================

  * matrix(Ring,List) -- create a matrix from a
    doubly nested list of ring elements or matrices
  * "matrix(RingFamily,List)"

matrix(RingElement) -- make a matrix from a ring element
********************************************************

Synopsis
========

  * Function: matrix,
  * Usage:
        matrix r
  * Inputs:
      * r
  * Optional inputs,:
      * Degree, => ..., default value null, create a
        matrix from a doubly-nested list of ring elements or matrices
  * Outputs:
      * a matrix, the one by one matrix with r as its single
        entry

Description
===========

+-----------------------+
|i1 : matrix 48         |
|                       |
|o1 = | 48 |            |
|                       |
|              1       1|
|o1 : Matrix ZZ  <-- ZZ |
+-----------------------+

Ways to use this method:
========================

  * "matrix(Number)"
  * matrix(RingElement) -- make a matrix from a
    ring element

matrix(RingMap) -- the matrix associated to a ring map
******************************************************

Synopsis
========

  * Function: matrix,
  * Usage:
        matrix f
  * Inputs:
      * f
  * Optional inputs,:
      * Degree, => ..., default value null, create a
        matrix from a doubly-nested list of ring elements or matrices
  * Outputs:
      * the matrix associated to the ring map f, computed by applying f to the
        matrix of variables of its source ring

Description
===========

+-------------------------------+
|i1 : R = QQ[x,y]               |
|                               |
|o1 = R                         |
|                               |
|o1 : PolynomialRing            |
+-------------------------------+
|i2 : S = QQ[s,t,u]             |
|                               |
|o2 = S                         |
|                               |
|o2 : PolynomialRing            |
+-------------------------------+
|i3 : f = map(R,S,{x^2,x*y,y^2})|
|                               |
|                  2        2   |
|o3 = map (R, S, {x , x*y, y }) |
|                               |
|o3 : RingMap R <-- S           |
+-------------------------------+
|i4 : matrix f                  |
|                               |
|o4 = | x2 xy y2 |              |
|                               |
|             1      3          |
|o4 : Matrix R  <-- R           |
+-------------------------------+

Ways to use this method:
========================

  * matrix(RingMap) -- the matrix associated to a
    ring map

matrix(Vector) -- make a matrix
*******************************

Synopsis
========

  * Function: matrix,
  * Usage:
        matrix v
  * Inputs:
      * v,
  * Optional inputs,:
      * Degree, => ..., default value null, create a
        matrix from a doubly-nested list of ring elements or matrices
  * Outputs:
      * a vector, the matrix with a single column containing the
        vector v

Description
===========

+-----------------------+
|i1 : v = vector {1,2,3}|
|                       |
|o1 = | 1 |             |
|     | 2 |             |
|     | 3 |             |
|                       |
|       3               |
|o1 : ZZ                |
+-----------------------+
|i2 : matrix v          |
|                       |
|o2 = | 1 |             |
|     | 2 |             |
|     | 3 |             |
|                       |
|              3       1|
|o2 : Matrix ZZ  <-- ZZ |
+-----------------------+

Ways to use this method:
========================

  * matrix(Vector) -- make a matrix

MatrixExpression -- the class of all matrix expressions
*******************************************************

Description
===========

MatrixExpression is a type of Expression, representing a
matrix.

+-----------------------------------------------------------------------------+
|i1 : MatrixExpression {{a,b,c},{a,bb,ccc}}                                   |
|                                                                             |
|o1 = | a b  c   |                                                            |
|     | a bb ccc |                                                            |
|                                                                             |
|o1 : Expression of class MatrixExpression                                    |
+-----------------------------------------------------------------------------+
|i2 : R=QQ[x,y];                                                              |
+-----------------------------------------------------------------------------+
|i3 : MatrixExpression append(applyTable({{x^2-y^2,x^3-y^3},{x^2-4*y^2,x^3+y^3|
|                                                                             |
|o3 = {-2} | (x-y)(x+y)   (x-y)(x2+xy+y2) |                                   |
|     {-3} | (x-2y)(x+2y) (x+y)(x2-xy+y2) |                                   |
|                                                                             |
|o3 : Expression of class MatrixExpression                                    |
|-----------------------------------------------------------------------------|
|}},factor),Degrees=>{{{-2},{-3}},{{0},{0}}})                                 |
+-----------------------------------------------------------------------------+
|i4 : value oo                                                                |
|                                                                             |
|o4 = {-2} | x2-y2  x3-y3 |                                                   |
|     {-3} | x2-4y2 x3+y3 |                                                   |
|                                                                             |
|             2      2                                                        |
|o4 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * Table -- the class of all table expressions

For the programmer
==================

The object MatrixExpression, is a header type,
with ancestor classes Expression, <
BasicList < Thing.

max -- yields the maximum element in a list or sequence
*******************************************************

Synopsis
========

  * Usage:
        max X
  * Inputs:
      * X, a visible list,
  * Outputs:
      * m, a thing,

Description
===========

+---------------------------------------------+
|i1 : X = for i from 1 to 10 list random(100) |
|                                             |
|o1 = {24, 65, 71, 72, 19, 19, 91, 72, 93, 79}|
|                                             |
|o1 : List                                    |
+---------------------------------------------+
|i2 : max X                                   |
|                                             |
|o2 = 93                                      |
+---------------------------------------------+

If L contains elements in a polynomial ring, the MonomialOrder,
of the ring is used for comparisons.

+------------------------------------------------+
|i3 : R1 = QQ[x, y, z, MonomialOrder => Lex];    |
+------------------------------------------------+
|i4 : max {x*y^2, x*y^2 + z^2, y^4, y*z^5}       |
|                                                |
|        2    2                                  |
|o4 = x*y  + z                                   |
|                                                |
|o4 : R1                                         |
+------------------------------------------------+
|i5 : R2 = QQ[x, y, z, MonomialOrder => GRevLex];|
+------------------------------------------------+
|i6 : max (x*y^2, x*y^2 + z^2, y^4, y*z^5)       |
|                                                |
|        5                                       |
|o6 = y*z                                        |
|                                                |
|o6 : R2                                         |
+------------------------------------------------+

More generally, the order of the elements is determined using the ?,
operator.

If X is a list of lists, max acts on the outermost level.

+--------------------------------------------------+
|i7 : max {{3, 1, 2}, {2, 9, 6}, {3, 7, 5}}        |
|                                                  |
|o7 = {3, 7, 5}                                    |
|                                                  |
|o7 : List                                         |
+--------------------------------------------------+
|i8 : max flatten {{3, 1, 2}, {2, 9, 6}, {3, 7, 5}}|
|                                                  |
|o8 = 9                                            |
+--------------------------------------------------+

See also
========

  * maxPosition -- position of the largest element
  * min -- yields the minimum element in a list or sequence
  * sort -- sort a list or columns of a matrix
  * ? -- comparison operator

Ways to use max:
================

  * "max(VisibleList)"
  * max(GradedModule)

For the programmer
==================

The object max, is a method function with a single argument.

max(GradedModule)
*****************

Synopsis
========

  * Function: max,
  * Usage:
        max C
  * Inputs:
      * C
  * Outputs:
      * an integer, the maximum index of a component, possibly zero,
        of the graded module C

Description
===========

+---------------------------------------------------+
|i1 : R = QQ[a..e]                                  |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : C = res coker vars R                          |
|                                                   |
|      1      5      10      10      5      1       |
|o2 = R  <-- R  <-- R   <-- R   <-- R  <-- R  <-- 0 |
|                                                   |
|     0      1      2       3       4      5      6 |
|                                                   |
|o2 : ChainComplex                                  |
+---------------------------------------------------+
|i3 : max C                                         |
|                                                   |
|o3 = 6                                             |
+---------------------------------------------------+
|i4 : dual C                                        |
|                                                   |
|             1      5      10      10      5      1|
|o4 = 0  <-- R  <-- R  <-- R   <-- R   <-- R  <-- R |
|                                                   |
|     -6     -5     -4     -3      -2      -1     0 |
|                                                   |
|o4 : ChainComplex                                  |
+---------------------------------------------------+
|i5 : max dual C                                    |
|                                                   |
|o5 = 0                                             |
+---------------------------------------------------+

See also
========

  * min(GradedModule)

Ways to use this method:
========================

  * max(GradedModule)

maxExponent
***********

Description
===========

This constant is the largest exponent (of 2) that can be stored internally in
the binary representation of an inexact real (or complex) number.  It cannot be
changed.
+----------------+
|i1 : maxExponent|
|                |
|o1 = 1073741823 |
+----------------+

For the programmer
==================

The object maxExponent, is an integer.

maxPosition -- position of the largest element
**********************************************

Synopsis
========

  * Usage:
        maxPosition L
  * Inputs:
      * L, a basic list,
  * Outputs:
      * i, an integer, the index of the largest element in the list
        L

Description
===========

If the largest element occurs more than once, the index of its first occurrence
is used.

+--------------------------------+
|i1 : maxPosition {1, 6, 4, 2, 6}|
|                                |
|o1 = 1                          |
+--------------------------------+

If L contains elements in a polynomial ring, the MonomialOrder,
of the ring is used for comparisons.

+-------------------------------------------------+
|i2 : R1 = QQ[x, y, z, MonomialOrder => Lex];     |
+-------------------------------------------------+
|i3 : maxPosition {x*y^2, x*y^2 + z^2, y^4, y*z^5}|
|                                                 |
|o3 = 1                                           |
+-------------------------------------------------+
|i4 : R2 = QQ[x, y, z, MonomialOrder => GRevLex]; |
+-------------------------------------------------+
|i5 : maxPosition (x*y^2, x*y^2 + z^2, y^4, y*z^5)|
|                                                 |
|o5 = 3                                           |
+-------------------------------------------------+

More generally, the order of the elements is determined using the ?,
operator.

See also
========

  * minPosition -- position of the smallest element
  * max -- yields the maximum element in a list or sequence
  * min -- yields the minimum element in a list or sequence
  * sort -- sort a list or columns of a matrix
  * position -- the first element of a list satisfying a
    condition
  * positions -- which elements of a list satisfy a condition
  * ? -- comparison operator

Ways to use maxPosition:
========================

  * "maxPosition(BasicList)"

For the programmer
==================

The object maxPosition, is a method function with a single argument.

memoize -- record results of function evaluation for future use
***************************************************************

Description
===========

memoize f -- produces, from a function f, a new function that behaves the same
as f, but remembers previous answers to be provided the next time the same
arguments are presented.

+---------------------------------------------------------+
|i1 : fib = n -> if n <= 1 then 1 else fib(n-1) + fib(n-2)|
|                                                         |
|o1 = fib                                                 |
|                                                         |
|o1 : FunctionClosure                                     |
+---------------------------------------------------------+
|i2 : time fib 28                                         |
| -- used 0.642152s (cpu); 0.47692s (thread); 0s (gc)     |
|                                                         |
|o2 = 514229                                              |
+---------------------------------------------------------+
|i3 : fib = memoize fib                                   |
|                                                         |
|o3 = fib                                                 |
|                                                         |
|o3 : FunctionClosure                                     |
+---------------------------------------------------------+
|i4 : time fib 28                                         |
| -- used 4.1138e-05s (cpu); 4.0642e-05s (thread); 0s (gc)|
|                                                         |
|o4 = 514229                                              |
+---------------------------------------------------------+
|i5 : time fib 28                                         |
| -- used 2.667e-06s (cpu); 2.463e-06s (thread); 0s (gc)  |
|                                                         |
|o5 = 514229                                              |
+---------------------------------------------------------+

An optional second argument to memoize provides a list of initial values, each
of the form x => v, where v is the value to be provided for the argument x.

Alternatively, values can be provided after defining the memoized function
using the syntax f x = v. A slightly more efficient implementation of the above
would be

+----------------------------------------------+
|i6 : fib = memoize( n -> fib(n-1) + fib(n-2) )|
|                                              |
|o6 = fib                                      |
|                                              |
|o6 : FunctionClosure                          |
+----------------------------------------------+
|i7 : fib 0 = fib 1 = 1;                       |
+----------------------------------------------+
|i8 : fib 28                                   |
|                                              |
|o8 = 514229                                   |
+----------------------------------------------+

The function memoize operates by constructing a MutableHashTable,
in which the arguments are used as keys for accessing the
return value of the function.  This mutable hash table can be obtained using
the function memoizeValues, as follows.

+-----------------------------------+
|i9 : peek memoizeValues fib        |
|                                   |
|o9 = MutableHashTable{0 => 1      }|
|                      1 => 1       |
|                      2 => 2       |
|                      3 => 3       |
|                      4 => 5       |
|                      5 => 8       |
|                      6 => 13      |
|                      7 => 21      |
|                      8 => 34      |
|                      9 => 55      |
|                      10 => 89     |
|                      11 => 144    |
|                      12 => 233    |
|                      13 => 377    |
|                      14 => 610    |
|                      15 => 987    |
|                      16 => 1597   |
|                      17 => 2584   |
|                      18 => 4181   |
|                      19 => 6765   |
|                      20 => 10946  |
|                      21 => 17711  |
|                      22 => 28657  |
|                      23 => 46368  |
|                      24 => 75025  |
|                      25 => 121393 |
|                      26 => 196418 |
|                      27 => 317811 |
|                      28 => 514229 |
+-----------------------------------+

That hash table can be replaced by an empty one with the function memoizeClear.

+----------------------------+
|i10 : memoizeClear fib      |
+----------------------------+
|i11 : peek memoizeValues fib|
|                            |
|o11 = MutableHashTable{}    |
+----------------------------+

Warning: the new function created by memoize will save references to all
arguments and values it encounters, and this will often prevent those arguments
and values from being garbage-collected as soon as they might have been.  If
the arguments are implemented as mutable hash tables (modules, matrices and
rings are implemented this way) then a viable strategy is to stash computed
results in the arguments themselves.  See also CacheTable.

Ways to use memoize:
====================

  * "memoize(Function)"
  * "memoize(Function,List)"

For the programmer
==================

The object memoize, is a method function.

mergePairs -- merge sorted lists of pairs
*****************************************

Synopsis
========

  * Usage:
        mergePairs(x,y,f)
  * Inputs:
      * x, a basic list,
      * y, a basic list,
      * f, a function,
  * Outputs:
      * a basic list,

Description
===========

This function merges sorted lists of pairs.

It merges x and y, which should be lists of pairs (k,v) arranged in increasing
order according to the key k. The result will be a list of pairs, also arranged
in increasing order, each of which is either from x or from y, or in the case
where a key k occurs in both, with say (k,v) in x and (k,w) in y, then the
result will contain the pair (k,f(v,w)). Thus the function f is used for
combining the values when the keys collide.

The class of the result is taken to be the minimal common ancestor of the class
of x and the class of y.

See also
========

  * merge -- merge two hash tables

Ways to use mergePairs:
=======================

  * "mergePairs(BasicList,BasicList,Function)"

For the programmer
==================

The object mergePairs, is a compiled function.

methodOptions(Function) -- recover the options used when a method function was created
**************************************************************************************

Synopsis
========

  * Function: methodOptions,
  * Usage:
        methodOptions f
  * Inputs:
      * f
  * Outputs:
      * the options used when f was created by method,

Description
===========

+-----------------------------------------------------------------------------+
|i1 : methodOptions source                                                    |
|                                                                             |
|o1 = OptionTable{Binary => false                         }                   |
|                 Dispatch => {Thing, Thing, Thing, Thing}                    |
|                 Options => null                                             |
|                 TypicalValue => Thing                                       |
|                                                                             |
|o1 : OptionTable                                                             |
+-----------------------------------------------------------------------------+
|i2 : methodOptions res                                                       |
|                                                                             |
|o2 = OptionTable{Binary => false                                             |
|                 Dispatch => {Thing, Thing, Thing, Thing}                    |
|                 Options => {StopBeforeComputation => false, LengthLimit =>  |
|                 TypicalValue => Thing                                       |
|                                                                             |
|o2 : OptionTable                                                             |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|infinity, DegreeLimit => null, SyzygyLimit => infinity, PairLimit =>         |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|infinity, HardDegreeLimit => {}, SortStrategy => 0, Strategy => null,        |
|-----------------------------------------------------------------------------|
|                                                      }                      |
|                                                                             |
|FastNonminimal => false, ParallelizeByDegree => false}                       |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * "methodOptions(Command)"
  * methodOptions(Function) -- recover the
    options used when a method function was created
  * "methodOptions(ScriptedFunctor)"

methods for normal forms and remainder -- normal form of ring elements and matrices
***********************************************************************************

Synopsis
========

  * Usage:
        f % I
  * Inputs:
      * f, a ring element, or a matrix,
      * I, a ring element, an ideal, or a
        monomial ideal,
  * Outputs:
      * a matrix, the normal form of f modulo the ideal I. The
        result is obtained by reducing each entry of f modulo I.

To reduce f with respect to I, a (partial) Gröbner basis of I is computed,
unless it has already been done, or unless I is a monomial ideal.

+-----------------------------------------------+
|i1 : R = ZZ/1277[x,y];                         |
+-----------------------------------------------+
|i2 : I = ideal(x^3 - 2*x*y, x^2*y - 2*y^2 + x);|
|                                               |
|o2 : Ideal of R                                |
+-----------------------------------------------+
|i3 : (x^3 - 2*x) % I                           |
|                                               |
|o3 = -2x                                       |
|                                               |
|o3 : R                                         |
+-----------------------------------------------+
|i4 : (x^3) % I                                 |
|                                               |
|o4 = 0                                         |
|                                               |
|o4 : R                                         |
+-----------------------------------------------+
|i5 : S = ZZ[x,y];                              |
+-----------------------------------------------+
|i6 : 144*x^2*y^2 % (7*x*y-2)                   |
|                                               |
|         2 2                                   |
|o6 = - 3x y  + 12                              |
|                                               |
|o6 : S                                         |
+-----------------------------------------------+

Synopsis
========

  * Usage:
        f % M
  * Inputs:
      * f, a ring element, or a matrix,
      * M, a module, or a matrix,
  * Outputs:
      * a matrix, the normal form of the matrix f modulo the
        image of M, if M is a matrix with the same target as f, or modulo M if
        M is a submodule of the target of f.  The result is obtained by
        reducing each column of f modulo M.
+--------------------------------------------------------+
|i7 : S = QQ[a..f]                                       |
|                                                        |
|o7 = S                                                  |
|                                                        |
|o7 : PolynomialRing                                     |
+--------------------------------------------------------+
|i8 : J = ideal(a*b*c-d*e*f,a*b*d-c*e*f, a*c*e-b*d*f)    |
|                                                        |
|o8 = ideal (a*b*c - d*e*f, a*b*d - c*e*f, a*c*e - b*d*f)|
|                                                        |
|o8 : Ideal of S                                         |
+--------------------------------------------------------+
|i9 : C = res J                                          |
|                                                        |
|      1      3      6      6      2                     |
|o9 = S  <-- S  <-- S  <-- S  <-- S  <-- 0               |
|                                                        |
|     0      1      2      3      4      5               |
|                                                        |
|o9 : ChainComplex                                       |
+--------------------------------------------------------+
|i10 : F = syz transpose C.dd_4                          |
|                                                        |
|o10 = {-8} | 0 0 a de  ce bd  bc  0   0   0  0   |      |
|      {-8} | 0 b 0 df  cf 0   0   ad  ac  0  0   |      |
|      {-8} | c 0 0 -ef 0  -bf 0   -ae 0   ab 0   |      |
|      {-8} | d 0 0 0   ef 0   bf  0   ae  0  ab  |      |
|      {-8} | 0 e 0 0   0  -df -cf 0   0   ad -ac |      |
|      {-8} | 0 0 f 0   0  0   0   -de -ce bd -bc |      |
|                                                        |
|              6      11                                 |
|o10 : Matrix S  <-- S                                   |
+--------------------------------------------------------+
|i11 : G = transpose C.dd_3                              |
|                                                        |
|o11 = {-8} | bd  -ce de  a 0  0  |                      |
|      {-8} | -ac -cf df  0 -b 0  |                      |
|      {-8} | -bf -ab -ef 0 0  -c |                      |
|      {-8} | -ae -ef -ab 0 0  -d |                      |
|      {-8} | -df -ad ac  0 -e 0  |                      |
|      {-8} | ce  -bd bc  f 0  0  |                      |
|                                                        |
|              6      6                                  |
|o11 : Matrix S  <-- S                                   |
+--------------------------------------------------------+

Since C is a complex, we know that the image of G is contained in the image of
F.

+---------------------------------------------------+
|i12 : G % F                                        |
|                                                   |
|o12 = 0                                            |
|                                                   |
|              6      6                             |
|o12 : Matrix S  <-- S                              |
+---------------------------------------------------+
|i13 : F % G                                        |
|                                                   |
|o13 = {-8} | 0 0 0 de  ce bd  bc  0   bd  -ce de  ||
|      {-8} | 0 0 0 df  cf 0   0   ad  0   -cf df  ||
|      {-8} | 0 0 0 -ef 0  -bf 0   -ae -bf 0   -ef ||
|      {-8} | 0 0 0 0   ef 0   bf  0   0   -ef 0   ||
|      {-8} | 0 0 0 0   0  -df -cf 0   -df 0   0   ||
|      {-8} | 0 0 0 0   0  0   0   -de 0   0   0   ||
|                                                   |
|              6      11                            |
|o13 : Matrix S  <-- S                              |
+---------------------------------------------------+

The inclusion is strict, since F % G != 0 implies that the image of F is not
contained in the image of G.

Normal forms work over quotient rings too.

+---------------------------------+
|i14 : A = QQ[x,y,z]/(x^3-y^2-3)  |
|                                 |
|o14 = A                          |
|                                 |
|o14 : QuotientRing               |
+---------------------------------+
|i15 : I = ideal(x^4, y^4)        |
|                                 |
|                2        4       |
|o15 = ideal (x*y  + 3x, y )      |
|                                 |
|o15 : Ideal of A                 |
+---------------------------------+
|i16 : J = ideal(x^3*y^2, x^2*y^3)|
|                                 |
|              4     2   2 3      |
|o16 = ideal (y  + 3y , x y )     |
|                                 |
|o16 : Ideal of A                 |
+---------------------------------+
|i17 : (gens J) % I               |
|                                 |
|o17 = 0                          |
|                                 |
|              1      2           |
|o17 : Matrix A  <-- A            |
+---------------------------------+

Here is an example involving rational functions.

+----------------------------------------------+
|i18 : kk = frac(ZZ[a,b])                      |
|                                              |
|o18 = kk                                      |
|                                              |
|o18 : FractionField                           |
+----------------------------------------------+
|i19 : B = kk[x,y,z]                           |
|                                              |
|o19 = B                                       |
|                                              |
|o19 : PolynomialRing                          |
+----------------------------------------------+
|i20 : I = ideal(a*x^2-b*x-y-1, 1/b*y^2-z-1)   |
|                                              |
|                2                1  2         |
|o20 = ideal (a*x  - b*x - y - 1, -*y  - z - 1)|
|                                 b            |
|                                              |
|o20 : Ideal of B                              |
+----------------------------------------------+
|i21 : gens gb I                               |
|                                              |
|o21 = | y2-bz-b x2+(-b)/ax+(-1)/ay+(-1)/a |   |
|                                              |
|              1      2                        |
|o21 : Matrix B  <-- B                         |
+----------------------------------------------+
|i22 : x^2*y^2 % I                             |
|                                              |
|       2                2                     |
|      b        b       b      b     b     b   |
|o22 = --*x*z + -*y*z + --*x + -*y + -*z + -   |
|       a       a        a     a     a     a   |
|                                              |
|o22 : B                                       |
+----------------------------------------------+

See also
========

  * % -- a binary operator, usually used for remainder and reduction
  * Gröbner bases
  * generators -- provide matrix or list of generators
  * Matrix % GroebnerBasis -- calculate the
    normal form of ring elements and matrices using a (partially computed)
    Gröbner basis

midpoint -- midpoint of an interval
***********************************

Synopsis
========

  * Usage:
        x = midpoint I
  * Inputs:
      * I, a real interval,
  * Outputs:
      * x, a real number,

Description
===========

Returns the midpoint (the average of the endpoints) of the input interval.

See also
========

  * left -- left endpoint of an interval
  * right -- right endpoint of an interval
  * diameter -- diameter of an interval

For the programmer
==================

The object midpoint, is a compiled function.

min -- yields the minimum element in a list or sequence
*******************************************************

Synopsis
========

  * Usage:
        min X
  * Inputs:
      * X, a visible list,
  * Outputs:
      * m, a thing,

Description
===========

+---------------------------------------------+
|i1 : X = for i from 1 to 10 list random(100) |
|                                             |
|o1 = {24, 65, 71, 72, 19, 19, 91, 72, 93, 79}|
|                                             |
|o1 : List                                    |
+---------------------------------------------+
|i2 : min X                                   |
|                                             |
|o2 = 19                                      |
+---------------------------------------------+

If L contains elements in a polynomial ring, the MonomialOrder,
of the ring is used for comparisons.

+------------------------------------------------+
|i3 : R1 = QQ[x, y, z, MonomialOrder => Lex];    |
+------------------------------------------------+
|i4 : min {x*y^2, x*y^2 + z^2, y^4, y*z^5}       |
|                                                |
|        5                                       |
|o4 = y*z                                        |
|                                                |
|o4 : R1                                         |
+------------------------------------------------+
|i5 : R2 = QQ[x, y, z, MonomialOrder => GRevLex];|
+------------------------------------------------+
|i6 : min (x*y^2, x*y^2 + z^2, y^4, y*z^5)       |
|                                                |
|        2                                       |
|o6 = x*y                                        |
|                                                |
|o6 : R2                                         |
+------------------------------------------------+

More generally, the order of the elements is determined using the ?,
operator.

If X is a list of lists, min acts on the outermost level.

+--------------------------------------------------+
|i7 : min {{3, 1, 2}, {2, 9, 6}, {3, 7, 5}}        |
|                                                  |
|o7 = {2, 9, 6}                                    |
|                                                  |
|o7 : List                                         |
+--------------------------------------------------+
|i8 : min flatten {{3, 1, 2}, {2, 9, 6}, {3, 7, 5}}|
|                                                  |
|o8 = 1                                            |
+--------------------------------------------------+

See also
========

  * minPosition -- position of the smallest element
  * max -- yields the maximum element in a list or sequence
  * sort -- sort a list or columns of a matrix
  * ? -- comparison operator

Ways to use min:
================

  * "min(VisibleList)"
  * min(GradedModule)

For the programmer
==================

The object min, is a method function with a single argument.

min(GradedModule)
*****************

Synopsis
========

  * Function: min,
  * Usage:
        max C
  * Inputs:
      * C
  * Outputs:
      * an integer, the minimum index of a component, possibly zero,
        of the graded module C

Description
===========

+---------------------------------------------------+
|i1 : R = QQ[a..e]                                  |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : C = res coker vars R                          |
|                                                   |
|      1      5      10      10      5      1       |
|o2 = R  <-- R  <-- R   <-- R   <-- R  <-- R  <-- 0 |
|                                                   |
|     0      1      2       3       4      5      6 |
|                                                   |
|o2 : ChainComplex                                  |
+---------------------------------------------------+
|i3 : min C                                         |
|                                                   |
|o3 = 0                                             |
+---------------------------------------------------+
|i4 : dual C                                        |
|                                                   |
|             1      5      10      10      5      1|
|o4 = 0  <-- R  <-- R  <-- R   <-- R   <-- R  <-- R |
|                                                   |
|     -6     -5     -4     -3      -2      -1     0 |
|                                                   |
|o4 : ChainComplex                                  |
+---------------------------------------------------+
|i5 : min dual C                                    |
|                                                   |
|o5 = -6                                            |
+---------------------------------------------------+

See also
========

  * max(GradedModule)

Ways to use this method:
========================

  * min(GradedModule)

minExponent
***********

Description
===========

This constant is the smallest exponent (of 2) that can be stored internally in
the binary representation of an inexact real (or complex) number.  It cannot be
changed.
+----------------+
|i1 : minExponent|
|                |
|o1 = -1073741824|
+----------------+

For the programmer
==================

The object minExponent, is an integer.

mingens -- minimal generator matrix
***********************************

Description
===========

Every ideal and module in Macaulay2 comes equipped with a generating set, which
is sometimes a larger generating set than is required.  This routine returns a
matrix whose columns generate the given ideal or module.

See also
========

  * trim -- minimize generators and relations
  * minimalPresentation -- compute a minimal
    presentation

Ways to use mingens:
====================

  * mingens(GroebnerBasis) -- (partially
    constructed) minimal generator matrix
  * "mingens(Ideal)" -- see mingens(Module), --
    minimal generator matrix
  * mingens(Module) -- minimal generator matrix
  * "mingens(MonomialIdeal)" -- see mingens(Module),
    -- minimal generator matrix

For the programmer
==================

The object mingens, is a method function with options.

mingens(GroebnerBasis) -- (partially constructed) minimal generator matrix
**************************************************************************

Synopsis
========

  * Function: mingens,
  * Usage:
        mingens G
  * Inputs:
      * G
  * Optional inputs,:
      * Strategy, => ..., default value null, a Strategy
        option value
  * Outputs:
      * whose columns form a (partially computed) minimal generating set, a
        matrix,

Description
===========

Every GroebnerBasis computation in Macaulay2 computes a generator matrix, in
the process of constructing the Gröbner basis.  If the original ideal or module
is homogeneous, then the columns of this matrix form a minimal set of
generators.  In the inhomogeneous case, the columns generate, and an attempt is
made to keep the size of the generating set small.

If the Gröbner basis is only partially constructed, the returned result will be
a partial answer.  In the graded case this set can be extended to a minimal set
of generators for the ideal or module.
+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..f]                                                            |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : M = genericSymmetricMatrix(R,a,3)                                       |
|                                                                             |
|o2 = | a b c |                                                               |
|     | b d e |                                                               |
|     | c e f |                                                               |
|                                                                             |
|             3      3                                                        |
|o2 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i3 : I = minors(2,M)                                                         |
|                                                                             |
|               2                                                  2          |
|o3 = ideal (- b  + a*d, - b*c + a*e, - c*d + b*e, - b*c + a*e, - c  + a*f, - |
|     ------------------------------------------------------------------------|
|                                             2                               |
|     c*e + b*f, - c*d + b*e, - c*e + b*f, - e  + d*f)                        |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : G = gb(I, PairLimit=>5)                                                 |
|                                                                             |
|o4 = GroebnerBasis[status: PairLimit; all S-pairs handled up to degree 1]    |
|                                                                             |
|o4 : GroebnerBasis                                                           |
+-----------------------------------------------------------------------------+
|i5 : mingens G                                                               |
|                                                                             |
|o5 = | e2-df ce-bf cd-be |                                                   |
|                                                                             |
|             1      3                                                        |
|o5 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i6 : mingens I                                                               |
|                                                                             |
|o6 = | e2-df ce-bf cd-be c2-af bc-ae b2-ad |                                 |
|                                                                             |
|             1      6                                                        |
|o6 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * GroebnerBasis -- the class of all Gröbner bases
  * gb -- compute a Gröbner basis
  * genericSymmetricMatrix -- make a generic
    symmetric matrix
  * minors -- ideal generated by minors

Ways to use this method:
========================

  * mingens(GroebnerBasis) -- (partially
    constructed) minimal generator matrix

mingens(Module) -- minimal generator matrix
*******************************************

Synopsis
========

  * Function: mingens,
  * Usage:
        mingens I
  * Inputs:
      * I, or an ideal
  * Optional inputs,:
      * Strategy, => ..., default value null, a Strategy
        option value
  * Outputs:
      * a matrix, a matrix, whose columns generate I.

Description
===========

If I is homogeneous, then a matrix, whose columns minimally generate I, is
returned.
+-----------------------------------------------------+
|i1 : R = QQ[a..f]                                    |
|                                                     |
|o1 = R                                               |
|                                                     |
|o1 : PolynomialRing                                  |
+-----------------------------------------------------+
|i2 : I = ideal(a,b,c) * ideal(a,b,c)                 |
|                                                     |
|             2                  2                  2 |
|o2 = ideal (a , a*b, a*c, a*b, b , b*c, a*c, b*c, c )|
|                                                     |
|o2 : Ideal of R                                      |
+-----------------------------------------------------+
|i3 : mingens I                                       |
|                                                     |
|o3 = | c2 bc ac b2 ab a2 |                           |
|                                                     |
|             1      6                                |
|o3 : Matrix R  <-- R                                 |
+-----------------------------------------------------+
If I is not homogeneous, then an attempt is made to find a more efficient
generating matrix, one which is better than a Gröbner basis.  There is no
guarantee that the generating set is small, or that no subset also generates.
The only thing known is that the entries do generate the ideal.
+-----------------------------------------------------------------------------+
|i4 : J = ideal(a-1, b-2, c-3)                                                |
|                                                                             |
|o4 = ideal (a - 1, b - 2, c - 3)                                             |
|                                                                             |
|o4 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i5 : I = J*J                                                                 |
|                                                                             |
|             2                                                               |
|o5 = ideal (a  - 2a + 1, a*b - 2a - b + 2, a*c - 3a - c + 3, a*b - 2a - b +  |
|     ------------------------------------------------------------------------|
|         2                                                                   |
|     2, b  - 4b + 4, b*c - 3b - 2c + 6, a*c - 3a - c + 3, b*c - 3b - 2c + 6, |
|     ------------------------------------------------------------------------|
|      2                                                                      |
|     c  - 6c + 9)                                                            |
|                                                                             |
|o5 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i6 : mingens I                                                               |
|                                                                             |
|o6 = | c2-6c+9 bc-3b-2c+6 ac-3a-c+3 b2-4b+4 ab-2a-b+2 a2-2a+1 |              |
|                                                                             |
|             1      6                                                        |
|o6 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
Every module I in Macaulay2 is a submodule of a quotient of some ambient free
module F.  This routine returns a minimal, or improved generating set for the
same module I.  If you want to minimize the generators and the relations of a
subquotient module, use trim.  If you want a minimal presentation,
then use minimalPresentation.
+-----------------------------------------------------------------------------+
|i7 : M = matrix{{a^2*b*c-d*e*f,a^3*c-d^2*f,a*d*f-b*c*e-1}}                   |
|                                                                             |
|o7 = | a2bc-def a3c-d2f -bce+adf-1 |                                         |
|                                                                             |
|             1      3                                                        |
|o7 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i8 : I = kernel M                                                            |
|                                                                             |
|o8 = image {4} | -bce+adf-1 0          a3c-d2f   a4c-bcde-d   -a3ce+d2ef     |
|           {4} | 0          -bce+adf-1 -a2bc+def -a3bc+bce2+e a3df-de2f-a2   |
|           {3} | -a2bc+def  -a3c+d2f   0         -a2bcd+a3ce  -a5c+a2d2f     |
|                                                                             |
|                             3                                               |
|o8 : R-module, submodule of R                                                |
|-----------------------------------------------------------------------------|
|a4df-bd2ef-a3    -a5df+abd2ef+a4  -a5cf+abcdef+adf |                         |
|-a3bdf+bde2f+a2b a4bdf-abde2f-a3b a4bcf-abce2f-aef |                         |
|-a2bd2f+a3def    a3bd2f-a4def     a3bcdf-a4cef     |                         |
+-----------------------------------------------------------------------------+
|i9 : J = image mingens I                                                     |
|                                                                             |
|o9 = image {4} | bce-adf+1 0         a3c-d2f   |                             |
|           {4} | 0         bce-adf+1 -a2bc+def |                             |
|           {3} | a2bc-def  a3c-d2f   0         |                             |
|                                                                             |
|                             3                                               |
|o9 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+
|i10 : I == J                                                                 |
|                                                                             |
|o10 = true                                                                   |
+-----------------------------------------------------------------------------+
|i11 : trim I                                                                 |
|                                                                             |
|o11 = image {4} | bce-adf+1 0         a3c-d2f   |                            |
|            {4} | 0         bce-adf+1 -a2bc+def |                            |
|            {3} | a2bc-def  a3c-d2f   0         |                            |
|                                                                             |
|                              3                                              |
|o11 : R-module, submodule of R                                               |
+-----------------------------------------------------------------------------+

If the base ring is a polynomial ring (or quotient of one), then a Gröbner
basis computation is started, and continued until all generators have been
considered.

See also
========

  * trim -- minimize generators and relations
  * minimalPresentation -- compute a minimal
    presentation
  * kernel -- kernel of a ringmap, matrix, or chain complex
  * image -- image of a map

Ways to use this method:
========================

  * "mingens(Ideal)"
  * mingens(Module) -- minimal generator matrix
  * "mingens(MonomialIdeal)"

mingle -- mingle elements of several lists
******************************************

Synopsis
========

  * Usage:
        mingle(L)
  * Inputs:
      * L, a basic list, a list of lists L=\{L1, L2, ...,
        Ln\}
  * Outputs:
      * M, a list, a new list mingling the elements of all lists
        in L

Description
===========

The output list M takes the first element of each Li, i=1,...,n, followed by
the second element of Li, i=1,...,n, and so forth.

+------------------------------------------------------+
|i1 : mingle {{a1, a2, a3}, {b1, b2, b3}, {c1, c2, c3}}|
|                                                      |
|o1 = {a1, b1, c1, a2, b2, c2, a3, b3, c3}             |
|                                                      |
|o1 : List                                             |
+------------------------------------------------------+

The lists can have different lengths. After a list is exhausted, it will be
silently ignored.

+----------------------------------------------+
|i2 : mingle {{a1, a2, a3, a4}, {b1, b2}, {c1}}|
|                                              |
|o2 = {a1, b1, c1, a2, b2, a3, a4}             |
|                                              |
|o2 : List                                     |
+----------------------------------------------+

To transpose a nested list (thinking of it as a matrix), try using mingle with
pack.

+---------------------------------------------------------------+
|i3 : pack(3, mingle ((a1, a2, a3), (b1, b2, b3), (c1, c2, c3)))|
|                                                               |
|o3 = {{a1, b1, c1}, {a2, b2, c2}, {a3, b3, c3}}                |
|                                                               |
|o3 : List                                                      |
+---------------------------------------------------------------+

Notice from the previous example that mingle accepts sequences and other types
of BasicList,s as input, but the output will always be a
List.

Further examples:

+-----------------------------------------------------------------------------+
|i4 : concatenate mingle( {"a","b","c"} , {",",","} )                         |
|                                                                             |
|o4 = a,b,c                                                                   |
+-----------------------------------------------------------------------------+
|i5 : netList pack(3, mingle( (0..5), apply(6, i -> i^2), apply(6, i -> i^3)))|
|                                                                             |
|     +-+--+---+                                                              |
|o5 = |0|0 |0  |                                                              |
|     +-+--+---+                                                              |
|     |1|1 |1  |                                                              |
|     +-+--+---+                                                              |
|     |2|4 |8  |                                                              |
|     +-+--+---+                                                              |
|     |3|9 |27 |                                                              |
|     +-+--+---+                                                              |
|     |4|16|64 |                                                              |
|     +-+--+---+                                                              |
|     |5|25|125|                                                              |
|     +-+--+---+                                                              |
+-----------------------------------------------------------------------------+

See also
========

  * apply -- apply a function to each element
  * insert -- copy a list, inserting an element
  * join -- join lists, sequences, and iterable objects
  * pack -- pack elements of a list or string into several shorter
    lists or strings
  * sort -- sort a list or columns of a matrix
  * sublists -- process interspersed subsequences of a visible
    list
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use mingle:
===================

  * "mingle(BasicList)"

For the programmer
==================

The object mingle, is a compiled function.

minimal presentations and generators
************************************

prune, trim

MinimalGenerators -- whether to compute minimal generators and return a trimmed set of generators
*************************************************************************************************

Description
===========

The following returns two minimal generators (Serre's Theorem: a codim 2
Gorenstein ideal is a complete intersection.)

+-------------------------+
|i1 : S = ZZ/101[a,b]     |
|                         |
|o1 = S                   |
|                         |
|o1 : PolynomialRing      |
+-------------------------+
|i2 : i = ideal(a^4,b^4)  |
|                         |
|             4   4       |
|o2 = ideal (a , b )      |
|                         |
|o2 : Ideal of S          |
+-------------------------+
|i3 : quotient(i, a^3+b^3)|
|                         |
|                  3    3 |
|o3 = ideal (a*b, a  - b )|
|                         |
|o3 : Ideal of S          |
+-------------------------+

Without trimming we would get 4 generators instead.

+-----------------------------------------------------+
|i4 : quotient(i, a^3+b^3, MinimalGenerators => false)|
|                                                     |
|                  3    3                             |
|o4 = ideal (a*b, a  - b )                            |
|                                                     |
|o4 : Ideal of S                                      |
+-----------------------------------------------------+

Sometimes the extra time to find the minimal generators is too large. This
allows one to bypass this part of the computation.

+--------------------------------------------------------+
|i5 : needsPackage "Truncations"                         |
|                                                        |
|o5 = Truncations                                        |
|                                                        |
|o5 : Package                                            |
+--------------------------------------------------------+
|i6 : R = ZZ/101[x_0..x_4]                               |
|                                                        |
|o6 = R                                                  |
|                                                        |
|o6 : PolynomialRing                                     |
+--------------------------------------------------------+
|i7 : I = truncate(8, monomialCurveIdeal(R,{1,4,5,9}));  |
|                                                        |
|o7 : Ideal of R                                         |
+--------------------------------------------------------+
|i8 : time gens gb I;                                    |
| -- used 0.0255838s (cpu); 0.0255648s (thread); 0s (gc) |
|                                                        |
|             1      428                                 |
|o8 : Matrix R  <-- R                                    |
+--------------------------------------------------------+
|i9 : time J1 = saturate(I);                             |
| -- used 0.216168s (cpu); 0.146116s (thread); 0s (gc)   |
|                                                        |
|o9 : Ideal of R                                         |
+--------------------------------------------------------+
|i10 : time J = saturate(I, MinimalGenerators => false); |
| -- used 8.428e-05s (cpu); 8.4247e-05s (thread); 0s (gc)|
|                                                        |
|o10 : Ideal of R                                        |
+--------------------------------------------------------+
|i11 : numgens J                                         |
|                                                        |
|o11 = 7                                                 |
+--------------------------------------------------------+
|i12 : numgens J1                                        |
|                                                        |
|o12 = 7                                                 |
+--------------------------------------------------------+

See also
========

  * quotient(Ideal,Ideal) (Saturation), --
    ideal or submodule quotient
  * saturate(Ideal,Ideal) (Saturation) -- saturation of ideal
    or submodule
  * monomialCurveIdeal -- make the ideal of a
    monomial curve
  * truncate(ZZ,Ideal) (Truncations), --
    truncation of the graded ring, ideal or module at a specified degree or set
    of degrees

Functions with optional argument named MinimalGenerators:
=========================================================

  * adjoint(...,MinimalGenerators=>...) (missing documentation)
  * "associatedPrimes(...,MinimalGenerators=>...)" -- see
    associatedPrimes (PrimaryDecomposition), -- find
    associated primes
  * canonicalBundle(...,MinimalGenerators=>...) (missing documentation)
  * "compose(Module,Module,Module,MinimalGenerators=>...)" -- see
    compose, -- composition as a pairing on Hom-modules
  * "cotangentSheaf(...,MinimalGenerators=>...)" -- see
    cotangentSheaf(ProjectiveVariety) (Varieties),
    -- cotangent sheaf of a
    projective variety
  * dual(ChainComplex,MinimalGenerators=>...) (missing documentation)
  * dual(Matrix,MinimalGenerators=>...) (missing documentation)
  * dual(SheafMap,MinimalGenerators=>...) (missing documentation)
  * "End(...,MinimalGenerators=>...)" -- see End, -- module of
    endomorphisms
  * "Hom(...,MinimalGenerators=>...)" -- see Hom, -- module of
    homomorphisms
  * "homomorphism'(...,MinimalGenerators=>...)" -- see homomorphism',
    -- get the element of Hom from a homomorphism
  * "intersect(Ideal,Ideal,MinimalGenerators=>...)" -- see
    intersect(Ideal,Ideal), -- compute an
    intersection of a sequence of ideals or modules
  * "intersect(Module,Module,MinimalGenerators=>...)" -- see
    intersect(Ideal,Ideal), -- compute an
    intersection of a sequence of ideals or modules
  * "intersectInP(...,MinimalGenerators=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "decompose(Ideal,MinimalGenerators=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,MinimalGenerators=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "primaryDecomposition(...,MinimalGenerators=>...)" -- see
    primaryDecomposition (PrimaryDecomposition), --
    irredundant primary decomposition of an ideal
  * "quotient(...,MinimalGenerators=>...)" -- see
    quotient(Module,Module) (Saturation), --
    ideal or submodule quotient
  * "analyticSpread(...,MinimalGenerators=>...)" -- see
    reesIdeal(...,MinimalGenerators=>...) (ReesAlgebra),
    --
    Whether the saturation step returns minimal generators
  * "associatedGradedRing(...,MinimalGenerators=>...)" -- see
    reesIdeal(...,MinimalGenerators=>...) (ReesAlgebra),
    --
    Whether the saturation step returns minimal generators
  * "distinguished(...,MinimalGenerators=>...)" -- see
    reesIdeal(...,MinimalGenerators=>...) (ReesAlgebra),
    --
    Whether the saturation step returns minimal generators
  * "isLinearType(...,MinimalGenerators=>...)" -- see
    reesIdeal(...,MinimalGenerators=>...) (ReesAlgebra),
    --
    Whether the saturation step returns minimal generators
  * "isReduction(...,MinimalGenerators=>...)" -- see
    reesIdeal(...,MinimalGenerators=>...) (ReesAlgebra),
    --
    Whether the saturation step returns minimal generators
  * "minimalReduction(...,MinimalGenerators=>...)" -- see
    reesIdeal(...,MinimalGenerators=>...) (ReesAlgebra),
    --
    Whether the saturation step returns minimal generators
  * "multiplicity(...,MinimalGenerators=>...)" -- see
    reesIdeal(...,MinimalGenerators=>...) (ReesAlgebra),
    --
    Whether the saturation step returns minimal generators
  * "normalCone(Ideal,MinimalGenerators=>...)" -- see
    reesIdeal(...,MinimalGenerators=>...) (ReesAlgebra),
    --
    Whether the saturation step returns minimal generators
  * "normalCone(Ideal,RingElement,MinimalGenerators=>...)" -- see
    reesIdeal(...,MinimalGenerators=>...) (ReesAlgebra),
    --
    Whether the saturation step returns minimal generators
  * "reesAlgebra(...,MinimalGenerators=>...)" -- see
    reesIdeal(...,MinimalGenerators=>...) (ReesAlgebra),
    --
    Whether the saturation step returns minimal generators
  * reesIdeal(...,MinimalGenerators=>...) (ReesAlgebra),
    --
    Whether the saturation step returns minimal generators
  * "specialFiber(...,MinimalGenerators=>...)" -- see
    reesIdeal(...,MinimalGenerators=>...) (ReesAlgebra),
    --
    Whether the saturation step returns minimal generators
  * "specialFiberIdeal(...,MinimalGenerators=>...)" -- see
    reesIdeal(...,MinimalGenerators=>...) (ReesAlgebra),
    --
    Whether the saturation step returns minimal generators
  * "saturate(...,MinimalGenerators=>...)" -- see saturate (Saturation),
    -- saturation of ideal or submodule
  * sheafExt(ZZ,CoherentSheaf,CoherentSheaf,MinimalGenerators=>...) (missing
    documentation)
  * sheafExt(ZZ,CoherentSheaf,SheafOfRings,MinimalGenerators=>...) (missing
    documentation)
  * sheafExt(ZZ,SheafOfRings,CoherentSheaf,MinimalGenerators=>...) (missing
    documentation)
  * sheafExt(ZZ,SheafOfRings,SheafOfRings,MinimalGenerators=>...) (missing
    documentation)
  * sheafHom(...,MinimalGenerators=>...) (missing documentation)
  * "tangentSheaf(...,MinimalGenerators=>...)" -- see
    tangentSheaf(ProjectiveVariety) (Varieties),
    -- tangent sheaf of a
    projective variety
  * truncate(InfiniteNumber,Thing,MinimalGenerators=>...) (missing
    documentation)
  * truncate(List,Ideal,MinimalGenerators=>...) (missing documentation)
  * "truncate(List,Matrix,MinimalGenerators=>...)" -- see
    truncate(List,Matrix) (Truncations), --
    truncation of a map of free modules
  * "truncate(List,Module,MinimalGenerators=>...)" -- see
    truncate(List,Module) (Truncations), --
    truncation of the graded ring, ideal or module at a specified degree or set
    of degrees
  * truncate(List,Ring,MinimalGenerators=>...) (missing documentation)
  * truncate(ZZ,Ideal,MinimalGenerators=>...) (missing documentation)
  * truncate(ZZ,Matrix,MinimalGenerators=>...) (missing documentation)
  * truncate(ZZ,Module,MinimalGenerators=>...) (missing documentation)
  * truncate(ZZ,Ring,MinimalGenerators=>...) (missing documentation)

For the programmer
==================

The object MinimalGenerators, is a symbol.

minimalPresentation -- compute a minimal presentation
*****************************************************

See also
========

  * trim -- minimize generators and relations

Ways to use minimalPresentation:
================================

  * minimalPresentation(CoherentSheaf) (missing documentation)
  * minimalPresentation(Ideal), --
    compute a minimal presentation of the quotient ring defined by an ideal
  * minimalPresentation(Matrix), --
    minimally present source and target of a matrix
  * "minimalPresentation(ChainComplex)" -- see
    minimalPresentation(Module), -- minimal
    presentation of a module
  * "minimalPresentation(ChainComplexMap)" -- see
    minimalPresentation(Module), -- minimal
    presentation of a module
  * "minimalPresentation(GradedModule)" -- see
    minimalPresentation(Module), -- minimal
    presentation of a module
  * "minimalPresentation(GradedModuleMap)" -- see
    minimalPresentation(Module), -- minimal
    presentation of a module
  * minimalPresentation(Module), --
    minimal presentation of a module
  * minimalPresentation(Ring) -- compute
    a minimal presentation of a quotient ring
  * minimalPresentation(SheafMap) (missing documentation)
  * minimalPresentation(SheafOfRings) (missing documentation)

For the programmer
==================

The object minimalPresentation, is a method function with options.

minimalPresentation(Ideal) -- compute a minimal presentation of the quotient ring defined by an ideal
*****************************************************************************************************

Synopsis
========

  * Function: minimalPresentation,
  * Usage:
        J = minimalPresentation I
  * Inputs:
      * I, in a ring S
  * Optional inputs,:
      * Exclude, => ..., default value {},
        compute a minimal presentation of a quotient ring
  * Outputs:
      * J, an ideal,  in a new ring Q with S/I isomorphic to Q/J
  * Consequences:
      * minimalPresentation stores the isomorphism  from S/I to Q/J as
        I.cache.minimalPresentationMap , where I is the input ideal and the
        inverse of this map as I.cache.minimalPresentationMapInv

Description
===========

If the ideal I is homogeneous, then the ideal J, in a new ring Q is the
defining ideal for a minimal presentation of the ring S/I where S is the ring
of I. This is accomplished as follows. If a variable occurs as a term of a
generator of I and in no other terms of the same polynomial, then the variable
is replaced by the remaining terms and removed from the ring. A minimal
generating set for the resulting ideal is then computed. If I is not
homogeneous, then an attempt is made to improve the presentation of S/I.
+--------------------------------------------------------+
|i1 : C = ZZ/101[x,y,z,u,w];                             |
+--------------------------------------------------------+
|i2 : I = ideal(x-x^2-y,z+x*y,w^2-u^2);                  |
|                                                        |
|o2 : Ideal of C                                         |
+--------------------------------------------------------+
|i3 : minPres I                                          |
|                                                        |
|              2    2                                    |
|o3 = ideal(- u  + w )                                   |
|                                                        |
|               ZZ                                       |
|o3 : Ideal of ---[x, u, w]                              |
|              101                                       |
+--------------------------------------------------------+
|i4 : I.cache.minimalPresentationMap                     |
|                                                        |
|           ZZ                     2       3    2        |
|o4 = map (---[x, u, w], C, {x, - x  + x, x  - x , u, w})|
|          101                                           |
|                                                        |
|              ZZ                                        |
|o4 : RingMap ---[x, u, w] <-- C                         |
|             101                                        |
+--------------------------------------------------------+
|i5 : I.cache.minimalPresentationMapInv                  |
|                                                        |
|              ZZ                                        |
|o5 = map (C, ---[x, u, w], {x, u, w})                   |
|             101                                        |
|                                                        |
|                    ZZ                                  |
|o5 : RingMap C <-- ---[x, u, w]                         |
|                   101                                  |
+--------------------------------------------------------+
If the Exclude option is present, then those variables with the given indices
are not simplified away (remember that ring variable indices start at 0).
+-----------------------------------------+
|i6 : R = ZZ/101[x,y,z,u,w];              |
+-----------------------------------------+
|i7 : I = ideal(x-x^2-y,z+x*y,w^2-u^2);   |
|                                         |
|o7 : Ideal of R                          |
+-----------------------------------------+
|i8 : minimalPresentation(I, Exclude=>{1})|
|                                         |
|               2             2    2      |
|o8 = ideal (- x  + x - y, - u  + w )     |
|                                         |
|               ZZ                        |
|o8 : Ideal of ---[x..y, u, w]            |
|              101                        |
+-----------------------------------------+

See also
========

  * minimalPresentation(Ring) -- compute
    a minimal presentation of a quotient ring
  * trim(Ideal) -- minimize generators and relations

Ways to use this method:
========================

  * minimalPresentation(Ideal), --
    compute a minimal presentation of the quotient ring defined by an ideal

minimalPresentation(Matrix) -- minimally present source and target of a matrix
******************************************************************************

Synopsis
========

  * Function: minimalPresentation,
  * Usage:
        minimalPresentation f
  * Inputs:
      * f
  * Optional inputs,:
      * Exclude, => ..., default value {},
        compute a minimal presentation of a quotient ring
  * Outputs:
      * g, a matrix,

Description
===========

If the source and target of f are graded, then minimal presentations of the
source and target modules for f are computed using
minimalPresentation(Module), and g is the
matrix corresponding to f with source and target the minimally presented source
and target. If either the source or target of f is not graded then an attempt
is made to improve their presentations and gis the matrix with resulting source
and target. An example follows.
+---------------------------------------------------------+
|i1 : R = ZZ/32003[a..d];                                 |
+---------------------------------------------------------+
|i2 : f = inducedMap(coker matrix {{a,1,b},{c,3,b+d}},R^2)|
|                                                         |
|o2 = | 1 -10668 |                                        |
|     | 0 0      |                                        |
|                                                         |
|o2 : Matrix                                              |
+---------------------------------------------------------+
|i3 : g = prune f                                         |
|                                                         |
|o3 = | -3 1 |                                            |
|                                                         |
|o3 : Matrix                                              |
+---------------------------------------------------------+
|i4 : source g                                            |
|                                                         |
|      2                                                  |
|o4 = R                                                   |
|                                                         |
|o4 : R-module, free                                      |
+---------------------------------------------------------+
|i5 : target g                                            |
|                                                         |
|o5 = cokernel | b+16001d a-10668c |                      |
|                                                         |
|                            1                            |
|o5 : R-module, quotient of R                             |
+---------------------------------------------------------+

This function does not remove elements from the base field from the matrix, but
rather minimally presents the source and target and gives the corresponding new
map. For example:

+----------------------------------+
|i6 : m = matrix{{a,1,b},{c,3,b+d}}|
|                                  |
|o6 = | a 1 b   |                  |
|     | c 3 b+d |                  |
|                                  |
|             2      3             |
|o6 : Matrix R  <-- R              |
+----------------------------------+
|i7 : prune m                      |
|                                  |
|o7 = | a 1 b   |                  |
|     | c 3 b+d |                  |
|                                  |
|             2      3             |
|o7 : Matrix R  <-- R              |
+----------------------------------+
Unlike above, nothing changes.

Caveat
======

Check out the example just above.

See also
========

  * minimalPresentation(Module), --
    minimal presentation of a module

Ways to use this method:
========================

  * minimalPresentation(Matrix), --
    minimally present source and target of a matrix

minimalPresentation(Module) -- minimal presentation of a module
***************************************************************

Synopsis
========

  * Function: minimalPresentation,
  * Usage:
        N = minimalPresentation M
  * Inputs:
      * M
  * Optional inputs,:
      * Exclude, => ..., default value {},
        compute a minimal presentation of a quotient ring
  * Outputs:
      * N, a module, isomorphic to M
  * Consequences:
      * The isomorphism from N to M as g = N.cache.pruningMap unless
        M.cache.pruningMap already exists, in which case N is the same as M.
        The inverse isomorphism can be obtained as g^-1

Description
===========

If the Module M is graded then the module N is a minimal presentation of M.  If
not, then an attempt is made to improve the presentation of M.  An example
follows.
+--------------------------------------------+
|i1 : R = ZZ/32003[a..d];                    |
+--------------------------------------------+
|i2 : M = coker matrix {{a,1,b},{c,3,b+d}}   |
|                                            |
|o2 = cokernel | a 1 b   |                   |
|              | c 3 b+d |                   |
|                                            |
|                            2               |
|o2 : R-module, quotient of R                |
+--------------------------------------------+
|i3 : N = minimalPresentation M              |
|                                            |
|o3 = cokernel | b+16001d a-10668c |         |
|                                            |
|                            1               |
|o3 : R-module, quotient of R                |
+--------------------------------------------+
|i4 : peek N.cache                           |
|                                            |
|o4 = CacheTable{cache => MutableHashTable{}}|
|                pruningMap => | -10668 |    |
|                              | 0      |    |
+--------------------------------------------+
|i5 : g = N.cache.pruningMap                 |
|                                            |
|o5 = | -10668 |                             |
|     | 0      |                             |
|                                            |
|o5 : Matrix M <-- N                         |
+--------------------------------------------+
|i6 : g^-1                                   |
|                                            |
|o6 = | -3 1 |                               |
|                                            |
|o6 : Matrix N <-- M                         |
+--------------------------------------------+

See also
========

  * minimalPresentation(Matrix), --
    minimally present source and target of a matrix
  * trim(Module) -- minimize generators and relations
  * mingens(Module) -- minimal generator matrix

Ways to use this method:
========================

  * "minimalPresentation(ChainComplex)"
  * "minimalPresentation(ChainComplexMap)"
  * "minimalPresentation(GradedModule)"
  * "minimalPresentation(GradedModuleMap)"
  * minimalPresentation(Module), --
    minimal presentation of a module

minimalPresentation(Ring) -- compute a minimal presentation of a quotient ring
******************************************************************************

Synopsis
========

  * Function: minimalPresentation,
  * Usage:
        S = minimalPresentation R
        S = prune R
  * Inputs:
      * R, a quotient ring
  * Optional inputs,:
      * Exclude => ..., default value {}
  * Outputs:
      * S, a quotient ring, minimally presented if R is homogeneous, isomorphic
        to R
  * Consequences:
      * the isomorphism from R to S is stored as R.minimalPresentationMap and
        the inverse of this map is stored as R.minimalPresentationMapInv

Description
===========

The computation is accomplished by considering the relations of R. If a
variable occurs as a term of a relation of R and in no other terms of the same
polynomial, then  the variable is replaced by the remaining terms and removed
from the ring.  A minimal generating set for the resulting defining ideal is
then computed and the new quotient ring is returned. If R is not homogeneous,
then an attempt is made to improve the presentation.
+--------------------------------------------------------+
|i1 : R = ZZ/101[x,y,z,u,w]/ideal(x-x^2-y,z+x*y,w^2-u^2);|
+--------------------------------------------------------+
|i2 : minimalPresentation(R)                             |
|                                                        |
|      ZZ                                                |
|     ---[x, u, w]                                       |
|     101                                                |
|o2 = ------------                                       |
|          2    2                                        |
|       - u  + w                                         |
|                                                        |
|o2 : QuotientRing                                       |
+--------------------------------------------------------+
|i3 : R.minimalPresentationMap                           |
|                                                        |
|           ZZ                                           |
|          ---[x, u, w]                                  |
|          101                     2       3    2        |
|o3 = map (------------, R, {x, - x  + x, x  - x , u, w})|
|               2    2                                   |
|            - u  + w                                    |
|                                                        |
|              ZZ                                        |
|             ---[x, u, w]                               |
|             101                                        |
|o3 : RingMap ------------ <-- R                         |
|                  2    2                                |
|               - u  + w                                 |
+--------------------------------------------------------+
|i4 : R.minimalPresentationMapInv                        |
|                                                        |
|              ZZ                                        |
|             ---[x, u, w]                               |
|             101                                        |
|o4 = map (R, ------------, {x, u, w})                   |
|                  2    2                                |
|               - u  + w                                 |
|                                                        |
|                    ZZ                                  |
|                   ---[x, u, w]                         |
|                   101                                  |
|o4 : RingMap R <-- ------------                         |
|                        2    2                          |
|                     - u  + w                           |
+--------------------------------------------------------+
If the Exclude option is present, then those variables with the given indices
are not simplified away (remember that ring variable indices start at 0).
+--------------------------------------------------------+
|i5 : R = ZZ/101[x,y,z,u,w]/ideal(x-x^2-y,z+x*y,w^2-u^2);|
+--------------------------------------------------------+
|i6 : minimalPresentation(R, Exclude=>{1})               |
|                                                        |
|           ZZ                                           |
|          ---[x..y, u, w]                               |
|          101                                           |
|o6 = -------------------------                          |
|         2             2    2                           |
|     (- x  + x - y, - u  + w )                          |
|                                                        |
|o6 : QuotientRing                                       |
+--------------------------------------------------------+

See also
========

  * minimalPresentation(Ideal), --
    compute a minimal presentation of the quotient ring defined by an ideal
  * prune(Ideal) -- compute a minimal
    presentation of the quotient ring defined by an ideal
  * trim(Ring) -- minimize generators and relations
  * trim(QuotientRing) -- minimize generators and relations

Ways to use this method:
========================

  * minimalPresentation(Ring) -- compute
    a minimal presentation of a quotient ring

minimizeFilename -- minimize a file name
****************************************

Synopsis
========

  * Usage:
        minimizeFilename fn
  * Inputs:
      * fn, a path to a file
  * Outputs:
      * a minimized path, equivalent to fn

Description
===========

+------------------------------------------+
|i1 : minimizeFilename "a/b/c/../d"        |
|                                          |
|o1 = a/b/d                                |
+------------------------------------------+
|i2 : minimizeFilename "../../../../../../"|
|                                          |
|o2 = ../../../../../../                   |
+------------------------------------------+

Paths of the form foo/x/../bar, are shortened to foo/bar without checking the
file system to see whether x is a symbolic link.  For the other behavior, see
realpath.

See also
========

  * File -- the class of all files
  * relativizeFilename -- relativize a file name
  * baseFilename -- the base part of a filename or path
  * toAbsolutePath -- the absolute path version of a
    file name
  * searchPath -- search a path for a
    file
  * path -- list of directories to look in

For the programmer
==================

The object minimizeFilename, is a compiled function.

MinimumVersion -- the minimum required version of a program
***********************************************************

Functions with optional argument named MinimumVersion:
======================================================

  * "findProgram(...,MinimumVersion=>...)" -- see findProgram,
    -- load external program

For the programmer
==================

The object MinimumVersion, is a symbol.

minors(...,Strategy=>...) -- choose between Bareiss, Cofactor and Dynamic algorithms
************************************************************************************

Synopsis
========

  * Usage:
        minors(M, Strategy => s)
  * Inputs:
      * M, a matrix,
      * s, a symbol, either Bareiss, Cofactor, or Dynamic
  * Consequences:
      * If s is Bareiss, then the Bareiss algorithm is used; if
        s is Cofactor, then cofactor expansion is used; if s
        is Dynamic, then a dynamic programming algorithm is
        used.

Description
===========

The ring, of M determines the default strategy.  If the ring is a
polynomial ring, or a field (as identified by
isField) then the Bareiss, algorithm is used.  If the
ring is a quotient ring, (which has not been declared a
field by toField), then the Cofactor,
algorithm is used.The Dynamic, algorithm implements a variant of
cofactor expansion that caches intermediate results. This strategy introduces
some memory overhead, but can be faster than Cofactor,
especially with sparse matrices of low degree.

Further information
===================

  * Default value: null
  * Function: minors, -- ideal generated by
    minors
  * Option key: Strategy, -- an optional argument

Caveat
======

The Bareiss, algorithm returns a ring element that may differ
from the actual determinant by a zero divisor in the ring.  Thus, an incorrect
answer may be computed if the ring contains zero divisors.

See also
========

  * determinant -- determinant of a matrix
  * exteriorPower -- exterior power

Functions with optional argument named Strategy:
================================================

  * "addHook(...,Strategy=>...)" -- see addHook, -- add a hook
    function to an object for later processing
  * adjoint(...,Strategy=>...) (missing documentation)
  * "annihilator(...,Strategy=>...)" -- see annihilator (Saturation),
    -- the annihilator ideal
  * "associatedPrimes(...,Strategy=>...)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "basis(...,Strategy=>...)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * canonicalBundle(...,Strategy=>...) (missing documentation)
  * "mingens(...,Strategy=>...)" -- see Complement, -- a
    Strategy option value
  * "trim(...,Strategy=>...)" -- see Complement, -- a
    Strategy option value
  * "compose(Module,Module,Module,Strategy=>...)" -- see compose,
    -- composition as a pairing on Hom-modules
  * cotangentSheaf(...,Strategy=>...) (missing documentation)
  * determinant(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * dual(ChainComplex,Strategy=>...) (missing documentation)
  * dual(Matrix,Strategy=>...) (missing documentation)
  * "dual(MonomialIdeal,List,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...),
  * "dual(MonomialIdeal,RingElement,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...),
  * dual(MonomialIdeal,Strategy=>...)
  * dual(SheafMap,Strategy=>...) (missing documentation)
  * "End(...,Strategy=>...)" -- see End, -- module of endomorphisms
  * exteriorPower(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * "gb(...,Strategy=>...)" -- see gb, -- compute a Gröbner basis
  * gcdLLL(...,Strategy=>...) (missing documentation)
  * "GF(...,Strategy=>...)" -- see GF, -- make a finite field
  * "groebnerBasis(...,Strategy=>...)" -- see groebnerBasis,
    -- Gröbner basis, as a matrix
  * hermite(...,Strategy=>...) (missing documentation)
  * "Hom(...,Strategy=>...)" -- see Hom, -- module of homomorphisms
  * "homomorphism'(...,Strategy=>...)" -- see homomorphism',
    -- get the element of Hom from a homomorphism
  * "hooks(...,Strategy=>...)" -- see hooks, -- list hooks
    attached to a key
  * "idealizer(...,Strategy=>...)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * integralClosure(...,Strategy=>...) (IntegralClosure),
    --
    control the algorithm used
  * "intersect(Ideal,Ideal,Strategy=>...)" -- see intersect(Ideal,Ideal),
    -- compute an intersection of a sequence of
    ideals or modules
  * "intersect(Module,Module,Strategy=>...)" -- see
    intersect(Ideal,Ideal), -- compute an
    intersection of a sequence of ideals or modules
  * "intersectInP(...,Strategy=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "isPrimary(...,Strategy=>...)" -- see isPrimary (PrimaryDecomposition),
    -- determine whether a submodule is
    primary
  * "isPrime(Ideal,Strategy=>...)" -- see isPrime(Ideal) (MinimalPrimes),
    -- whether an ideal is prime
  * LLL(...,Strategy=>...) (LLLBases)
    -- choose among
    different algorithms
  * "localize(...,Strategy=>...)" -- see localize (PrimaryDecomposition),
    -- localize an ideal at a prime ideal
  * "match(...,Strategy=>...)" -- see match, -- regular expression
    matching
  * "decompose(Ideal,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * minors(...,Strategy=>...)
    -- choose between Bareiss,
    Cofactor and Dynamic algorithms
  * "parallelApply(...,Strategy=>...)" -- see parallelApply,
    -- apply a function to each element in parallel
  * "primaryComponent(...,Strategy=>...)" -- see primaryComponent (PrimaryDecomposition),
    -- find a primary component
    corresponding to an associated prime
  * pushForward(...,Strategy=>...) (missing documentation)
  * quotient(...,Strategy=>...) (Saturation)
  * "radical(...,Strategy=>...)" -- see radical (MinimalPrimes),
    -- the radical of an ideal
  * "radicalContainment(...,Strategy=>...)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * "analyticSpread(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "associatedGradedRing(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "distinguished(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isLinearType(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isReduction(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "minimalReduction(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "multiplicity(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(Ideal,RingElement,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(Ideal,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "reesAlgebra(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * reesIdeal(...,Strategy=>...) (ReesAlgebra)
    -- Choose a
    strategy for the saturation step
  * "specialFiber(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "specialFiberIdeal(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "regSeqInIdeal(...,Strategy=>...)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * resolution(...,Strategy=>...)
  * saturate(...,Strategy=>...) (Saturation)
  * sheafHom(...,Strategy=>...) (missing documentation)
  * "primaryDecomposition(...,Strategy=>...)" -- see strategies for computing primary decomposition (PrimaryDecomposition),
  * "syz(...,Strategy=>...)" -- see syz(Matrix), --
    compute the syzygy matrix
  * "tangentCone(...,Strategy=>...)" -- see tangentCone(Ideal) (TangentCone),
  * tangentSheaf(...,Strategy=>...) (missing documentation)

minors(ZZ,Matrix) -- ideal generated by minors
**********************************************

Synopsis
========

  * Function: minors,
  * Usage:
        minors(n,M)
  * Inputs:
      * n, an integer, order of the minor
      * M, a matrix, a map between free modules
  * Optional inputs,:
      * First => a list, default value null, if given, should be a
        list of two integer lists, which will be the first minor computed
      * Limit => an integer, default value infinity, the maximum
        number of minors to find
      * Strategy, => ...,
        default value null, choose between Bareiss, Cofactor and Dynamic
        algorithms
  * Outputs:
      * the ideal generated by the n by n minors of the matrix M

Description
===========

Minors are generated in the same order as that used by subsets(ZZ,ZZ).
+--------------------------------------------------+
|i1 : R = ZZ[a..f];                                |
+--------------------------------------------------+
|i2 : M = matrix{{a,b,c},{d,e,f}}                  |
|                                                  |
|o2 = | a b c |                                    |
|     | d e f |                                    |
|                                                  |
|             2      3                             |
|o2 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i3 : minors(2,M)                                  |
|                                                  |
|o3 = ideal (- b*d + a*e, - c*d + a*f, - c*e + b*f)|
|                                                  |
|o3 : Ideal of R                                   |
+--------------------------------------------------+
|i4 : minors(2,M,Limit=>1)                         |
|                                                  |
|o4 = ideal(- b*d + a*e)                           |
|                                                  |
|o4 : Ideal of R                                   |
+--------------------------------------------------+

When n is negative, the unit ideal is returned, to preserve the expected
ordering among the resulting ideals.

+-----------------------------+
|i5 : minors(1,M)             |
|                             |
|o5 = ideal (a, d, b, e, c, f)|
|                             |
|o5 : Ideal of R              |
+-----------------------------+
|i6 : minors(0,M)             |
|                             |
|o6 = ideal 1                 |
|                             |
|o6 : Ideal of R              |
+-----------------------------+
|i7 : minors(-1,M)            |
|                             |
|o7 = ideal 1                 |
|                             |
|o7 : Ideal of R              |
+-----------------------------+

See also
========

  * exteriorPower -- exterior power
  * determinant -- determinant of a matrix

Ways to use this method:
========================

  * minors(ZZ,Matrix) -- ideal generated by
    minors

minPosition -- position of the smallest element
***********************************************

Synopsis
========

  * Usage:
        minPosition L
  * Inputs:
      * L, a basic list,
  * Outputs:
      * i, an integer, the index of the smallest element in the list
        L

Description
===========

If the smallest element occurs more than once, the index of its first
occurrence is used.

+--------------------------------+
|i1 : minPosition {2, 1, 6, 4, 1}|
|                                |
|o1 = 1                          |
+--------------------------------+

If L contains elements in a polynomial ring, the MonomialOrder,
of the ring is used for comparisons.

+-------------------------------------------------+
|i2 : R1 = QQ[x, y, z, MonomialOrder => Lex];     |
+-------------------------------------------------+
|i3 : minPosition {x*y^2, x*y^2 + z^2, y^4, y*z^5}|
|                                                 |
|o3 = 3                                           |
+-------------------------------------------------+
|i4 : R2 = QQ[x, y, z, MonomialOrder => GRevLex]; |
+-------------------------------------------------+
|i5 : minPosition (x*y^2, x*y^2 + z^2, y^4, y*z^5)|
|                                                 |
|o5 = 0                                           |
+-------------------------------------------------+

More generally, the order of the elements is determined using the ?,
operator.

See also
========

  * maxPosition -- position of the largest element
  * max -- yields the maximum element in a list or sequence
  * min -- yields the minimum element in a list or sequence
  * sort -- sort a list or columns of a matrix
  * position -- the first element of a list satisfying a
    condition
  * positions -- which elements of a list satisfy a condition
  * ? -- comparison operator

Ways to use minPosition:
========================

  * "minPosition(BasicList)"

For the programmer
==================

The object minPosition, is a method function with a single argument.

Minus -- the class of all minus expressions
*******************************************

Description
===========

Minus is a type of Expression, representing negation.

This is a unary operator.

For the programmer
==================

The object Minus, is a wrapper type, with
ancestor classes Expression, < BasicList <
Thing.

minus -- additive inverse
*************************

Synopsis
========

  * Usage:
        minus(x)

Description
===========

minus(x) yields -x.

See also difference.

For the programmer
==================

The object minus, is a compiled function.

mod -- reduce modulo an integer
*******************************

Synopsis
========

  * Usage:
        mod(i,n)
  * Inputs:
      * i, an integer,
      * n, an integer,
  * Outputs:
      * an integer, the integer i modulo n, as an element of ZZ/n.

See also
========

  * ZZ % ZZ -- a binary operator, usually used for remainder and
    reduction

For the programmer
==================

The object mod, is a function closure.

Module -- the class of all modules
**********************************

Description
===========

See modules, for an overview of modules in Macaulay2.  See
modules in Macaulay2, for a tutorial overview of modules.

Modules in Macaulay2 are implemented as subquotient modules.
Submodules and quotients of free modules are perhaps the most common
and important modules, and subquotients form the smallest class of modules that
naturally includes these cases.

Common ways to make a module:
  * Ring ^ ZZ -- make a free module
  * Ring ^ List -- make a free module
  * cokernel(Matrix) -- cokernel of a map of modules, graded
    modules, or chaincomplexes
  * image(Matrix) -- image of a map
  * kernel(Matrix) -- kernel of a matrix
Common ways to get information about modules:
  * ring Module
  * numgens(Module) -- number of generators of a
    module
  * degrees(Module) -- degrees of generators
  * generators(Module) -- the generator matrix
    of a module
  * relations(Module) -- the defining relations
  * isFreeModule -- whether something is a free module
  * isHomogeneous(Module) -- whether something is
    homogeneous (graded)
Numerical information about a module:
  * codim(Module) -- codimension of the support of a
    module
  * dim(Module) -- compute the Krull dimension
  * rank(Module) -- compute the rank
Submodules, quotients, and subquotient modules:
  * ambient(Module) -- ambient free module
  * cover(Module) -- get the covering free module
  * super(Module) -- get the ambient module
  * Module / Module -- quotient module
  * subquotient(Matrix,Matrix) -- make a subquotient module
  * isSubset(Module,Module) -- whether
    one object is a subset of another
Common operations on modules:
  * Module + Module -- sum of submodules
  * Module == Module (missing documentation)
  * Module ++ Module -- direct sum of modules
  * Module ^ List -- projection onto summand
  * Module ** Module -- tensor product of
    modules
  * Module ^** ZZ -- tensor power
  * Module _ List -- map from free module to some
    generators
Minimalization:
  * mingens(Module) -- minimal generator matrix
  * trim(Module) -- minimize generators and relations
  * minimalPresentation(Module), --
    minimal presentation of a module
Graded modules:
  * basis -- basis or generating set of all or part of a ring,
    ideal or module
  * truncate(ZZ,Module) (Truncations), --
    truncation of the graded ring, ideal or module at a specified degree or set
    of degrees
  * degree(Module)
  * genera(Module) (Varieties)
  * hilbertSeries(Module) -- compute the
    Hilbert series of the module
  * hilbertFunction(ZZ,Module) -- the Hilbert function
  * poincare(Module) -- assemble degrees of a ring, module, or
    ideal into a polynomial
  * regularity(Module) -- compute the Castelnuovo-Mumford
    regularity
Annihilators, quotients and Gröbner bases:
  * gb(Module) -- compute a Gröbner basis
  * Ideal _colon_ Ideal (Saturation), --
    ideal or submodule quotient
  * annihilator(Module) (Saturation) -- the annihilator
    ideal
  * saturate(Module,Ideal) (Saturation) -- saturation of ideal
    or submodule
Common homological computations:
  * resolution(Module) -- compute a free
    resolution of a module
  * pdim(Module) -- calculate the projective dimension
    of a module
  * Hom -- module of homomorphisms
  * homomorphism(Matrix) -- get the homomorphism from
    element of Hom
  * Ext^ZZ(Module,Module) -- Ext module
  * Tor_ZZ(Module,Module) -- compute a
    Tor module
  * HH^ZZ Module -- local cohomology of a module
  * homology(Matrix,Matrix) -- homology
    of a pair of maps
  * fittingIdeal(ZZ,Module) -- Fitting ideal of a module
Multilinear algebra:
  * exteriorPower(ZZ,Module) -- exterior
    power of a module

Functions and methods returning a module:
=========================================

  * "Ideal * Module" -- see *, -- a binary operator, usually used
    for multiplication
  * "RingElement * Module" -- see *, -- a binary operator, usually
    used for multiplication
  * ambient(Module) -- ambient free module
  * ChainComplex ^ ZZ -- access member, cohomological
    degree
  * ChainComplex _ ZZ -- component
  * "GradedModule _ ZZ" -- see ChainComplex _ ZZ, --
    component
  * "coimage(Matrix)" -- see coimage, -- coimage of a map
  * "cokernel(Matrix)" -- see cokernel, -- cokernel of a map of
    modules, graded modules, or chaincomplexes
  * "cokernel(RingElement)" -- see cokernel, -- cokernel of a
    map of modules, graded modules, or chaincomplexes
  * "comodule(Ideal)" -- see comodule, -- submodule to quotient
    module
  * "comodule(Module)" -- see comodule, -- submodule to
    quotient module
  * "quotient(Ideal)" -- see comodule, -- submodule to quotient
    module
  * "quotient(Module)" -- see comodule, -- submodule to
    quotient module
  * cover(Module) -- get the covering free module
  * dual(Module) -- dual module
  * "Ext(Ideal,Ideal)" -- see Ext(Module,Module),
    -- total Ext module
  * "Ext(Ideal,Module)" -- see Ext(Module,Module),
    -- total Ext module
  * "Ext(Ideal,Ring)" -- see Ext(Module,Module),
    -- total Ext module
  * "Ext(Module,Ideal)" -- see Ext(Module,Module),
    -- total Ext module
  * Ext(Module,Module) -- total Ext module
  * "Ext(Module,Ring)" -- see Ext(Module,Module),
    -- total Ext module
  * Ext(Ring,Ideal) (missing documentation)
  * Ext(Ring,Module) (missing documentation)
  * Ext(Ring,Ring) (missing documentation)
  * Ext^ZZ(CoherentSheaf,CoherentSheaf) (Varieties)
    -- global Ext
  * "Ext^ZZ(CoherentSheaf,SheafOfRings)" -- see
    Ext^ZZ(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Ext
  * "Ext^ZZ(SheafOfRings,CoherentSheaf)" -- see
    Ext^ZZ(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Ext
  * "Ext^ZZ(SheafOfRings,SheafOfRings)" -- see
    Ext^ZZ(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Ext
  * Ext^ZZ(CoherentSheaf,SumOfTwists) (Varieties)
    -- global Ext
  * "Ext^ZZ(SheafOfRings,SumOfTwists)" -- see
    Ext^ZZ(CoherentSheaf,SumOfTwists) (Varieties),
    -- global Ext
  * "Ext^ZZ(Ideal,Ideal)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * "Ext^ZZ(Ideal,Module)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * "Ext^ZZ(Ideal,Ring)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * "Ext^ZZ(Module,Ideal)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * Ext^ZZ(Module,Module) -- Ext module
  * "Ext^ZZ(Module,Ring)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * Ext^ZZ(Ring,Ideal) (missing documentation)
  * Ext^ZZ(Ring,Module) (missing documentation)
  * Ext^ZZ(Ring,Ring) (missing documentation)
  * exteriorPower(ZZ,Module) -- exterior
    power of a module
  * HH^ZZ ChainComplex -- cohomology of a chain
    complex
  * HH^ZZ Module -- local cohomology of a module
  * HH^ZZ SheafOfRings (Varieties) -- cohomology of a
    sheaf of rings on a projective variety
  * HH^ZZ SumOfTwists (Varieties) -- coherent sheaf
    cohomology module
  * HH^ZZ(AffineVariety,CoherentSheaf) (missing documentation)
  * "HH^ZZ CoherentSheaf" -- see HH^ZZ(ProjectiveVariety,CoherentSheaf) (Varieties),
    -- cohomology of a
    coherent sheaf on a projective variety
  * HH^ZZ(ProjectiveVariety,CoherentSheaf) (Varieties)
    -- cohomology of a
    coherent sheaf on a projective variety
  * HH^ZZ(ProjectiveVariety,SumOfTwists) (missing documentation)
  * HH^ZZ(Variety,SheafOfRings) (missing documentation)
  * HH_ZZ ChainComplex -- homology of a chain
    complex
  * "Hom(Ideal,Ideal)" -- see Hom, -- module of homomorphisms
  * "Hom(Ideal,Module)" -- see Hom, -- module of homomorphisms
  * "Hom(Ideal,Ring)" -- see Hom, -- module of homomorphisms
  * "Hom(Module,Ideal)" -- see Hom, -- module of homomorphisms
  * "Hom(Module,Module)" -- see Hom, -- module of homomorphisms
  * "Hom(Module,Ring)" -- see Hom, -- module of homomorphisms
  * "Hom(Ring,Ideal)" -- see Hom, -- module of homomorphisms
  * "Hom(Ring,Module)" -- see Hom, -- module of homomorphisms
  * "Hom(Ring,Ring)" -- see Hom, -- module of homomorphisms
  * Hom(CoherentSheaf,CoherentSheaf) (Varieties)
    -- global Hom
  * "Hom(CoherentSheaf,SheafOfRings)" -- see
    Hom(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Hom
  * "Hom(SheafOfRings,CoherentSheaf)" -- see
    Hom(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Hom
  * "Hom(SheafOfRings,SheafOfRings)" -- see
    Hom(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Hom
  * "homogenize(Module,RingElement)" -- see homogenize, --
    homogenize with respect to a variable
  * "homogenize(Module,RingElement,List)" -- see homogenize,
    -- homogenize with respect to a variable
  * homology(Matrix,Matrix) -- homology
    of a pair of maps
  * Ideal / Ideal -- quotient module
  * "image(Matrix)" -- see image, -- image of a map
  * "image(RingElement)" -- see image, -- image of a map
  * "intersect(Module)" -- see intersect(Ideal,Ideal),
    -- compute an intersection of a sequence of
    ideals or modules
  * "intersect(Module,Module)" -- see intersect(Ideal,Ideal),
    -- compute an intersection of a sequence of
    ideals or modules
  * kernel(Matrix) -- kernel of a matrix
  * "kernel(RingElement)" -- see kernel(Matrix), --
    kernel of a matrix
  * "kernelOfLocalization(Module,Ideal)" -- see kernelOfLocalization (PrimaryDecomposition),
    -- the kernel of the
    localization map
  * lift(Module,type of InexactNumber') (missing documentation)
  * lift(Module,type of Number) (missing documentation)
  * lift(Module,type of RingElement) (missing documentation)
  * minimalPresentation(Module), --
    minimal presentation of a module
  * "prune(Module)" -- see minimalPresentation(Module),
    -- minimal presentation of a module
  * Module * RingElement (missing documentation)
  * Module ** Ring -- tensor product
  * "Ring ** Module" -- see Module ** Ring, -- tensor
    product
  * Module + Module -- sum of submodules
  * Module ++ Module -- direct sum of modules
  * "Module / Ideal" -- see Module / Module, -- quotient
    module
  * "Module / List" -- see Module / Module, -- quotient
    module
  * Module / Module -- quotient module
  * "Module / RingElement" -- see Module / Module, --
    quotient module
  * "Module / Sequence" -- see Module / Module, --
    quotient module
  * "Module / Vector" -- see Module / Module, --
    quotient module
  * Module ^ ZZ -- direct sum
  * Module ^** ZZ -- tensor power
  * module(CoherentSheaf) (Varieties) -- get
    the module defining a coherent sheaf
  * module(Ideal) (missing documentation)
  * module(Ring) -- make or get a module
  * module(SheafOfRings) (Varieties)
  * pullback(Matrix,Matrix) (missing documentation)
  * pushForward(RingMap,Module)
  * pushout(Matrix,Matrix) (missing documentation)
  * "Module : Ideal" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "Module : RingElement" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotient(Module,Ideal)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotient(Module,RingElement)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "removeLowestDimension(Module)" -- see removeLowestDimension (PrimaryDecomposition),
    -- remove components of lowest
    dimension
  * Ring ^ List -- make a free module
  * "RingFamily ^ List" -- see Ring ^ List, -- make a free
    module
  * Ring ^ ZZ -- make a free module
  * "RingFamily ^ ZZ" -- see Ring ^ ZZ, -- make a free module
  * "RingMap Module" -- see RingMap RingElement, --
    apply a ring map
  * "saturate(Module)" -- see saturate (Saturation), --
    saturation of ideal or submodule
  * "saturate(Module,Ideal)" -- see saturate (Saturation), --
    saturation of ideal or submodule
  * "saturate(Module,RingElement)" -- see saturate (Saturation),
    -- saturation of ideal or submodule
  * "saturate(Vector)" -- see saturate (Saturation), --
    saturation of ideal or submodule
  * "saturate(Vector,Ideal)" -- see saturate (Saturation), --
    saturation of ideal or submodule
  * "saturate(Vector,RingElement)" -- see saturate (Saturation),
    -- saturation of ideal or submodule
  * subquotient -- make a subquotient module
  * "substitute(Module,List)" -- see substitute, --
    substituting values for variables
  * "substitute(Module,Matrix)" -- see substitute, --
    substituting values for variables
  * "substitute(Module,Ring)" -- see substitute, --
    substituting values for variables
  * "substitute(Module,RingFamily)" -- see substitute, --
    substituting values for variables
  * sum(ChainComplex) -- direct sum of the
    components of a chain complex
  * "super(Module)" -- see super, -- get the ambient module
  * "symmetricPower(ZZ,Module)" -- see symmetricPower, --
    symmetric power
  * "Module ** Module" -- see tensor(Module,Module),
    -- tensor product of modules
  * tensor(Module,Module) -- tensor product
    of modules
  * "RingMap ** Module" -- see tensor(RingMap,Matrix),
    -- tensor product via a ring map
  * "tensor(RingMap,Module)" -- see tensor(RingMap,Matrix),
    -- tensor product via a ring map
  * "topComponents(Module)" -- see topComponents (PrimaryDecomposition),
    -- compute top dimensional component
    of an ideal or module
  * topComponents(Module,ZZ) (missing documentation)
  * "Tor_ZZ(Ideal,Ideal)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * "Tor_ZZ(Ideal,Module)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * "Tor_ZZ(Ideal,Ring)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * "Tor_ZZ(Module,Ideal)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * Tor_ZZ(Module,Module) -- compute a
    Tor module
  * "Tor_ZZ(Module,Ring)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * Tor_ZZ(Ring,Ideal) (missing documentation)
  * Tor_ZZ(Ring,Module) (missing documentation)
  * Tor_ZZ(Ring,Ring) (missing documentation)
  * "trim(Module)" -- see trim, -- minimize generators and
    relations
  * truncate(List,Module) (Truncations), --
    truncation of the graded ring, ideal or module at a specified degree or set
    of degrees

Methods that use a module:
==========================

  * "adjoint'(Matrix,Module,Module)" -- see adjoint, -- the
    tensor-Hom adjunction maps
  * "adjoint(Matrix,Module,Module)" -- see adjoint, -- the
    tensor-Hom adjunction maps
  * "analyticSpread(Module)" -- see analyticSpread (ReesAlgebra),
    -- Compute the analytic spread of a module or
    ideal
  * "analyticSpread(Module,RingElement)" -- see analyticSpread (ReesAlgebra),
    -- Compute the analytic spread of a module or
    ideal
  * "annihilator(Module)" -- see annihilator (Saturation), --
    the annihilator ideal
  * "associatedPrimes(Module)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "basis(InfiniteNumber,InfiniteNumber,Module)" -- see basis, --
    basis or generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,List,Module)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,ZZ,Module)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,InfiniteNumber,Module)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,List,Module)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,Module)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(List,ZZ,Module)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(Module)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(ZZ,InfiniteNumber,Module)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(ZZ,List,Module)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(ZZ,Module)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(ZZ,ZZ,Module)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "betti(Module)" -- see betti, -- display or modify a Betti
    diagram
  * "ChainComplex ** Module" -- see ChainComplex ** ChainComplex,
    -- tensor product
  * "Module ** ChainComplex" -- see ChainComplex ** ChainComplex,
    -- tensor product
  * "Module ** ChainComplexMap" -- see ChainComplex ** ChainComplexMap,
    -- tensor product
  * "ChainComplexMap ** Module" -- see ChainComplexMap ** ChainComplex,
    -- tensor product
  * "checkDegrees(Module,Module)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * codim(Module) -- codimension of the support of a
    module
  * "components(Module)" -- see components, -- list the
    components of a direct sum
  * "compose(Module,Module,Module)" -- see compose, --
    composition as a pairing on Hom-modules
  * coverMap(Module) -- the surjective map from a
    free module to a module corresponding to the generators
  * degree(Module)
  * "degrees(Module)" -- see degrees(Ring), -- degrees
    of generators
  * "describe(Module)" -- see describe, -- real description
  * dim(Module) -- compute the Krull dimension
  * "directSum(Module)" -- see directSum, -- direct sum of
    modules or maps
  * euler(Module) (Varieties)
  * "eulers(Module)" -- see eulers(CoherentSheaf) (Varieties),
  * "expectedReesIdeal(Module)" -- see expectedReesIdeal (ReesAlgebra),
    -- symmetric algebra ideal plus jacobian
    dual
  * Ext^ZZ(Matrix,Module) -- map between
    Ext modules
  * Ext^ZZ(Module,Matrix) -- map between
    Ext modules
  * factor(Module) -- factor a ZZ-module
  * "fittingIdeal(ZZ,Module)" -- see fittingIdeal, --
    Fitting ideal of a module
  * "flip(Module,Module)" -- see flip, -- isomorphism map of
    commutativity of tensor product
  * "formation(Module)" -- see formation, -- recover the
    methods used to make a module
  * "gb(Module)" -- see gb, -- compute a Gröbner basis
  * "gbRemove(Module)" -- see gbRemove, -- remove Gröbner basis
  * "gbSnapshot(Module)" -- see gbSnapshot, -- the Gröbner
    basis matrix as so far computed
  * "genera(Module)" -- see genera(CoherentSheaf) (Varieties),
  * "generator(Module)" -- see generator, -- provide a single
    generator
  * "Module _ ZZ" -- see generators of ideals and modules,
  * generators(Module) -- the generator matrix
    of a module
  * "genus(Module)" -- see genus(CoherentSheaf) (Varieties),
  * "gradedModule(Module)" -- see gradedModule, -- make a
    graded module
  * GradedModule ** Module -- a binary
    operator, usually used for tensor product or Cartesian product
  * "Module ** GradedModule" -- see GradedModule ** Module,
    -- a binary operator, usually used for tensor product or
    Cartesian product
  * "groebnerBasis(Module)" -- see groebnerBasis, --
    Gröbner basis, as a matrix
  * "hilbertFunction(List,Module)" -- see hilbertFunction,
    -- the Hilbert function
  * "hilbertFunction(Module)" -- see hilbertFunction, --
    the Hilbert function
  * "hilbertFunction(ZZ,Module)" -- see hilbertFunction,
    -- the Hilbert function
  * hilbertPolynomial(Module) -- compute
    the Hilbert polynomial of the module
  * hilbertSeries(Module) -- compute the
    Hilbert series of the module
  * "Hom(ChainComplex,Module)" -- see Hom(Module,ChainComplex),
    -- the Hom functor
  * "Hom(ChainComplexMap,Module)" -- see Hom(Module,ChainComplex),
    -- the Hom functor
  * Hom(Module,ChainComplex) -- the Hom
    functor
  * "Hom(Module,ChainComplexMap)" -- see Hom(Module,ChainComplex),
    -- the Hom functor
  * "Hom(Matrix,Module)" -- see Hom(Module,Matrix),
    -- induced map on Hom
  * Hom(Module,Matrix) -- induced map on Hom
  * Ideal == Module (missing documentation)
  * ideal(Module) -- converts a module to an ideal
  * inducedMap(Module,Module), --
    compute the map induced by the identity
  * inducedMap(Module,Module,Matrix)
    -- compute the induced map
  * "inducedMap(Module,Nothing,Matrix)" -- see
    inducedMap(Module,Module,Matrix),
    -- compute the induced map
  * "inducedMap(Nothing,Module,Matrix)" -- see
    inducedMap(Module,Module,Matrix),
    -- compute the induced map
  * "inducesWellDefinedMap(Module,Module,Matrix)" -- see
    inducesWellDefinedMap, -- whether a map is well
    defined
  * "inducesWellDefinedMap(Module,Nothing,Matrix)" -- see
    inducesWellDefinedMap, -- whether a map is well
    defined
  * "inducesWellDefinedMap(Nothing,Module,Matrix)" -- see
    inducesWellDefinedMap, -- whether a map is well
    defined
  * installHilbertFunction(Module,RingElement) (missing documentation)
  * "isDirectSum(Module)" -- see isDirectSum, -- whether
    something is a direct sum
  * "isFreeModule(Module)" -- see isFreeModule, -- whether
    something is a free module
  * "isHomogeneous(Module)" -- see isHomogeneous, --
    whether something is homogeneous (graded)
  * "isIdeal(Module)" -- see isIdeal, -- whether something is an
    ideal
  * "isIsomorphic(Module,Module)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * "isLinearType(Module)" -- see isLinearType (ReesAlgebra),
    -- Determine whether module has linear type
  * "isLinearType(Module,RingElement)" -- see isLinearType (ReesAlgebra),
    -- Determine whether module has linear type
  * "isModule(Module)" -- see isModule, -- whether something is
    a module
  * "isMonomialIdeal(Module)" -- see isMonomialIdeal, --
    whether something is a monomial ideal
  * "isPrimary(Module,Module)" -- see isPrimary (PrimaryDecomposition),
    -- determine whether a submodule is
    primary
  * "isQuotientModule(Module)" -- see isQuotientModule,
    -- whether something is evidently a quotient of a free module
  * "isReduction(Module,Module)" -- see isReduction (ReesAlgebra),
    -- Determine whether an ideal is a reduction
  * "isReduction(Module,Module,RingElement)" -- see isReduction (ReesAlgebra),
    -- Determine whether an ideal is a reduction
  * "isSquareFree(Module)" -- see isSquareFree, -- whether
    something is square free monomial ideal
  * "isSubmodule(Module)" -- see isSubmodule, -- whether a
    module is evidently a submodule of a free module
  * isSubquotient(Module,Module), --
    check whether a module is a subquotient of another
  * "isSubset(Ideal,Module)" -- see isSubset(Module,Module),
    -- whether one object is a subset of another
  * "isSubset(Module,Ideal)" -- see isSubset(Module,Module),
    -- whether one object is a subset of another
  * isSubset(Module,Module) -- whether
    one object is a subset of another
  * "isSupportedInZeroLocus(Ideal,Module)" -- see isSupportedInZeroLocus (Saturation),
    -- whether support of a module is
    contained in the zero locus of the (irrelevant) ideal
  * length(Module) -- Computes the length of a
    module
  * lift(Module,type of InexactNumber) (missing documentation)
  * map(Module) -- identity map
  * map(Module,Module,Function), --
    create a matrix by specifying a function that gives each entry
  * map(Module,Module,List) -- create a
    matrix by giving a sparse or dense list of entries
  * map(Module,Module,Matrix), --
    create the matrix induced on generators by a given matrix
  * "map(Module,Module,Number)" -- see map(Module,Module,RingElement),
    -- construct the map induced by
    multiplication by a ring element on the generators
  * map(Module,Module,RingElement)
    -- construct the map induced by
    multiplication by a ring element on the generators
  * "map(Module,Module,ZZ)" -- see map(Module,Module,RingElement),
    -- construct the map induced by
    multiplication by a ring element on the generators
  * "map(Module,ZZ,ZZ)" -- see map(Module,Module,RingElement),
    -- construct the map induced by
    multiplication by a ring element on the generators
  * "map(Module,Module,RingMap,List)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * map(Module,Module,RingMap,Matrix)
    -- homomorphism of modules
    over different rings
  * "map(Module,Nothing,RingMap,List)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * "map(Module,Nothing,RingMap,Matrix)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * "map(Module,RingMap)" -- see map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * map(Module,Nothing,List) -- create
    a matrix by giving a doubly nested list of ring elements
  * map(Module,Nothing,Matrix), --
    recast a matrix to have a new target, and a free module as source
  * map(Module,ZZ,Function) -- create a
    matrix from a free module by specifying a function that gives each entry
  * map(Module,ZZ,List) -- create a matrix
    by giving a sparse or dense list of entries
  * "Matrix % Module" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * mingens(Module) -- minimal generator matrix
  * "minimalBetti(Module)" -- see minimalBetti, -- minimal
    betti numbers of (the minimal free resolution of) a homogeneous ideal or
    module
  * Module * ZZ (missing documentation)
  * "GradedModule ++ Module" -- see Module ++ Module,
    -- direct sum of modules
  * "Module ++ GradedModule" -- see Module ++ Module,
    -- direct sum of modules
  * Module == Ideal (missing documentation)
  * Module == Module (missing documentation)
  * Module == ZZ (missing documentation)
  * Module ? Module (missing documentation)
  * Module ^ Array -- projection onto summand
  * Module ^ List -- projection onto summand
  * Module _ Array -- inclusion from summand
  * Module _ List -- map from free module to some
    generators
  * Module _* (missing documentation)
  * Module Array -- make a chain complex from a module
  * module(Module) (missing documentation)
  * "monomialIdeal(Module)" -- see monomialIdeal(Ideal),
    -- monomial ideal of lead monomials of a Gröbner
    basis
  * "multidegree(Module)" -- see multidegree, -- multidegree
  * numgens(Module) -- number of generators of a
    module
  * pdim(Module) -- calculate the projective dimension
    of a module
  * "poincare(Module)" -- see poincare, -- assemble degrees of
    a ring, module, or ideal into a polynomial
  * "preimage(Matrix,Module)" -- see preimage, -- preimage of a
    map
  * presentation(Module) -- presentation of a
    module
  * primaryDecomposition(Module) (PrimaryDecomposition)
    -- irredundant
    primary decomposition of a module
  * "Module : Module" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * random(Module) -- get a random vector in the
    module
  * random(Module,Module) -- get a random
    map of module
  * "rank(Module)" -- see rank, -- compute the rank
  * "reesAlgebra(Module)" -- see reesAlgebra (ReesAlgebra),
    -- Compute the defining ideal of the Rees Algebra
  * "reesAlgebra(Module,RingElement)" -- see reesAlgebra (ReesAlgebra),
    -- Compute the defining ideal of the Rees Algebra
  * "reesIdeal(Module)" -- see reesIdeal (ReesAlgebra), --
    Compute the defining ideal of the Rees Algebra
  * "reesIdeal(Module,RingElement)" -- see reesIdeal (ReesAlgebra),
    -- Compute the defining ideal of the Rees Algebra
  * "regularity(Module)" -- see regularity, -- compute the
    Castelnuovo-Mumford regularity
  * "relations(Module)" -- see relations, -- the defining
    relations
  * "reshape(Module,Module,Matrix)" -- see reshape, -- reshape a
    matrix
  * resolution(Module) -- compute a free
    resolution of a module
  * "ring(Module)" -- see ring, -- get the associated ring of an
    object
  * "Ring / Module" -- see Ring / Ideal, -- make a quotient
    ring
  * schreyerOrder(Module) -- obtain Schreyer
    order information
  * "Module ~" -- see sheaf(Module) (Varieties), --
    make a coherent sheaf
  * sheaf(Module) (Varieties) -- make a coherent sheaf
  * sheaf(Variety,Module) (Varieties), --
    make a coherent sheaf
  * "specialFiber(Module)" -- see specialFiber (ReesAlgebra),
    -- Special fiber of a blowup
  * "specialFiber(Module,RingElement)" -- see specialFiber (ReesAlgebra),
    -- Special fiber of a blowup
  * "specialFiberIdeal(Module)" -- see specialFiberIdeal (ReesAlgebra),
    -- Special fiber of a blowup
  * "specialFiberIdeal(Module,RingElement)" -- see specialFiberIdeal (ReesAlgebra),
    -- Special fiber of a blowup
  * "subquotient(Module,Matrix,Matrix)" -- see subquotient,
    -- make a subquotient module
  * "subquotient(Module,Matrix,Nothing)" -- see subquotient,
    -- make a subquotient module
  * "subquotient(Module,Nothing,Matrix)" -- see subquotient,
    -- make a subquotient module
  * "subquotient(Module,Nothing,Nothing)" -- see subquotient,
    -- make a subquotient module
  * "substitute(Module,Option)" -- see substitute, --
    substituting values for variables
  * "symmetricAlgebra(Module)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricAlgebraIdeal(Module)" -- see symmetricAlgebraIdeal (ReesAlgebra),
    -- Ideal of the symmetric algebra of an
    ideal or module
  * "Matrix ** Module" -- see tensor(Matrix,Module),
    -- tensor product
  * "Module ** Matrix" -- see tensor(Matrix,Module),
    -- tensor product
  * tensor(Matrix,Module) -- tensor product
  * "tensor(Module,Matrix)" -- see tensor(Matrix,Module),
    -- tensor product
  * "tensorAssociativity(Module,Module,Module)" -- see
    tensorAssociativity, -- associativity isomorphisms for
    tensor products
  * Tor_ZZ(Matrix,Module) (missing documentation)
  * Tor_ZZ(Module,Matrix) (missing documentation)
  * "truncate(ZZ,Module)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * "vector(Module,List)" -- see vector, -- make a vector
  * "vector(Module,Matrix)" -- see vector, -- make a vector
  * "vector(Module,Number)" -- see vector, -- make a vector
  * "vector(Module,RingElement)" -- see vector, -- make a vector
  * "versalEmbedding(Module)" -- see versalEmbedding (ReesAlgebra),
    -- Compute a versal embedding
  * wedgeProduct(ZZ,ZZ,Module), --
    the exterior multiplication map
  * ZZ == Module (missing documentation)
  * ZZ _ Module -- integers or zero element

For the programmer
==================

The object Module, is a type, with ancestor classes
ImmutableType < HashTable <
Thing.

module -- make or get a module
******************************

Ways to use module:
===================

  * module(CoherentSheaf) (Varieties) -- get
    the module defining a coherent sheaf
  * module(Ideal) (missing documentation)
  * module(Module) (missing documentation)
  * module(Ring) -- make or get a module
  * module(SheafOfRings) (Varieties)
  * module(Vector) -- the module of a vector

For the programmer
==================

The object module, is a method function.

Module ** Ring -- tensor product
********************************

Synopsis
========

  * Operator: **,
  * Usage:
        M ** R
        R ** M
        tensor(M, R)
        tensor(R, M)
  * Inputs:
      * M, a module, or an ideal,
      * R, a ring,
  * Outputs:
      * a module, over $R$, obtained by forming the tensor
        product of the module $M$ with $R$

Description
===========

If the ring of $M$ is a base ring of $R$ then the matrix presenting the module
will be simply promoted (see promote). Otherwise, a ring map
from the ring of M to R will be constructed by examining the names of the
variables, as described in map(Ring,Ring).

+-------------------------------------+
|i1 : R = ZZ/101[x,y];                |
+-------------------------------------+
|i2 : M = coker vars R                |
|                                     |
|o2 = cokernel | x y |                |
|                                     |
|                            1        |
|o2 : R-module, quotient of R         |
+-------------------------------------+
|i3 : M ** R[t]                       |
|                                     |
|o3 = cokernel | x y |                |
|                                     |
|                                    1|
|o3 : R[t]-module, quotient of (R[t]) |
+-------------------------------------+

Ways to use this method:
========================

  * "Ideal ** Ring"
  * Module ** Ring -- tensor product
  * "Ring ** Ideal"
  * "Ring ** Module"

Module + Module -- sum of submodules
************************************

Synopsis
========

  * Operator: +,

Description
===========

M + N -- the sum of two submodules.

The two modules should be submodules of the same module.

Ways to use this method:
========================

  * Module + Module -- sum of submodules

Module ++ Module -- direct sum of modules
*****************************************

Synopsis
========

  * Operator: ++,

Description
===========

M++N -- computes the direct sum of two modules (or coherent sheaves).
+----------------------------------+
|i1 : R = ZZ/101[a..c];            |
+----------------------------------+
|i2 : image vars R ++ kernel vars R|
|                                  |
|o2 = image {0} | a b c 0  0  0  | |
|           {1} | 0 0 0 -b 0  -c | |
|           {1} | 0 0 0 a  -c 0  | |
|           {1} | 0 0 0 0  b  a  | |
|                                  |
|                             4    |
|o2 : R-module, submodule of R     |
+----------------------------------+

The projection and inclusion maps for direct sums can be obtained with the
following methods.

  * Module ^ Array -- projection onto summand
  * Module _ Array -- inclusion from summand

The components can be recovered later with components, or
with formation.

See also
========

  * directSum -- direct sum of modules or maps

Ways to use this method:
========================

  * "GradedModule ++ Module"
  * "Module ++ GradedModule"
  * Module ++ Module -- direct sum of modules

Module / Module -- quotient module
**********************************

Synopsis
========

  * Operator: /,
  * Usage:
        M/N
  * Inputs:
      * M
      * N, a module, an ideal, a list,
        a sequence, a ring element,
        or a vector,
  * Outputs:
      * a module, The quotient module M/N of M

Description
===========

If N is an ideal, ring element, or list or sequence of ring elements (in the
ring of M), then the quotient is by the submodule N*M of M.

If N is a submodule of M, or a list or sequence of submodules, or a vector,
then the quotient is by these elements or submodules.
+-----------------------------------------------------------------------------+
|i1 : R = ZZ/173[a..d]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : M = ker matrix{{a^3-a*c*d,a*b*c-b^3,a*b*d-b*c^2}}                       |
|                                                                             |
|o2 = image {3} | 0      b3-abc bc2-abd |                                     |
|           {3} | -c2+ad a3-acd 0       |                                     |
|           {3} | b2-ac  0      a3-acd  |                                     |
|                                                                             |
|                             3                                               |
|o2 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+
|i3 : M/a == M/(a*M)                                                          |
|                                                                             |
|o3 = true                                                                    |
+-----------------------------------------------------------------------------+
|i4 : M/M_0                                                                   |
|                                                                             |
|o4 = subquotient ({3} | 0      b3-abc bc2-abd |, {3} | 0      |)             |
|                  {3} | -c2+ad a3-acd 0       |  {3} | -c2+ad |              |
|                  {3} | b2-ac  0      a3-acd  |  {3} | b2-ac  |              |
|                                                                             |
|                               3                                             |
|o4 : R-module, subquotient of R                                              |
+-----------------------------------------------------------------------------+
|i5 : M/(R*M_0 + b*M)                                                         |
|                                                                             |
|o5 = subquotient ({3} | 0      b3-abc bc2-abd |, {3} | 0      0              |
|                  {3} | -c2+ad a3-acd 0       |  {3} | -c2+ad -bc2+abd       |
|                  {3} | b2-ac  0      a3-acd  |  {3} | b2-ac  b3-abc         |
|                                                                             |
|                               3                                             |
|o5 : R-module, subquotient of R                                              |
|-----------------------------------------------------------------------------|
|b4-ab2c  b2c2-ab2d |)                                                        |
|a3b-abcd 0         |                                                         |
|0        a3b-abcd  |                                                         |
+-----------------------------------------------------------------------------+
|i6 : M/(M_0,a*M_1+M_2)                                                       |
|                                                                             |
|o6 = subquotient ({3} | 0      b3-abc bc2-abd |, {3} | 0                     |
|                  {3} | -c2+ad a3-acd 0       |  {3} | -c2+ad                |
|                  {3} | b2-ac  0      a3-acd  |  {3} | b2-ac                 |
|                                                                             |
|                               3                                             |
|o6 : R-module, subquotient of R                                              |
|-----------------------------------------------------------------------------|
|ab3-a2bc+bc2-abd |)                                                          |
|a4-a2cd          |                                                           |
|a3-acd           |                                                           |
+-----------------------------------------------------------------------------+
|i7 : presentation oo                                                         |
|                                                                             |
|o7 = {5} | -1 0  -a3+acd |                                                   |
|     {6} | 0  -a -c2+ad  |                                                   |
|     {6} | 0  -1 b2-ac   |                                                   |
|                                                                             |
|             3      3                                                        |
|o7 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * subquotient modules -- the way Macaulay2
    represents modules
  * presentation -- presentation of a module or ring

Ways to use this method:
========================

  * "Module / Ideal"
  * "Module / List"
  * Module / Module -- quotient module
  * "Module / RingElement"
  * "Module / Sequence"
  * "Module / Vector"

Module ^ Array -- projection onto summand
*****************************************

Synopsis
========

  * Operator: ^,
  * Usage:
        M^[i,j,...,k]
  * Inputs:
      * M, or a chain complex,
      * [i,j,...,k], an array of indices
  * Outputs:
      * a matrix, or a chain complex map,

Description
===========

The module M should be a direct sum, and the result is the map obtained by
projection onto the sum of the components numbered or named i, j, ..., k.  Free
modules are regarded as direct sums of modules.

+-----------------------+
|i1 : M = ZZ^2 ++ ZZ^3  |
|                       |
|       5               |
|o1 = ZZ                |
|                       |
|o1 : ZZ-module, free   |
+-----------------------+
|i2 : M^[0]             |
|                       |
|o2 = | 1 0 0 0 0 |     |
|     | 0 1 0 0 0 |     |
|                       |
|              2       5|
|o2 : Matrix ZZ  <-- ZZ |
+-----------------------+
|i3 : M^[1]             |
|                       |
|o3 = | 0 0 1 0 0 |     |
|     | 0 0 0 1 0 |     |
|     | 0 0 0 0 1 |     |
|                       |
|              3       5|
|o3 : Matrix ZZ  <-- ZZ |
+-----------------------+
|i4 : M^[1,0]           |
|                       |
|o4 = | 0 0 1 0 0 |     |
|     | 0 0 0 1 0 |     |
|     | 0 0 0 0 1 |     |
|     | 1 0 0 0 0 |     |
|     | 0 1 0 0 0 |     |
|                       |
|              5       5|
|o4 : Matrix ZZ  <-- ZZ |
+-----------------------+

If the components have been given names (see directSum), use
those instead.
+---------------------------------------------------+
|i5 : R = QQ[a..d];                                 |
+---------------------------------------------------+
|i6 : M = (a => image vars R) ++ (b => coker vars R)|
|                                                   |
|o6 = subquotient (| a b c d 0 |, | 0 0 0 0 |)      |
|                  | 0 0 0 0 1 |  | a b c d |       |
|                                                   |
|                               2                   |
|o6 : R-module, subquotient of R                    |
+---------------------------------------------------+
|i7 : M^[a]                                         |
|                                                   |
|o7 = {1} | 1 0 0 0 0 |                             |
|     {1} | 0 1 0 0 0 |                             |
|     {1} | 0 0 1 0 0 |                             |
|     {1} | 0 0 0 1 0 |                             |
|                                                   |
|o7 : Matrix                                        |
+---------------------------------------------------+
|i8 : isWellDefined oo                              |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+
|i9 : M^[b]                                         |
|                                                   |
|o9 = | 0 0 0 0 1 |                                 |
|                                                   |
|o9 : Matrix                                        |
+---------------------------------------------------+
|i10 : isWellDefined oo                             |
|                                                   |
|o10 = true                                         |
+---------------------------------------------------+
|i11 : isWellDefined(M^{2})                         |
|                                                   |
|o11 = false                                        |
+---------------------------------------------------+

This works the same way for chain complexes.
+---------------------------------------------------------+
|i12 : C = res coker vars R                               |
|                                                         |
|       1      4      6      4      1                     |
|o12 = R  <-- R  <-- R  <-- R  <-- R  <-- 0               |
|                                                         |
|      0      1      2      3      4      5               |
|                                                         |
|o12 : ChainComplex                                       |
+---------------------------------------------------------+
|i13 : D = (a=>C) ++ (b=>C)                               |
|                                                         |
|       2      8      12      8      2                    |
|o13 = R  <-- R  <-- R   <-- R  <-- R  <-- 0              |
|                                                         |
|      0      1      2       3      4      5              |
|                                                         |
|o13 : ChainComplex                                       |
+---------------------------------------------------------+
|i14 : D^[a]                                              |
|                                                         |
|           1               2                             |
|o14 = 0 : R  <----------- R  : 0                         |
|                | 1 0 |                                  |
|                                                         |
|           4                               8             |
|      1 : R  <--------------------------- R  : 1         |
|                {1} | 1 0 0 0 0 0 0 0 |                  |
|                {1} | 0 1 0 0 0 0 0 0 |                  |
|                {1} | 0 0 1 0 0 0 0 0 |                  |
|                {1} | 0 0 0 1 0 0 0 0 |                  |
|                                                         |
|           6                                       12    |
|      2 : R  <----------------------------------- R   : 2|
|                {2} | 1 0 0 0 0 0 0 0 0 0 0 0 |          |
|                {2} | 0 1 0 0 0 0 0 0 0 0 0 0 |          |
|                {2} | 0 0 1 0 0 0 0 0 0 0 0 0 |          |
|                {2} | 0 0 0 1 0 0 0 0 0 0 0 0 |          |
|                {2} | 0 0 0 0 1 0 0 0 0 0 0 0 |          |
|                {2} | 0 0 0 0 0 1 0 0 0 0 0 0 |          |
|                                                         |
|           4                               8             |
|      3 : R  <--------------------------- R  : 3         |
|                {3} | 1 0 0 0 0 0 0 0 |                  |
|                {3} | 0 1 0 0 0 0 0 0 |                  |
|                {3} | 0 0 1 0 0 0 0 0 |                  |
|                {3} | 0 0 0 1 0 0 0 0 |                  |
|                                                         |
|           1                   2                         |
|      4 : R  <--------------- R  : 4                     |
|                {4} | 1 0 |                              |
|                                                         |
|      5 : 0 <----- 0 : 5                                 |
|               0                                         |
|                                                         |
|o14 : ChainComplexMap                                    |
+---------------------------------------------------------+

See also
========

  * directSum -- direct sum of modules or maps
  * Matrix ^ Array -- component of map corresponding to
    summand of target
  * Module _ Array -- inclusion from summand
  * Module ^ List -- projection onto summand

Ways to use this method:
========================

  * "ChainComplex ^ Array"
  * Module ^ Array -- projection onto summand

Module ^ List -- projection onto summand
****************************************

Synopsis
========

  * Operator: ^,

Description
===========

M^{i,j,k,...} -- provides the projection map from a free module M to the free
module corresponding to the basis vectors whose index numbers are listed.

+-----------------------+
|i1 : (ZZ^5)^{2,3}      |
|                       |
|o1 = | 0 0 1 0 0 |     |
|     | 0 0 0 1 0 |     |
|                       |
|              2       5|
|o1 : Matrix ZZ  <-- ZZ |
+-----------------------+

See also
========

  * _ -- a binary operator, used for subscripting and access to
    elements
  * Module -- the class of all modules
  * List -- the class of all lists -- {...}

Ways to use this method:
========================

  * Module ^ List -- projection onto summand

Module ^ ZZ -- direct sum
*************************

Synopsis
========

  * Operator: ^,
  * Usage:
        M^n
  * Inputs:
      * M
      * n
  * Outputs:
      * the direct sum of n copies of M

Description
===========

+-----------------------------------+
|i1 : M = coker matrix{{1,2,3}}     |
|                                   |
|o1 = cokernel | 1 2 3 |            |
|                                   |
|                              1    |
|o1 : ZZ-module, quotient of ZZ     |
+-----------------------------------+
|i2 : M^3                           |
|                                   |
|o2 = cokernel | 1 2 3 0 0 0 0 0 0 ||
|              | 0 0 0 1 2 3 0 0 0 ||
|              | 0 0 0 0 0 0 1 2 3 ||
|                                   |
|                              3    |
|o2 : ZZ-module, quotient of ZZ     |
+-----------------------------------+
|i3 : directSum(3:M)                |
|                                   |
|o3 = cokernel | 1 2 3 0 0 0 0 0 0 ||
|              | 0 0 0 1 2 3 0 0 0 ||
|              | 0 0 0 0 0 0 1 2 3 ||
|                                   |
|                              3    |
|o3 : ZZ-module, quotient of ZZ     |
+-----------------------------------+

See also
========

  * directSum -- direct sum of modules or maps
  * ++ -- a binary operator, usually used for direct sum

Ways to use this method:
========================

  * Module ^ ZZ -- direct sum

Module ^** ZZ -- tensor power
*****************************

Synopsis
========

  * Operator: ^**,
  * Usage:
        M^**i
  * Inputs:
      * M
      * i
  * Outputs:
      * a module, the i-th tensor power of M

Description
===========

The second symmetric power of the canonical module of the rational quartic:
+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..d];                                                           |
+-----------------------------------------------------------------------------+
|i2 : I = monomialCurveIdeal(R,{1,3,4})                                       |
|                                                                             |
|                        3      2     2    2    3    2                        |
|o2 = ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c)                      |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : M = Ext^1(I,R^{-4})                                                     |
|                                                                             |
|o3 = cokernel {1} | c 0 -d 0 -b |                                            |
|              {1} | b c 0  a 0  |                                            |
|              {1} | 0 d c  b a  |                                            |
|                                                                             |
|                            3                                                |
|o3 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i4 : M^**2                                                                   |
|                                                                             |
|o4 = cokernel {2} | c 0 -d 0 -b 0 0 0  0 0  0 0 0  0 0  c 0 -d 0 -b 0 0 0  0 |
|              {2} | b c 0  a 0  0 0 0  0 0  0 0 0  0 0  0 0 0  0 0  c 0 -d 0 |
|              {2} | 0 d c  b a  0 0 0  0 0  0 0 0  0 0  0 0 0  0 0  0 0 0  0 |
|              {2} | 0 0 0  0 0  c 0 -d 0 -b 0 0 0  0 0  b c 0  a 0  0 0 0  0 |
|              {2} | 0 0 0  0 0  b c 0  a 0  0 0 0  0 0  0 0 0  0 0  b c 0  a |
|              {2} | 0 0 0  0 0  0 d c  b a  0 0 0  0 0  0 0 0  0 0  0 0 0  0 |
|              {2} | 0 0 0  0 0  0 0 0  0 0  c 0 -d 0 -b 0 d c  b a  0 0 0  0 |
|              {2} | 0 0 0  0 0  0 0 0  0 0  b c 0  a 0  0 0 0  0 0  0 d c  b |
|              {2} | 0 0 0  0 0  0 0 0  0 0  0 d c  b a  0 0 0  0 0  0 0 0  0 |
|                                                                             |
|                            9                                                |
|o4 : R-module, quotient of R                                                 |
|-----------------------------------------------------------------------------|
|0  0 0 0  0 0  |                                                             |
|-b 0 0 0  0 0  |                                                             |
|0  c 0 -d 0 -b |                                                             |
|0  0 0 0  0 0  |                                                             |
|0  0 0 0  0 0  |                                                             |
|0  b c 0  a 0  |                                                             |
|0  0 0 0  0 0  |                                                             |
|a  0 0 0  0 0  |                                                             |
|0  0 d c  b a  |                                                             |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * Module ^** ZZ -- tensor power

Module _ Array -- inclusion from summand
****************************************

Synopsis
========

  * Operator: _,
  * Usage:
        M_[i,j,...,k]
  * Inputs:
      * M, or a chain complex,
      * [i,j,...,k], an array of indices
  * Outputs:
      * a matrix, or a chain complex map,

Description
===========

The module or chain complex M should be a direct sum, and the result is the map
corresponding to inclusion from the sum of the components numbered or named i,
j, ..., k.  Free modules are regarded as direct sums of modules.

+-----------------------+
|i1 : M = ZZ^2 ++ ZZ^3  |
|                       |
|       5               |
|o1 = ZZ                |
|                       |
|o1 : ZZ-module, free   |
+-----------------------+
|i2 : M_[0]             |
|                       |
|o2 = | 1 0 |           |
|     | 0 1 |           |
|     | 0 0 |           |
|     | 0 0 |           |
|     | 0 0 |           |
|                       |
|              5       2|
|o2 : Matrix ZZ  <-- ZZ |
+-----------------------+
|i3 : M_[1]             |
|                       |
|o3 = | 0 0 0 |         |
|     | 0 0 0 |         |
|     | 1 0 0 |         |
|     | 0 1 0 |         |
|     | 0 0 1 |         |
|                       |
|              5       3|
|o3 : Matrix ZZ  <-- ZZ |
+-----------------------+
|i4 : M_[1,0]           |
|                       |
|o4 = | 0 0 0 1 0 |     |
|     | 0 0 0 0 1 |     |
|     | 1 0 0 0 0 |     |
|     | 0 1 0 0 0 |     |
|     | 0 0 1 0 0 |     |
|                       |
|              5       5|
|o4 : Matrix ZZ  <-- ZZ |
+-----------------------+

If the components have been given names (see directSum), use
those instead.
+---------------------------------------------------+
|i5 : R = QQ[a..d];                                 |
+---------------------------------------------------+
|i6 : M = (a => image vars R) ++ (b => coker vars R)|
|                                                   |
|o6 = subquotient (| a b c d 0 |, | 0 0 0 0 |)      |
|                  | 0 0 0 0 1 |  | a b c d |       |
|                                                   |
|                               2                   |
|o6 : R-module, subquotient of R                    |
+---------------------------------------------------+
|i7 : M_[a]                                         |
|                                                   |
|o7 = {1} | 1 0 0 0 |                               |
|     {1} | 0 1 0 0 |                               |
|     {1} | 0 0 1 0 |                               |
|     {1} | 0 0 0 1 |                               |
|     {0} | 0 0 0 0 |                               |
|                                                   |
|o7 : Matrix                                        |
+---------------------------------------------------+
|i8 : isWellDefined oo                              |
|                                                   |
|o8 = true                                          |
+---------------------------------------------------+
|i9 : M_[b]                                         |
|                                                   |
|o9 = {1} | 0 |                                     |
|     {1} | 0 |                                     |
|     {1} | 0 |                                     |
|     {1} | 0 |                                     |
|     {0} | 1 |                                     |
|                                                   |
|o9 : Matrix                                        |
+---------------------------------------------------+
|i10 : isWellDefined oo                             |
|                                                   |
|o10 = true                                         |
+---------------------------------------------------+

This works the same way for chain complexes.
+---------------------------------------------+
|i11 : C = res coker vars R                   |
|                                             |
|       1      4      6      4      1         |
|o11 = R  <-- R  <-- R  <-- R  <-- R  <-- 0   |
|                                             |
|      0      1      2      3      4      5   |
|                                             |
|o11 : ChainComplex                           |
+---------------------------------------------+
|i12 : D = (a=>C) ++ (b=>C)                   |
|                                             |
|       2      8      12      8      2        |
|o12 = R  <-- R  <-- R   <-- R  <-- R  <-- 0  |
|                                             |
|      0      1      2       3      4      5  |
|                                             |
|o12 : ChainComplex                           |
+---------------------------------------------+
|i13 : D_[a]                                  |
|                                             |
|           2             1                   |
|o13 = 0 : R  <--------- R  : 0               |
|                | 1 |                        |
|                | 0 |                        |
|                                             |
|           8                       4         |
|      1 : R  <------------------- R  : 1     |
|                {1} | 1 0 0 0 |              |
|                {1} | 0 1 0 0 |              |
|                {1} | 0 0 1 0 |              |
|                {1} | 0 0 0 1 |              |
|                {1} | 0 0 0 0 |              |
|                {1} | 0 0 0 0 |              |
|                {1} | 0 0 0 0 |              |
|                {1} | 0 0 0 0 |              |
|                                             |
|           12                           6    |
|      2 : R   <----------------------- R  : 2|
|                 {2} | 1 0 0 0 0 0 |         |
|                 {2} | 0 1 0 0 0 0 |         |
|                 {2} | 0 0 1 0 0 0 |         |
|                 {2} | 0 0 0 1 0 0 |         |
|                 {2} | 0 0 0 0 1 0 |         |
|                 {2} | 0 0 0 0 0 1 |         |
|                 {2} | 0 0 0 0 0 0 |         |
|                 {2} | 0 0 0 0 0 0 |         |
|                 {2} | 0 0 0 0 0 0 |         |
|                 {2} | 0 0 0 0 0 0 |         |
|                 {2} | 0 0 0 0 0 0 |         |
|                 {2} | 0 0 0 0 0 0 |         |
|                                             |
|           8                       4         |
|      3 : R  <------------------- R  : 3     |
|                {3} | 1 0 0 0 |              |
|                {3} | 0 1 0 0 |              |
|                {3} | 0 0 1 0 |              |
|                {3} | 0 0 0 1 |              |
|                {3} | 0 0 0 0 |              |
|                {3} | 0 0 0 0 |              |
|                {3} | 0 0 0 0 |              |
|                {3} | 0 0 0 0 |              |
|                                             |
|           2                 1               |
|      4 : R  <------------- R  : 4           |
|                {4} | 1 |                    |
|                {4} | 0 |                    |
|                                             |
|      5 : 0 <----- 0 : 5                     |
|               0                             |
|                                             |
|o13 : ChainComplexMap                        |
+---------------------------------------------+

See also
========

  * directSum -- direct sum of modules or maps
  * Matrix ^ Array -- component of map corresponding to
    summand of target
  * Module ^ Array -- projection onto summand
  * Module _ List -- map from free module to some
    generators

Ways to use this method:
========================

  * "ChainComplex _ Array"
  * Module _ Array -- inclusion from summand

Module _ List -- map from free module to some generators
********************************************************

Synopsis
========

  * Operator: _,
  * Usage:
        M_p
  * Inputs:
      * M, or an ideal,
      * p, of integers
  * Outputs:
      * f, a map from a free module to the module M which sends the basis
        vectors to the generators of M whose index numbers are listed.

Description
===========

If M is an ideal, then the map maps to module M.
+--------------------------------+
|i1 : R = QQ[x,y,z]              |
|                                |
|o1 = R                          |
|                                |
|o1 : PolynomialRing             |
+--------------------------------+
|i2 : I = ideal vars R           |
|                                |
|o2 = ideal (x, y, z)            |
|                                |
|o2 : Ideal of R                 |
+--------------------------------+
|i3 : f = I_{0,2}                |
|                                |
|o3 = {1} | 1 0 |                |
|     {1} | 0 0 |                |
|     {1} | 0 1 |                |
|                                |
|o3 : Matrix                     |
+--------------------------------+
|i4 : image f                    |
|                                |
|o4 = image | x z |              |
|                                |
|                             1  |
|o4 : R-module, submodule of R   |
+--------------------------------+
|i5 : M = image syz vars R       |
|                                |
|o5 = image {1} | -y 0  -z |     |
|           {1} | x  -z 0  |     |
|           {1} | 0  y  x  |     |
|                                |
|                             3  |
|o5 : R-module, submodule of R   |
+--------------------------------+
|i6 : g = M_{1}                  |
|                                |
|o6 = {2} | 0 |                  |
|     {2} | 1 |                  |
|     {2} | 0 |                  |
|                                |
|                   1            |
|o6 : Matrix M <-- R             |
+--------------------------------+
|i7 : source g                   |
|                                |
|      1                         |
|o7 = R                          |
|                                |
|o7 : R-module, free, degrees {2}|
+--------------------------------+
|i8 : target g                   |
|                                |
|o8 = image {1} | -y 0  -z |     |
|           {1} | x  -z 0  |     |
|           {1} | 0  y  x  |     |
|                                |
|                             3  |
|o8 : R-module, submodule of R   |
+--------------------------------+

See also
========

  * module(Ideal) (missing documentation)
  * Module _ ZZ

Ways to use this method:
========================

  * "Ideal _ List"
  * Module _ List -- map from free module to some
    generators

Module Array -- make a chain complex from a module
**************************************************

Synopsis
========

  * Operator: SPACE,

Description
===========

M[n] -- create a chain complex with the module M concentrated in degree -n.

See also
========

  * ChainComplex -- the class of all chain complexes

Ways to use this method:
========================

  * Module Array -- make a chain complex from a module

module(Ring) -- make or get a module
************************************

Synopsis
========

  * Function: module,
  * Usage:
        module R
  * Inputs:
      * R
  * Outputs:
      * the free module of rank 1 over the ring R

Description
===========

+--------------------+
|i1 : ZZ             |
|                    |
|o1 = ZZ             |
|                    |
|o1 : Ring           |
+--------------------+
|i2 : module ZZ      |
|                    |
|       1            |
|o2 = ZZ             |
|                    |
|o2 : ZZ-module, free|
+--------------------+

Ways to use this method:
========================

  * module(Ring) -- make or get a module

module(Vector) -- the module of a vector
****************************************

Synopsis
========

  * Function: module,
  * Usage:
        module v
  * Inputs:
      * v
  * Outputs:
      * the module that contains the vector v

Description
===========

The class of v is also equal to the module of v.
+--------------------+
|i1 : F = ZZ^4       |
|                    |
|       4            |
|o1 = ZZ             |
|                    |
|o1 : ZZ-module, free|
+--------------------+
|i2 : v = F_2        |
|                    |
|o2 = | 0 |          |
|     | 0 |          |
|     | 1 |          |
|     | 0 |          |
|                    |
|       4            |
|o2 : ZZ             |
+--------------------+
|i3 : module v       |
|                    |
|       4            |
|o3 = ZZ             |
|                    |
|o3 : ZZ-module, free|
+--------------------+
|i4 : class v        |
|                    |
|       4            |
|o4 = ZZ             |
|                    |
|o4 : ZZ-module, free|
+--------------------+

Ways to use this method:
========================

  * module(Vector) -- the module of a vector

modulo(Matrix,Matrix) -- find the pre-image (pullback) of image of a map (low level version)
********************************************************************************************

Synopsis
========

  * Function: modulo,
  * Usage:
        modulo(f,g)
  * Inputs:
      * f
      * g
  * Outputs:
      * a matrix,  whose image is the pre-image (pullback) of
        the image of g under f

Description
===========

The maps f and g must have the same target, and their sources and targets must
be free. If f is null, then it is taken to be the identity.  If g
is null, it is taken to be zero.

This function is mainly for internal use.

+------------------------------------------------+
|i1 : R = QQ[x,y,z]                              |
|                                                |
|o1 = R                                          |
|                                                |
|o1 : PolynomialRing                             |
+------------------------------------------------+
|i2 : f = matrix {{x,y}}                         |
|                                                |
|o2 = | x y |                                    |
|                                                |
|             1      2                           |
|o2 : Matrix R  <-- R                            |
+------------------------------------------------+
|i3 : g = matrix {{y,z}}                         |
|                                                |
|o3 = | y z |                                    |
|                                                |
|             1      2                           |
|o3 : Matrix R  <-- R                            |
+------------------------------------------------+
|i4 : modulo(f,g)                                |
|                                                |
|o4 = {1} | 0 z y |                              |
|     {1} | 1 0 0 |                              |
|                                                |
|             2      3                           |
|o4 : Matrix R  <-- R                            |
+------------------------------------------------+
|i5 : kernel( inducedMap(coker g, target g) * f )|
|                                                |
|o5 = image {1} | 0 z y |                        |
|           {1} | 1 0 0 |                        |
|                                                |
|                             2                  |
|o5 : R-module, submodule of R                   |
+------------------------------------------------+

Ways to use this method:
========================

  * modulo(Matrix,Matrix) -- find the
    pre-image (pullback) of image of a map (low level version)
  * "modulo(Matrix,Nothing)"
  * "modulo(Nothing,Matrix)"

Monoid -- the class of all monoids
**********************************

Description
===========

A monoid is a set with a multiplicative operation on it and an identity
element.  A typical monoid is the set of monomials in a polynomial ring, which
we consider to be created before the polynomial ring is created.

Types of monoid:
================

  * OrderedMonoid -- the class of all ordered monoids

Functions and methods returning a monoid:
=========================================

  * "degreesMonoid" -- see degreesRing, -- the ring or
    monoid of degrees
  * monoid -- make or retrieve a monoid
  * "Monoid ** Monoid" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "Monoid ^** ZZ" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * tensor(Monoid,Monoid) -- tensor product
    of monoids

Methods that use a monoid:
==========================

  * degreeGroup(Monoid) (missing documentation)
  * "degreeLength(Monoid)" -- see degreeLength, -- the
    length of the degree vector
  * "degrees(Monoid)" -- see degrees(Ring), -- degrees
    of generators
  * "degreesMonoid(Monoid)" -- see degreesRing, -- the ring
    or monoid of degrees
  * "degreesRing(Monoid)" -- see degreesRing, -- the ring or
    monoid of degrees
  * "describe(Monoid)" -- see describe, -- real description
  * generators(Monoid) -- list of generators
  * "heft(Monoid)" -- see heft, -- heft vector of ring or monoid
  * Monoid _* (missing documentation)
  * numgens(Monoid) -- number of generators of a
    monoid
  * options(Monoid) -- get values used for optional
    arguments
  * "InexactFieldFamily Monoid" -- see Ring Monoid, -- make
    a polynomial ring
  * Ring Monoid -- make a polynomial ring
  * RingElement _ Monoid (missing documentation)
  * "use(Monoid)" -- see use(Ring), -- install ring
    variables and ring operations
  * vars(Monoid) -- list of variables in a monoid

For the programmer
==================

The object Monoid, is a type, with ancestor classes
Type < MutableHashTable <
HashTable < Thing.

monoid(Ring) -- make or retrieve a monoid
*****************************************

Synopsis
========

  * Function: monoid,
  * Usage:
        monoid R
  * Inputs:
      * R, a ring,
  * Optional inputs,:
      * Constants (missing documentation) => ..., default value false,
      * DegreeGroup (missing documentation) => ..., default value null,
      * DegreeLift, =>
        ..., default value null, specify maps between degree groups
      * DegreeMap, => ...,
        default value null, specify maps between degree groups
      * DegreeRank, => ...,
        default value null, specify the degrees of the variables
      * Degrees, => ...,
        default value null, specify the degrees of the variables
      * Global, => ..., default
        value true, specify local or global monomial order
      * Heft, => ..., default
        value null, specify a heft vector
      * Inverses, => ...,
        default value false, allow negative exponents in monomials
      * Join, => ..., default
        value null, specify how to handle degrees in the coefficient ring
      * Local, => ..., default
        value false, specify local or global monomial order
      * MonomialOrder,
        => ..., default value {GRevLex, Position => Up}, specify the monomial
        ordering
      * MonomialSize, =>
        ..., default value 32, specify the bit-length of monomial exponents in
        the ring
      * SkewCommutative,
        => ..., default
        value {}, specify Skew commuting variables in the ring
      * VariableBaseName,
        => ..., default value "p", specify the names of the indeterminates
      * Variables, => ...,
        default value null, specify the names of the indeterminates
      * Weights, => ...,
        default value {}, specify weights of the variables
      * WeylAlgebra, =>
        ..., default value {}, specify differential operators in the ring
  * Outputs:
      * a monoid, the monoid of monomials in the polynomial ring
        R

Description
===========

If R is a quotient ring of a polynomial ring S, then the monoid of S is
returned.

+-------------------------------------+
|i1 : R = QQ[a..d, Weights=>{1,2,3,4}]|
|                                     |
|o1 = R                               |
|                                     |
|o1 : PolynomialRing                  |
+-------------------------------------+
|i2 : M = monoid R                    |
|                                     |
|o2 = M                               |
|                                     |
|o2 : GeneralOrderedMonoid            |
+-------------------------------------+
|i3 : use M                           |
|                                     |
|o3 = M                               |
|                                     |
|o3 : GeneralOrderedMonoid            |
+-------------------------------------+
|i4 : class a                         |
|                                     |
|o4 = M                               |
|                                     |
|o4 : GeneralOrderedMonoid            |
+-------------------------------------+

Ways to use this method:
========================

  * monoid(Ring) -- make or retrieve a monoid

MonoidElement -- the class of all monoid elements
*************************************************

See also
========

  * monoid -- make or retrieve a monoid

Functions and methods returning a monoid element:
=================================================

  * lift(IndexedVariable,type of MonoidElement) (missing documentation)
  * lift(RingElement,type of MonoidElement) (missing documentation)
  * RingElement _ Monoid (missing documentation)

Methods that use a monoid element:
==================================

  * baseName(MonoidElement) (missing documentation)
  * degree(MonoidElement) (missing documentation)
  * "exponents(MonoidElement)" -- see exponents, -- the
    exponents of a polynomial
  * "listForm(MonoidElement)" -- see listForm, -- convert to
    list form
  * MonoidElement * MonoidElement (missing documentation)
  * MonoidElement * ZZ (missing documentation)
  * MonoidElement .. MonoidElement (missing documentation)
  * MonoidElement .. Thing (missing documentation)
  * MonoidElement ..< MonoidElement (missing documentation)
  * MonoidElement ..< Thing (missing documentation)
  * MonoidElement / MonoidElement (missing documentation)
  * MonoidElement : MonoidElement (missing documentation)
  * MonoidElement == MonoidElement (missing documentation)
  * MonoidElement == ZZ (missing documentation)
  * MonoidElement ? MonoidElement (missing documentation)
  * MonoidElement ^ ZZ (missing documentation)
  * MonoidElement _ Ring (missing documentation)
  * MonoidElement _ Thing (missing documentation)
  * MonoidElement Array (missing documentation)
  * "standardForm(MonoidElement)" -- see standardForm, --
    convert to standard form
  * Thing .. MonoidElement (missing documentation)
  * Thing ..< MonoidElement (missing documentation)
  * ZZ * MonoidElement (missing documentation)
  * ZZ == MonoidElement (missing documentation)

For the programmer
==================

The object MonoidElement, is a type, with
ancestor classes HashTable, < Thing.

monomialCurveIdeal -- make the ideal of a monomial curve
********************************************************

Synopsis
========

  * Usage:
        I = monomialCurveIdeal(R, a)
  * Inputs:
      * R, a polynomial ring, over a field
      * a, a list, containing integers to be used as exponents in
        the parametrization of a rational curve
  * Outputs:
      * I, an ideal, corresponding to the projective curve given
        parametrically on an affine piece by $t \mapsto (t^{a_0}, \dots,
        t^{a_n})$

Description
===========

The ideal is defined in the polynomial ring $R$, which must have at least $n+1$
variables, preferably all of equal degree. The first $n+1$ variables in the
ring are used.

A plane quintic curve of genus 6
================================

+----------------------------------+
|i1 : R = ZZ/101[a..f]             |
|                                  |
|o1 = R                            |
|                                  |
|o1 : PolynomialRing               |
+----------------------------------+
|i2 : monomialCurveIdeal(R, {3, 5})|
|                                  |
|            5    2 3              |
|o2 = ideal(b  - a c )             |
|                                  |
|o2 : Ideal of R                   |
+----------------------------------+

A genus 2 curve with one singular point
=======================================

+---------------------------------------------+
|i3 : monomialCurveIdeal(R, {3, 4, 5})        |
|                                             |
|             2         2       2   3         |
|o3 = ideal (c  - b*d, b c - a*d , b  - a*c*d)|
|                                             |
|o3 : Ideal of R                              |
+---------------------------------------------+

A genus 7 curve with two singular points
========================================

+-----------------------------------------------------------------------------+
|i4 : monomialCurveIdeal(R, {6, 7, 8, 9, 11})                                 |
|                                                                             |
|             2                    2                    2                   2 |
|o4 = ideal (e  - c*f, d*e - b*f, d  - c*e, c*d - b*e, c  - b*d, b*c*e - a*f ,|
|     ------------------------------------------------------------------------|
|      2            2            3                                            |
|     b d - a*e*f, b c - a*d*f, b  - a*c*f)                                   |
|                                                                             |
|o4 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

The smooth rational quartic in $\PP^3$
======================================

+-------------------------------------------------------+
|i5 : monomialCurveIdeal(R, {1, 3, 4})                  |
|                                                       |
|                        3      2     2    2    3    2  |
|o5 = ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c)|
|                                                       |
|o5 : Ideal of R                                        |
+-------------------------------------------------------+

For the programmer
==================

The object monomialCurveIdeal, is a function closure.

MonomialIdeal -- the class of all monomial ideals handled by the engine
***********************************************************************

Description
===========

Monomial ideals are kinds of ideals, but many algorithms are much faster.
Generally, any routines available for ideals are also available for monomial
ideals.
+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..d];                                                           |
+-----------------------------------------------------------------------------+
|i2 : I = monomialIdeal(a*b*c,b*c*d,a^2*d,b^3*c)                              |
|                                                                             |
|                            3    2                                           |
|o2 = monomialIdeal (a*b*c, b c, a d, b*c*d)                                  |
|                                                                             |
|o2 : MonomialIdeal of R                                                      |
+-----------------------------------------------------------------------------+
|i3 : I^2                                                                     |
|                                                                             |
|                     2 2 2     4 2   6 2   3        2 3        2 2    4 2    |
|o3 = monomialIdeal (a b c , a*b c , b c , a b*c*d, a b c*d, a*b c d, b c d,  |
|     ------------------------------------------------------------------------|
|      4 2   2     2   2 2 2                                                  |
|     a d , a b*c*d , b c d )                                                 |
|                                                                             |
|o3 : MonomialIdeal of R                                                      |
+-----------------------------------------------------------------------------+
|i4 : I + monomialIdeal(b*c)                                                  |
|                                                                             |
|                          2                                                  |
|o4 = monomialIdeal (b*c, a d)                                                |
|                                                                             |
|o4 : MonomialIdeal of R                                                      |
+-----------------------------------------------------------------------------+
|i5 : I : monomialIdeal(b*c)                                                  |
|                                                                             |
|                        2                                                    |
|o5 = monomialIdeal (a, b , d)                                                |
|                                                                             |
|o5 : MonomialIdeal of R                                                      |
+-----------------------------------------------------------------------------+
|i6 : radical I                                                               |
|                                                                             |
|o6 = monomialIdeal (b*c, a*d)                                                |
|                                                                             |
|o6 : MonomialIdeal of R                                                      |
+-----------------------------------------------------------------------------+
|i7 : associatedPrimes I                                                      |
|                                                                             |
|o7 = {monomialIdeal (a, b), monomialIdeal (a, c), monomialIdeal (b, d),      |
|     ------------------------------------------------------------------------|
|     monomialIdeal (c, d), monomialIdeal (a, b, d)}                          |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : primaryDecomposition I                                                  |
|                                                                             |
|                      2                      2                               |
|o8 = {monomialIdeal (a , b), monomialIdeal (a , c), monomialIdeal (b, d),    |
|     ------------------------------------------------------------------------|
|                                              3                              |
|     monomialIdeal (c, d), monomialIdeal (a, b , d)}                         |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+

Specialized functions only available for monomial ideals
--------------------------------------------------------

  * borel(MonomialIdeal) -- make a Borel fixed
    submodule
  * isBorel(MonomialIdeal) -- whether an ideal is fixed by
    upper triangular changes of coordinates
  * MonomialIdeal - MonomialIdeal, --
    monomial ideal difference
  * dual(MonomialIdeal) -- the Alexander dual
    of a monomial ideal
  * independentSets -- some size-maximal independent
    subsets of variables modulo an ideal
  * irreducibleDecomposition (PrimaryDecomposition)
    -- express a monomial ideal
    as an intersection of irreducible monomial ideals
  * standardPairs -- find the standard pairs of a
    monomial ideal
+-----------------------------------------------------------------------------+
|i9 : borel I                                                                 |
|                                                                             |
|                     3   2      2   3   2           2      2     2   2       |
|o9 = monomialIdeal (a , a b, a*b , b , a c, a*b*c, b c, a*c , b*c , a d,     |
|     ------------------------------------------------------------------------|
|             2                                                               |
|     a*b*d, b d, a*c*d, b*c*d)                                               |
|                                                                             |
|o9 : MonomialIdeal of R                                                      |
+-----------------------------------------------------------------------------+
|i10 : isBorel I                                                              |
|                                                                             |
|o10 = false                                                                  |
+-----------------------------------------------------------------------------+
|i11 : I - monomialIdeal(b^3*c,b^4)                                           |
|                                                                             |
|                             2                                               |
|o11 = monomialIdeal (a*b*c, a d, b*c*d)                                      |
|                                                                             |
|o11 : MonomialIdeal of R                                                     |
+-----------------------------------------------------------------------------+
|i12 : standardPairs I                                                        |
|                                                                             |
|                                                                             |
|o12 = {{1, {c, d}}, {a, {c, d}}, {1, {b, d}}, {a, {b, d}}, {1, {a, c}}, {1,  |
|      -----------------------------------------------------------------------|
|                           2                                                 |
|      {b, a}}, {b, {c}}, {b , {c}}}                                          |
|                                                                             |
|o12 : List                                                                   |
+-----------------------------------------------------------------------------+
|i13 : independentSets I                                                      |
|                                                                             |
|o13 = {a*b, a*c, b*d, c*d}                                                   |
|                                                                             |
|o13 : List                                                                   |
+-----------------------------------------------------------------------------+
|i14 : dual I                                                                 |
|                                                                             |
|                        3        2      3                                    |
|o14 = monomialIdeal (a*b , a*c, a b*d, b d, c*d)                             |
|                                                                             |
|o14 : MonomialIdeal of R                                                     |
+-----------------------------------------------------------------------------+
The ring of a monomial ideal must be a commutative polynomial ring.  This ring
must not be a skew commuting ring, and/or a quotient ring.

Functions and methods returning a monomial ideal:
=================================================

  * "MonomialIdeal * MonomialIdeal" -- see *, -- a binary operator,
    usually used for multiplication
  * "MonomialIdeal * Ring" -- see *, -- a binary operator, usually
    used for multiplication
  * "Ring * MonomialIdeal" -- see *, -- a binary operator, usually
    used for multiplication
  * "RingElement * MonomialIdeal" -- see *, -- a binary operator,
    usually used for multiplication
  * "MonomialIdeal + MonomialIdeal" -- see +, -- a unary or binary
    operator, usually used for addition
  * "borel(MonomialIdeal)" -- see borel(Matrix), --
    make a Borel fixed submodule
  * "MonomialIdeal ^ Array" -- see Ideal ^ Array, --
    bracket power of an ideal
  * "MonomialIdeal ^ ZZ" -- see Ideal ^ ZZ, -- power of an
    ideal
  * "mingens(MonomialIdeal)" -- see mingens(Module),
    -- minimal generator matrix
  * monomialIdeal -- make a monomial ideal
  * MonomialIdeal - MonomialIdeal, --
    monomial ideal difference
  * monomialIdeal(String) (Classic) -- make a
    monomial ideal using classic Macaulay syntax
  * "MonomialIdeal : RingElement" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotient(MonomialIdeal,RingElement)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "saturate(MonomialIdeal,RingElement)" -- see saturate (Saturation),
    -- saturation of ideal or submodule
  * "trim(MonomialIdeal)" -- see trim, -- minimize generators and
    relations

Methods that use a monomial ideal:
==================================

  * "ZZ % MonomialIdeal" -- see %, -- a binary operator, usually used
    for remainder and reduction
  * "ZZ // MonomialIdeal" -- see //, -- a binary operator, usually
    used for quotient
  * codim(MonomialIdeal) -- compute the
    codimension
  * "dim(MonomialIdeal)" -- see dim(Ideal), -- compute
    the Krull dimension
  * dual(MonomialIdeal) -- the Alexander dual
    of a monomial ideal
  * dual(MonomialIdeal,List) -- the
    Alexander dual
  * dual(MonomialIdeal,RingElement)
    -- the Alexander dual
  * "generators(MonomialIdeal)" -- see generators(Ideal),
    -- the generator matrix of an ideal
  * ideal(MonomialIdeal) -- converts a
    monomial ideal to an ideal
  * "independentSets(MonomialIdeal)" -- see independentSets,
    -- some size-maximal independent subsets of variables
    modulo an ideal
  * "irreducibleDecomposition(MonomialIdeal)" -- see
    irreducibleDecomposition (PrimaryDecomposition),
    -- express a monomial ideal as an intersection of irreducible monomial
    ideals
  * "isBorel(MonomialIdeal)" -- see isBorel, -- whether an ideal
    is fixed by upper triangular changes of coordinates
  * "isMonomialIdeal(MonomialIdeal)" -- see isMonomialIdeal,
    -- whether something is a monomial ideal
  * "isSquareFree(MonomialIdeal)" -- see isSquareFree, --
    whether something is square free monomial ideal
  * lcm(MonomialIdeal) -- least common multiple
    of all minimal generators
  * "Matrix // MonomialIdeal" -- see Matrix // Matrix,
    -- factor a map through another
  * "RingElement // MonomialIdeal" -- see Matrix // Matrix,
    -- factor a map through another
  * "Matrix % MonomialIdeal" -- see methods for normal forms and remainder,
    -- normal form of ring
    elements and matrices
  * "RingElement % MonomialIdeal" -- see methods for normal forms and remainder,
    -- normal form of ring
    elements and matrices
  * MonomialIdeal == MonomialIdeal (missing documentation)
  * MonomialIdeal == ZZ (missing documentation)
  * "monomialIdeal(MonomialIdeal)" -- see monomialIdeal(Ideal),
    -- monomial ideal of lead monomials of a Gröbner
    basis
  * "numgens(MonomialIdeal)" -- see numgens(Ring), --
    number of generators of a polynomial ring
  * "poincare(MonomialIdeal)" -- see poincare, -- assemble
    degrees of a ring, module, or ideal into a polynomial
  * "polarize(MonomialIdeal)" -- see polarize, -- given a
    monomial ideal, computes the squarefree monomial ideal obtained via
    polarization
  * "standardPairs(MonomialIdeal)" -- see standardPairs,
    -- find the standard pairs of a monomial ideal
  * "standardPairs(MonomialIdeal,List)" -- see standardPairs,
    -- find the standard pairs of a monomial ideal
  * ZZ == MonomialIdeal (missing documentation)

For the programmer
==================

The object MonomialIdeal, is a type, with
ancestor classes Ideal, < HashTable <
Thing.

monomialIdeal -- make a monomial ideal
**************************************

Ways to use monomialIdeal:
==========================

  * monomialIdeal(Ideal) -- monomial ideal of
    lead monomials of a Gröbner basis
  * "monomialIdeal(Module)" -- see monomialIdeal(Ideal),
    -- monomial ideal of lead monomials of a Gröbner
    basis
  * "monomialIdeal(MonomialIdeal)" -- see monomialIdeal(Ideal),
    -- monomial ideal of lead monomials of a Gröbner
    basis
  * "monomialIdeal(List)" -- see monomialIdeal(Matrix),
    -- monomial ideal of lead monomials
  * monomialIdeal(Matrix) -- monomial ideal
    of lead monomials
  * "monomialIdeal(RingElement)" -- see monomialIdeal(Matrix),
    -- monomial ideal of lead monomials
  * "monomialIdeal(Sequence)" -- see monomialIdeal(Matrix),
    -- monomial ideal of lead monomials
  * monomialIdeal(String) (Classic) -- make a
    monomial ideal using classic Macaulay syntax

For the programmer
==================

The object monomialIdeal, is a method function with a single argument.

MonomialIdeal - MonomialIdeal -- monomial ideal difference
**********************************************************

Synopsis
========

  * Operator: -,
  * Usage:
        I - J
  * Inputs:
      * I
      * J
  * Outputs:
      * a monomial ideal, generated by those minimal
        generators of I which are not in J

Description
===========

+-------------------------------------+
|i1 : R = QQ[a..d];                   |
+-------------------------------------+
|i2 : I = monomialIdeal(a^3,b^2,a*b*c)|
|                                     |
|                     3   2           |
|o2 = monomialIdeal (a , b , a*b*c)   |
|                                     |
|o2 : MonomialIdeal of R              |
+-------------------------------------+
|i3 : J = monomialIdeal(a^2,b^3,a*b*c)|
|                                     |
|                     2   3           |
|o3 = monomialIdeal (a , b , a*b*c)   |
|                                     |
|o3 : MonomialIdeal of R              |
+-------------------------------------+
|i4 : I - J                           |
|                                     |
|                    2                |
|o4 = monomialIdeal b                 |
|                                     |
|o4 : MonomialIdeal of R              |
+-------------------------------------+
|i5 : J - I                           |
|                                     |
|                    2                |
|o5 = monomialIdeal a                 |
|                                     |
|o5 : MonomialIdeal of R              |
+-------------------------------------+
|i6 : I - (I-J)                       |
|                                     |
|                     3               |
|o6 = monomialIdeal (a , a*b*c)       |
|                                     |
|o6 : MonomialIdeal of R              |
+-------------------------------------+

See also
========

  * MonomialIdeal -- the class of all monomial ideals
    handled by the engine

Ways to use this method:
========================

  * MonomialIdeal - MonomialIdeal, --
    monomial ideal difference

monomialIdeal(Ideal) -- monomial ideal of lead monomials of a Gröbner basis
***************************************************************************

Synopsis
========

  * Function: monomialIdeal,
  * Usage:
        monomialIdeal J
  * Inputs:
      * J
  * Outputs:
      * a monomial ideal, the monomial ideal generated by
        the lead monomials of a Gröbner basis of J

Description
===========

J may also be a submodule of R^1, for R the ring of J.
+------------------------------------------+
|i1 : R = ZZ/101[a,b,c];                   |
+------------------------------------------+
|i2 : I = ideal(a^3,b^3,c^3, a^2-b^2)      |
|                                          |
|             3   3   3   2    2           |
|o2 = ideal (a , b , c , a  - b )          |
|                                          |
|o2 : Ideal of R                           |
+------------------------------------------+
|i3 : monomialIdeal I                      |
|                                          |
|                     2     2   3   3      |
|o3 = monomialIdeal (a , a*b , b , c )     |
|                                          |
|o3 : MonomialIdeal of R                   |
+------------------------------------------+
|i4 : monomialSubideal I                   |
|                                          |
|                     3   2      2   3   3 |
|o4 = monomialIdeal (a , a b, a*b , b , c )|
|                                          |
|o4 : MonomialIdeal of R                   |
+------------------------------------------+
If the coefficient ring is ZZ, lead coefficients of the monomials are ignored.
+---------------------------------+
|i5 : R = ZZ[x,y]                 |
|                                 |
|o5 = R                           |
|                                 |
|o5 : PolynomialRing              |
+---------------------------------+
|i6 : monomialIdeal ideal(2*x,3*y)|
|                                 |
|o6 = monomialIdeal (x, y)        |
|                                 |
|o6 : MonomialIdeal of R          |
+---------------------------------+

See also
========

  * MonomialIdeal -- the class of all monomial ideals
    handled by the engine
  * monomialSubideal -- find the largest monomial
    ideal in an ideal

Ways to use this method:
========================

  * monomialIdeal(Ideal) -- monomial ideal of
    lead monomials of a Gröbner basis
  * "monomialIdeal(Module)"
  * "monomialIdeal(MonomialIdeal)"

monomialIdeal(Matrix) -- monomial ideal of lead monomials
*********************************************************

Synopsis
========

  * Function: monomialIdeal,
  * Usage:
        monomialIdeal L
  * Inputs:
      * L, a matrix, a ring element, a
        list, or a sequence,
  * Outputs:
      * a monomial ideal, the monomial ideal of lead
        monomials of the elements of L

Description
===========

If L is a matrix, then it must have only one row.  For all of these types, the
result is generated by only the lead monomials given: no Gröbner bases are
computed. See monomialIdeal(Ideal), if the lead
monomials of a Gröbner basis is desired.
+--------------------------------------------+
|i1 : R = ZZ/101[a,b,c];                     |
+--------------------------------------------+
|i2 : I = monomialIdeal(a^3,b^3,c^3, a^2-b^2)|
|                                            |
|                     2   3   3              |
|o2 = monomialIdeal (a , b , c )             |
|                                            |
|o2 : MonomialIdeal of R                     |
+--------------------------------------------+
|i3 : M = monomialIdeal vars R               |
|                                            |
|o3 = monomialIdeal (a, b, c)                |
|                                            |
|o3 : MonomialIdeal of R                     |
+--------------------------------------------+
|i4 : J = monomialIdeal 0_R                  |
|                                            |
|o4 = monomialIdeal ()                       |
|                                            |
|o4 : MonomialIdeal of R                     |
+--------------------------------------------+
If the coefficient ring is ZZ, lead coefficients of the monomials are ignored.
+---------------------------+
|i5 : R = ZZ[x,y]           |
|                           |
|o5 = R                     |
|                           |
|o5 : PolynomialRing        |
+---------------------------+
|i6 : monomialIdeal(2*x,3*y)|
|                           |
|o6 = monomialIdeal (x, y)  |
|                           |
|o6 : MonomialIdeal of R    |
+---------------------------+

See also
========

  * MonomialIdeal -- the class of all monomial ideals
    handled by the engine

Ways to use this method:
========================

  * "monomialIdeal(List)"
  * monomialIdeal(Matrix) -- monomial ideal
    of lead monomials
  * "monomialIdeal(RingElement)"
  * "monomialIdeal(Sequence)"

Monomials -- whether to display the number of monomial
******************************************************

Description
===========

Monomials -- an option for status, which specifies whether to
display the number of monomials.

Functions with optional argument named Monomials:
=================================================

  * "coefficients(...,Monomials=>...)" -- see coefficients,
    -- monomials and their coefficients
  * "status(...,Monomials=>...)" -- see status, -- status of a
    resolution computation

For the programmer
==================

The object Monomials, is a symbol.

monomials -- matrix of monomials in a ring element or matrix
************************************************************

Synopsis
========

  * Usage:
        monomials f
  * Inputs:
      * f, either a Matrix, or a RingElement,
  * Optional inputs,:
      * Variables, =>
        ..., default value null, specify variables
  * Outputs:
      * a matrix, a one row matrix in the same ring with all of
        the monomials that appear in f

Description
===========

Each monomial only appears once, and the monomials are sorted in what order?
+-----------------------------------------------------------------------+
|i1 : R = ZZ[a..d,x,y];                                                 |
+-----------------------------------------------------------------------+
|i2 : m = matrix{{a*x^2+b*x*y+c*y^2, a*x^3+b*x^2*y+c*x*y^2+d*y^3+a*x^2}}|
|                                                                       |
|o2 = | ax2+bxy+cy2 ax3+bx2y+cxy2+dy3+ax2 |                             |
|                                                                       |
|             1      2                                                  |
|o2 : Matrix R  <-- R                                                   |
+-----------------------------------------------------------------------+
|i3 : monomials m                                                       |
|                                                                       |
|o3 = | ax3 bx2y cxy2 dy3 ax2 bxy cy2 |                                 |
|                                                                       |
|             1      7                                                  |
|o3 : Matrix R  <-- R                                                   |
+-----------------------------------------------------------------------+
If the monomials in only some of the variables are desired, use the optional
argument monomials(...,Variables=>...).
+-----------------------------------+
|i4 : monomials(m, Variables=>{x,y})|
|                                   |
|o4 = | x3 x2y xy2 y3 x2 xy y2 |    |
|                                   |
|             1      7              |
|o4 : Matrix R  <-- R               |
+-----------------------------------+

See also
========

  * coefficients -- monomials and their coefficients

Ways to use monomials:
======================

  * "monomials(Matrix)"
  * "monomials(RingElement)"

For the programmer
==================

The object monomials, is a method function with options.

monomials(...,Variables=>...) -- specify variables
**************************************************

Synopsis
========

  * Usage:
        monomials(m,Variables=>x)
  * Inputs:
      * x, either a list or sequence of ring variables, a list or sequence of
        integers denoting indices of ring variables, or a single ring element
        or integer index. The default value is: all of the variables
  * Consequences:
      * Each variable not in the set of variables x is considered a coefficient

Further information
===================

  * Default value: null
  * Function: monomials, -- matrix of monomials in a ring
    element or matrix
  * Option key: Variables, -- an optional argument

See also
========

  * coefficients -- monomials and their coefficients

Functions with optional argument named Variables:
=================================================

  * "basis(...,Variables=>...)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "coefficients(...,Variables=>...)" -- see coefficients,
    -- monomials and their coefficients
  * monoid(...,Variables=>...)
    -- specify the names of the
    indeterminates
  * monomials(...,Variables=>...)
    -- specify variables
  * "newRing(...,Variables=>...)" -- see newRing, -- make a copy
    of a ring, with some features changed
  * "symmetricAlgebra(...,Variables=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Variables=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Variables=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

monomialSubideal -- find the largest monomial ideal in an ideal
***************************************************************

Synopsis
========

  * Usage:
        monomialSubideal I
  * Inputs:
      * I, an ideal,
  * Outputs:
      * a monomial ideal, the largest monomial ideal
        contained in I

Description
===========

+---------------------------------------------------------+
|i1 : QQ[a,b,c,d];                                        |
+---------------------------------------------------------+
|i2 : I = ideal(b*c, c^2 - b*d, -a*c+b^2)                 |
|                                                         |
|                  2         2                            |
|o2 = ideal (b*c, c  - b*d, b  - a*c)                     |
|                                                         |
|o2 : Ideal of QQ[a..d]                                   |
+---------------------------------------------------------+
|i3 : monomialSubideal I                                  |
|                                                         |
|                     3          2   3          2         |
|o3 = monomialIdeal (b , b*c, a*c , c , a*b*d, b d, a*c*d)|
|                                                         |
|o3 : MonomialIdeal of QQ[a..d]                           |
+---------------------------------------------------------+

Implemented by Greg Smith.

Ways to use monomialSubideal:
=============================

  * "monomialSubideal(Ideal)"

For the programmer
==================

The object monomialSubideal, is a method function.

multidegree -- multidegree
**************************

Synopsis
========

  * Usage:
        multidegree M
  * Inputs:
      * M, a module, an ideal, or a ring,
  * Outputs:
      * the multidegree of M.  If M is an ideal, the corresponding quotient
        ring is used.

Description
===========

The multidegree is defined on page 165 of Combinatorial Commutative Algebra, by
Miller and Sturmfels.  It is an element of the degrees ring of M.  Our
implementation agrees with their definition provided the heft vector of the
ring has every entry equal to 1. See also Gröbner geometry of Schubert
polynomials, by Allen Knutson and Ezra Miller.

+-----------------------------------------------------------------------------+
|i1 : S = QQ[a..d, Degrees => {{2,-1},{1,0},{0,1},{-1,2}}];                   |
+-----------------------------------------------------------------------------+
|i2 : heft S                                                                  |
|                                                                             |
|o2 = {1, 1}                                                                  |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : multidegree ideal (b^2,b*c,c^2)                                         |
|                                                                             |
|o3 = 3T T                                                                    |
|       0 1                                                                   |
|                                                                             |
|o3 : ZZ[T ..T ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i4 : multidegree ideal a                                                     |
|                                                                             |
|o4 = 2T  - T                                                                 |
|       0    1                                                                |
|                                                                             |
|o4 : ZZ[T ..T ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i5 : multidegree ideal (a^2,a*b,b^2)                                         |
|                                                                             |
|       2                                                                     |
|o5 = 6T  - 3T T                                                              |
|       0     0 1                                                             |
|                                                                             |
|o5 : ZZ[T ..T ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i6 : describe ring oo                                                        |
|                                                                             |
|o6 = ZZ[T ..T , Degrees => {2:1}, MonomialOrder => {MonomialSize => 32},     |
|         0   1                                     {Weights => {2:-1} }      |
|                                                   {GroupLex => 2     }      |
|                                                   {Position => Up    }      |
|-----------------------------------------------------------------------------|
|Inverses => true, Global => false]                                           |
+-----------------------------------------------------------------------------+

Caveat
======

This implementation is provisional in the case where the heft vector does not
have every entry equal to 1.

See also
========

  * heft vectors
  * degreesRing -- the ring or monoid of degrees

Ways to use multidegree:
========================

  * "multidegree(Ideal)"
  * "multidegree(Module)"
  * "multidegree(Ring)"

For the programmer
==================

The object multidegree, is a method function.

mutable matrices
****************

To and from matrices:
+--------------------------------+
|i1 : m = matrix{{1,2,3},{4,5,6}}|
|                                |
|o1 = | 1 2 3 |                  |
|     | 4 5 6 |                  |
|                                |
|              2       3         |
|o1 : Matrix ZZ  <-- ZZ          |
+--------------------------------+
|i2 : n = mutableMatrix m        |
|                                |
|o2 = | 1 2 3 |                  |
|     | 4 5 6 |                  |
|                                |
|o2 : MutableMatrix              |
+--------------------------------+
|i3 : m2 = matrix n              |
|                                |
|o3 = | 1 2 3 |                  |
|     | 4 5 6 |                  |
|                                |
|              2       3         |
|o3 : Matrix ZZ  <-- ZZ          |
+--------------------------------+
|i4 : m2 - m == 0                |
|                                |
|o4 = true                       |
+--------------------------------+
Modifying and accessing entries.  Remember that the upper left entry is (0,0),
not (1,1)!
+------------------------+
|i5 : n_(0,0) = 212314323|
|                        |
|o5 = 212314323          |
+------------------------+
|i6 : n_(0,0)            |
|                        |
|o6 = 212314323          |
+------------------------+
|i7 : n                  |
|                        |
|o7 = | 212314323 2 3 |  |
|     | 4         5 6 |  |
|                        |
|o7 : MutableMatrix      |
+------------------------+
Number of rows, columns, and the ring:
+-----------------+
|i8 : numrows n   |
|                 |
|o8 = 2           |
+-----------------+
|i9 : numColumns n|
|                 |
|o9 = 3           |
+-----------------+
|i10 : numcols n  |
|                 |
|o10 = 3          |
+-----------------+
|i11 : ring n     |
|                 |
|o11 = ZZ         |
|                 |
|o11 : Ring       |
+-----------------+

See row and column operations,

Some other methods for creating mutable matrices.
+-------------------------------------+
|i12 : mutableIdentity(RR_100,5)      |
|                                     |
|o12 = | 1 0 0 0 0 |                  |
|      | 0 1 0 0 0 |                  |
|      | 0 0 1 0 0 |                  |
|      | 0 0 0 1 0 |                  |
|      | 0 0 0 0 1 |                  |
|                                     |
|o12 : MutableMatrix                  |
+-------------------------------------+
|i13 : mutableMatrix(QQ,3,5)          |
|                                     |
|o13 = 0                              |
|                                     |
|o13 : MutableMatrix                  |
+-------------------------------------+
|i14 : randomMutableMatrix(4,4,.5,100)|
|                                     |
|o14 = | -35 0 0  0   |               |
|      | 100 0 0  0   |               |
|      | 0   0 82 18  |               |
|      | -14 0 0  -98 |               |
|                                     |
|o14 : MutableMatrix                  |
+-------------------------------------+

mutableIdentity(Ring,ZZ) -- make a mutable identity matrix
**********************************************************

Synopsis
========

  * Function: mutableIdentity,
  * Usage:
        mutableIdentity(R,nrows)
  * Inputs:
      * R
      * nrows
  * Optional inputs,:
      * Dense => ..., default value true, whether the encoding of the matrix
        should be dense or not: see MutableMatrix,
  * Outputs:
      * a mutable matrix, an nrows by nrows mutable
        identity matrix filled with elements of the ring R

Description
===========

+--------------------------------+
|i1 : m = mutableIdentity(QQ,10) |
|                                |
|o1 = | 1 0 0 0 0 0 0 0 0 0 |    |
|     | 0 1 0 0 0 0 0 0 0 0 |    |
|     | 0 0 1 0 0 0 0 0 0 0 |    |
|     | 0 0 0 1 0 0 0 0 0 0 |    |
|     | 0 0 0 0 1 0 0 0 0 0 |    |
|     | 0 0 0 0 0 1 0 0 0 0 |    |
|     | 0 0 0 0 0 0 1 0 0 0 |    |
|     | 0 0 0 0 0 0 0 1 0 0 |    |
|     | 0 0 0 0 0 0 0 0 1 0 |    |
|     | 0 0 0 0 0 0 0 0 0 1 |    |
|                                |
|o1 : MutableMatrix              |
+--------------------------------+
|i2 : m_(5,5) = 11/13            |
|                                |
|     11                         |
|o2 = --                         |
|     13                         |
|                                |
|o2 : QQ                         |
+--------------------------------+
|i3 : m                          |
|                                |
|o3 = | 1 0 0 0 0 0     0 0 0 0 ||
|     | 0 1 0 0 0 0     0 0 0 0 ||
|     | 0 0 1 0 0 0     0 0 0 0 ||
|     | 0 0 0 1 0 0     0 0 0 0 ||
|     | 0 0 0 0 1 0     0 0 0 0 ||
|     | 0 0 0 0 0 11/13 0 0 0 0 ||
|     | 0 0 0 0 0 0     1 0 0 0 ||
|     | 0 0 0 0 0 0     0 1 0 0 ||
|     | 0 0 0 0 0 0     0 0 1 0 ||
|     | 0 0 0 0 0 0     0 0 0 1 ||
|                                |
|o3 : MutableMatrix              |
+--------------------------------+

See also
========

  * mutableMatrix -- make a mutable matrix

Ways to use this method:
========================

  * mutableIdentity(Ring,ZZ) -- make a
    mutable identity matrix
  * "mutableIdentity(RingFamily,ZZ)"

MutableList -- the class of all mutable lists
*********************************************

Description
===========

For an overview of lists and sequences, see lists and sequences.

Normally the entries in a mutable list are not printed, to prevent infinite
loops in the printing routines.  To print them out, use peek.
+--------------------------------------+
|i1 : s = new MutableList from {a,b,c};|
+--------------------------------------+
|i2 : s#2 = 1234;                      |
+--------------------------------------+
|i3 : s                                |
|                                      |
|o3 = MutableList{...3...}             |
|                                      |
|o3 : MutableList                      |
+--------------------------------------+
|i4 : peek s                           |
|                                      |
|o4 = MutableList{a, b, 1234}          |
+--------------------------------------+

See also
========

  * BasicList -- the class of all basic lists

Types of mutable list:
======================

  * Bag -- the class of all bags

Methods that use a mutable list:
================================

  * "positions(MutableList,Function)" -- see positions, --
    which elements of a list satisfy a condition
  * "remove(MutableList,ZZ)" -- see remove, -- remove an entry
    from a mutable hash table, list, or database

For the programmer
==================

The object MutableList, is a type, with
ancestor classes BasicList, < Thing.

MutableMatrix -- the class of all mutable matrices
**************************************************

Description
===========

A mutable matrix in Macaulay2 is a rectangular array of elements of a specific
ring, whose entries can be modified.

A mutable matrix is different from a Matrix, in that a matrix
contains degree information for the target and source of the matrix, while a
mutable matrix has no such information.  Also, more operations are provided for
matrices.

For an overview of mutable matrices, see mutable matrices.

Mutable matrices can either be encoded in a sparse manner (the matrix only
encodes the non-zero elements), or in a dense manner (all elements are stored
-- even zeros).  The distinction is an option to several of the routines that
create mutable matrices (see mutableMatrix,
mutableIdentity). Certain operations over RR
or CC are performed using the lapack library and require dense encoding of
matrices: LUdecomposition, SVD,
solve, eigenvalues, eigenvectors.

row and column operations
-------------------------

  * rowAdd -- add a multiple of one row to another
  * rowSwap -- interchange rows
  * rowPermute -- permute some rows
  * rowMult -- multiply a row by a ring element
  * columnAdd -- add a multiple of one column to another
  * columnSwap -- interchange columns
  * columnPermute -- permute some columns
  * columnMult -- multiply a column by a ring element

matrix arithmetic
-----------------

Many matrix arithmetic routines are only available for immutable matrices, not
mutable matrices.  It is necessary to use matrix, to make an
immutable matrix first.

Functions and methods returning a mutable matrix:
=================================================

  * "mutableIdentity" -- see mutableIdentity(Ring,ZZ),
    -- make a mutable identity matrix
  * mutableMatrix -- make a mutable matrix
  * MutableMatrix ^ ZZ (missing documentation)
  * "randomMutableMatrix" -- see randomMutableMatrix(ZZ,ZZ,RR,ZZ),
    -- a random mutable matrix of
    integers
  * RingMap MutableMatrix (missing documentation)

Methods that use a mutable matrix:
==================================

  * "MutableMatrix * MutableMatrix" -- see *, -- a binary operator,
    usually used for multiplication
  * "RingElement * MutableMatrix" -- see *, -- a binary operator,
    usually used for multiplication
  * "MutableMatrix + MutableMatrix" -- see +, -- a unary or binary
    operator, usually used for addition
  * "- MutableMatrix" -- see -, -- a unary or binary operator, usually
    used for negation or subtraction
  * "MutableMatrix - MutableMatrix" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "clean(RR,MutableMatrix)" -- see clean, -- Set to zero
    elements that are approximately zero
  * "columnAdd(MutableMatrix,ZZ,Number,ZZ)" -- see columnAdd,
    -- add a multiple of one column to another
  * "columnAdd(MutableMatrix,ZZ,RingElement,ZZ)" -- see columnAdd,
    -- add a multiple of one column to another
  * "columnMult(MutableMatrix,ZZ,Number)" -- see columnMult,
    -- multiply a column by a ring element
  * "columnMult(MutableMatrix,ZZ,RingElement)" -- see columnMult,
    -- multiply a column by a ring element
  * "columnPermute(MutableMatrix,ZZ,List)" -- see columnPermute,
    -- permute some columns
  * "columnRankProfile(MutableMatrix)" -- see columnRankProfile,
    -- find the column rank profile of a mutable matrix
  * "columnSwap(MutableMatrix,ZZ,ZZ)" -- see columnSwap, --
    interchange columns
  * "determinant(MutableMatrix)" -- see determinant, --
    determinant of a matrix
  * "eigenvalues(MutableMatrix)" -- see eigenvalues, -- find
    eigenvalues of a matrix
  * "eigenvectors(MutableMatrix)" -- see eigenvectors, --
    find eigenvectors of a matrix over RR or CC
  * "entries(MutableMatrix)" -- see entries, -- lists the
    entries of a matrix
  * "fillMatrix(MutableMatrix)" -- see fillMatrix, -- fill a
    mutable matrix with random numbers
  * "fillMatrix(MutableMatrix,ZZ)" -- see fillMatrix, -- fill
    a mutable matrix with random numbers
  * "inverse(MutableMatrix)" -- see inverse(Matrix),
    -- compute the inverse
  * lift(MutableMatrix,type of InexactNumber') (missing documentation)
  * lift(MutableMatrix,type of InexactNumber) (missing documentation)
  * lift(MutableMatrix,type of Number) (missing documentation)
  * lift(MutableMatrix,type of RingElement) (missing documentation)
  * "LLL(MutableMatrix)" -- see LLL (LLLBases), -- compute an LLL
    basis
  * "LUdecomposition(MutableMatrix)" -- see LUdecomposition,
    -- LU decomposition
  * "MutableMatrix _ Sequence" -- see Matrix _ Sequence,
    -- get entry of matrix
  * matrix(MutableMatrix) -- make a matrix
    from a mutable one
  * "mutableMatrix(MutableMatrix)" -- see mutableMatrix,
    -- make a mutable matrix
  * MutableMatrix * RingElement (missing documentation)
  * MutableMatrix * RR (missing documentation)
  * MutableMatrix * ZZ (missing documentation)
  * MutableMatrix == MutableMatrix (missing documentation)
  * MutableMatrix == ZZ (missing documentation)
  * MutableMatrix ^ List (missing documentation)
  * MutableMatrix _ List (missing documentation)
  * MutableMatrix _ Sequence = Thing,
    -- assignment to an element of a mutable matrix
  * "norm(InexactField,MutableMatrix)" -- see norm,
  * "norm(MutableMatrix)" -- see norm,
  * "norm(RR,MutableMatrix)" -- see norm,
  * "nullSpace(MutableMatrix)" -- see nullSpace, -- find the
    null space of a mutable matrix
  * "numColumns(MutableMatrix)" -- see numColumns(Matrix),
    -- number of columns in a matrix or mutable matrix
  * "numRows(MutableMatrix)" -- see numRows(Matrix),
    -- number of rows in a matrix or mutable matrix
  * "precision(MutableMatrix)" -- see precision,
  * "QRDecomposition(MutableMatrix)" -- see QRDecomposition,
    -- compute a QR decomposition of a real matrix
  * "rank(MutableMatrix)" -- see rank, -- compute the rank
  * "reducedRowEchelonForm(MutableMatrix)" -- see reducedRowEchelonForm,
    -- compute the reduced row echelon form of a matrix
    or mutable matrix over a field
  * "ring(MutableMatrix)" -- see ring, -- get the associated ring
    of an object
  * "rowAdd(MutableMatrix,ZZ,Number,ZZ)" -- see rowAdd, -- add a
    multiple of one row to another
  * "rowAdd(MutableMatrix,ZZ,RingElement,ZZ)" -- see rowAdd, --
    add a multiple of one row to another
  * "rowMult(MutableMatrix,ZZ,Number)" -- see rowMult, --
    multiply a row by a ring element
  * "rowMult(MutableMatrix,ZZ,RingElement)" -- see rowMult, --
    multiply a row by a ring element
  * "rowPermute(MutableMatrix,ZZ,List)" -- see rowPermute, --
    permute some rows
  * "rowRankProfile(MutableMatrix)" -- see rowRankProfile,
    -- find the row rank profile of a mutable matrix
  * "rowSwap(MutableMatrix,ZZ,ZZ)" -- see rowSwap, --
    interchange rows
  * RR * MutableMatrix (missing documentation)
  * "solve(MutableMatrix,MutableMatrix)" -- see solve, -- solve
    linear equation(s)
  * "submatrix(MutableMatrix,VisibleList)" -- see
    submatrix(Matrix,VisibleList), --
    select columns
  * "submatrix(MutableMatrix,VisibleList,VisibleList)" -- see
    submatrix(Matrix,VisibleList,VisibleList),
    -- select part of a
    matrix
  * "SVD(MutableMatrix)" -- see SVD, -- singular value decomposition
    of a matrix
  * "transpose(MutableMatrix)" -- see transpose(Matrix),
    -- transpose a matrix
  * ZZ * MutableMatrix (missing documentation)
  * ZZ == MutableMatrix (missing documentation)

For the programmer
==================

The object MutableMatrix, is a type, with
ancestor classes HashTable, < Thing.

mutableMatrix -- make a mutable matrix
**************************************

Synopsis
========

  * Usage:
        mutableMatrix m
  * Inputs:
      * m, a matrix, a mutable matrix, or
        a list,
  * Optional inputs,:
      * Dense => ..., default value true, whether the encoding of the matrix
        should be dense or not: see MutableMatrix,
  * Outputs:
      * a new mutable matrix whose entries are obtained from m.  If m is a
        list, it should be a doubly nested list (table) of ring elements, all
        from the same ring.

Description
===========

+---------------------------------------+
|i1 : f = mutableMatrix {{1,2,3,4}}     |
|                                       |
|o1 = | 1 2 3 4 |                       |
|                                       |
|o1 : MutableMatrix                     |
+---------------------------------------+
|i2 : f_(0,2)                           |
|                                       |
|o2 = 3                                 |
+---------------------------------------+
|i3 : f_(0,2) = 33                      |
|                                       |
|o3 = 33                                |
+---------------------------------------+
|i4 : f                                 |
|                                       |
|o4 = | 1 2 33 4 |                      |
|                                       |
|o4 : MutableMatrix                     |
+---------------------------------------+
|i5 : R = QQ[a..z]                      |
|                                       |
|o5 = R                                 |
|                                       |
|o5 : PolynomialRing                    |
+---------------------------------------+
|i6 : mutableMatrix genericMatrix(R,3,3)|
|                                       |
|o6 = | a d g |                         |
|     | b e h |                         |
|     | c f i |                         |
|                                       |
|o6 : MutableMatrix                     |
+---------------------------------------+

Ways to use mutableMatrix:
==========================

  * "mutableMatrix(List)"
  * "mutableMatrix(Matrix)"
  * "mutableMatrix(MutableMatrix)"
  * mutableMatrix(Ring,ZZ,ZZ) -- make
    a mutable matrix filled with zeroes
  * "mutableMatrix(RingFamily,ZZ,ZZ)" -- see mutableMatrix(Ring,ZZ,ZZ),
    -- make a mutable matrix filled with
    zeroes

For the programmer
==================

The object mutableMatrix, is a method function with options.

MutableMatrix _ Sequence = Thing -- assignment to an element of a mutable matrix
********************************************************************************

Synopsis
========

  * Operator: _,
  * Usage:
        f_(i,j) = r
  * Inputs:
      * f
      * a pair (i,j) of integers
      * r
  * Consequences:
      * the (i,j) entry of f is replaced by the ring element r

Description
===========

+-----------------------------+
|i1 : R = QQ[a..d]            |
|                             |
|o1 = R                       |
|                             |
|o1 : PolynomialRing          |
+-----------------------------+
|i2 : f = mutableMatrix vars R|
|                             |
|o2 = | a b c d |             |
|                             |
|o2 : MutableMatrix           |
+-----------------------------+
|i3 : f_(0,2)                 |
|                             |
|o3 = c                       |
|                             |
|o3 : R                       |
+-----------------------------+
|i4 : f_(0,2) = 7*c^2         |
|                             |
|       2                     |
|o4 = 7c                      |
|                             |
|o4 : R                       |
+-----------------------------+
|i5 : f                       |
|                             |
|o5 = | a b 7c2 d |           |
|                             |
|o5 : MutableMatrix           |
+-----------------------------+

Ways to use this method:
========================

  * MutableMatrix _ Sequence = Thing,
    -- assignment to an element of a mutable matrix

mutableMatrix(Ring,ZZ,ZZ) -- make a mutable matrix filled with zeroes
*********************************************************************

Synopsis
========

  * Function: mutableMatrix,
  * Usage:
        mutableMatrix(R,nrows,ncols)
  * Inputs:
      * R
      * nrows
      * ncols
  * Optional inputs,:
      * Dense, => ..., default value true, whether the
        encoding of the matrix should be dense or not: see MutableMatrix,
  * Outputs:
      * an nrows by ncols mutable matrix filled with zeroes from the ring R

Description
===========

+----------------------------------------------------+
|i1 : m = mutableMatrix(QQ,10,20)                    |
|                                                    |
|o1 = 0                                              |
|                                                    |
|o1 : MutableMatrix                                  |
+----------------------------------------------------+
|i2 : m_(5,5) = 11/13                                |
|                                                    |
|     11                                             |
|o2 = --                                             |
|     13                                             |
|                                                    |
|o2 : QQ                                             |
+----------------------------------------------------+
|i3 : m                                              |
|                                                    |
|o3 = | 0 0 0 0 0 0     0 0 0 0 0 0 0 0 0 0 0 0 0 0 ||
|     | 0 0 0 0 0 0     0 0 0 0 0 0 0 0 0 0 0 0 0 0 ||
|     | 0 0 0 0 0 0     0 0 0 0 0 0 0 0 0 0 0 0 0 0 ||
|     | 0 0 0 0 0 0     0 0 0 0 0 0 0 0 0 0 0 0 0 0 ||
|     | 0 0 0 0 0 0     0 0 0 0 0 0 0 0 0 0 0 0 0 0 ||
|     | 0 0 0 0 0 11/13 0 0 0 0 0 0 0 0 0 0 0 0 0 0 ||
|     | 0 0 0 0 0 0     0 0 0 0 0 0 0 0 0 0 0 0 0 0 ||
|     | 0 0 0 0 0 0     0 0 0 0 0 0 0 0 0 0 0 0 0 0 ||
|     | 0 0 0 0 0 0     0 0 0 0 0 0 0 0 0 0 0 0 0 0 ||
|     | 0 0 0 0 0 0     0 0 0 0 0 0 0 0 0 0 0 0 0 0 ||
|                                                    |
|o3 : MutableMatrix                                  |
+----------------------------------------------------+

See also
========

  * mutableIdentity -- make a mutable
    identity matrix
  * mutableMatrix -- make a mutable matrix

Ways to use this method:
========================

  * mutableMatrix(Ring,ZZ,ZZ) -- make
    a mutable matrix filled with zeroes
  * "mutableMatrix(RingFamily,ZZ,ZZ)"

Net ^ ZZ -- raise a net or string
*********************************

Synopsis
========

  * Operator: ^,
  * Usage:
        n^i
  * Inputs:
      * n, or a a string,
      * i
  * Outputs:
      * a net, obtained by elevating n by raising its characters by
        i rows

Description
===========

If n is a string, then n^0 is an easy way to convert it to a net.
+-----------------+
|i1 : s = "x"     |
|                 |
|o1 = x           |
+-----------------+
|i2 : class(s^0)  |
|                 |
|o2 = Net         |
|                 |
|o2 : Type        |
+-----------------+
|i3 : n = s^1|"ij"|
|                 |
|     x           |
|o3 =  ij         |
+-----------------+
|i4 : n^-3        |
|                 |
|o4 =             |
|                 |
|     x           |
|      ij         |
+-----------------+

See also
========

  * strings and nets -- an overview of strings and
    nets in Macaulay2

Ways to use this method:
========================

  * Net ^ ZZ -- raise a net or string
  * "String ^ ZZ"

Net | Net -- join strings or nets
*********************************

Synopsis
========

  * Operator: |,

Description
===========

s|t -- concatenates strings or nets horizontally.

The result is a string if the arguments are all strings, otherwise it is a net.
The baselines of the nets are aligned.
+-----------------------+
|i1 : "abc" | "def"     |
|                       |
|o1 = abcdef            |
+-----------------------+
|i2 : x = "abc" || "ABC"|
|                       |
|o2 = abc               |
|     ABC               |
+-----------------------+
|i3 : x|"x"|x           |
|                       |
|o3 = abcxabc           |
|     ABC ABC           |
+-----------------------+
If one of the two arguments is an integer, it is converted to a string first.
+-----------------+
|i4 : "t = " | 333|
|                 |
|o4 = t = 333     |
+-----------------+

See also
========

  * horizontalJoin -- join nets or strings horizontally

Ways to use this method:
========================

  * Net | Net -- join strings or nets
  * "String | String"
  * "String | ZZ"
  * "ZZ | String"

Net || Net -- join nets or strings vertically
*********************************************

Synopsis
========

  * Operator: ||,

Description
===========

m||n -- joins nets or strings by concatenating them vertically.  The baseline
of the result is the baseline of the first one.

In this example, we build a large net with arrows to indicate the location of
the baseline.
+-----------------------------------------+
|i1 : x = "x" | "3"^1                     |
|                                         |
|      3                                  |
|o1 = x                                   |
+-----------------------------------------+
|i2 : "<--- " | ( x || "" || x ) | " --->"|
|                                         |
|           3                             |
|o2 = <--- x  --->                        |
|                                         |
|           3                             |
|          x                              |
+-----------------------------------------+

See also
========

  * stack -- join nets or string vertically

Ways to use this method:
========================

  * Net || Net -- join nets or strings vertically

NetFile -- the class of all net files
*************************************

Description
===========

This class is experimental.  Net files are intended to supplant output files
eventually.  Whereas a file is a stream of bytes, or in some non-unix operating
systems, a sequence of lines each of which is a sequence of bytes, a net file
is a sequence of lines, each of which is a net.  Each output line is assembled
by joining nets one by one.
+-------------------------------------------+
|i1 : f = newNetFile()                      |
|                                           |
|o1 = <<a netfile>>                         |
|                                           |
|o1 : NetFile                               |
+-------------------------------------------+
|i2 : f << "aabbcc" << endl                 |
|                                           |
|o2 = <<a netfile>>                         |
|                                           |
|o2 : NetFile                               |
+-------------------------------------------+
|i3 : f << "aa" << "bb"^1 << "cc"^-1 << endl|
|                                           |
|o3 = <<a netfile>>                         |
|                                           |
|o3 : NetFile                               |
+-------------------------------------------+
|i4 : f << "aa" << "bb"^1 << "cc"^-1 << endl|
|                                           |
|o4 = <<a netfile>>                         |
|                                           |
|o4 : NetFile                               |
+-------------------------------------------+
|i5 : getNetFile f                          |
|                                           |
|                bb      bb                 |
|o5 = (aabbcc, aa    , aa    )              |
|                  cc      cc               |
|                                           |
|o5 : Sequence                              |
+-------------------------------------------+
|i6 : peek oo                               |
|                                           |
|                +------+  +------+         |
|      +------+  |  bb  |  |  bb  |         |
|o6 = (|aabbcc|, |aa    |, |aa    |)        |
|      +------+  |    cc|  |    cc|         |
|                +------+  +------+         |
+-------------------------------------------+
|i7 : class \ ooo                           |
|                                           |
|o7 = (Net, Net, Net)                       |
|                                           |
|o7 : Sequence                              |
+-------------------------------------------+

Methods that use an object of class NetFile:
============================================

  * "Manipulator NetFile"
  * "NetFile << Manipulator"
  * "NetFile << Net"
  * "NetFile << String"

For the programmer
==================

The object NetFile, is a type, with ancestor class
Thing.

netList(VisibleList) -- a table of boxes
****************************************

Synopsis
========

  * Function: netList,
  * Usage:
        netList v
  * Inputs:
      * v, a list of lists of things to be converted to nets and displayed as a
        table in a net
  * Optional inputs,:
      * Boxes => ..., default value true, whether to draw boxes around the
        individual nets. Can be a Boolean, or a pair controlling separately the
        horizontal and vertical lines of the boxes. Each element of the pair is
        either a Boolean (draw all or none) or a list of rows/columns where
        lines are to inserted.
      * BaseRow => an integer, default value 0, the index of the
        base row, for the purpose of setting the baseline of the net produced.
        The value is allowed to be as large as the length of v, larger by 1
        than one might expect.
      * HorizontalSpace => an integer, default value 0, the amount
        of space horizontally between entries or between entries and their
        enclosing boxes
      * VerticalSpace => an integer, default value 0, the amount of
        space vertically between entries or between entries and their enclosing
        boxes
      * Alignment => ..., default value Left, Center, Left, Right, or a list of
        those symbols indicating horizontal adjustment; if it's a list, the
        i-th entry specifies the adjustment in the i-th column; if not, the
        symbol applies to all columns.
  * Outputs:
      * a net obtained by converting the elements of each list in the list of
        lists v to nets and arranging them in a table, as specified by the
        options

Description
===========

+-----------------------------------------------------------------+
|i1 : f = {{"hi there","foo"},{-3, 2^40}}                         |
|                                                                 |
|o1 = {{hi there, foo}, {-3, 1099511627776}}                      |
|                                                                 |
|o1 : List                                                        |
+-----------------------------------------------------------------+
|i2 : netList f                                                   |
|                                                                 |
|     +--------+-------------+                                    |
|o2 = |hi there|foo          |                                    |
|     +--------+-------------+                                    |
|     |-3      |1099511627776|                                    |
|     +--------+-------------+                                    |
+-----------------------------------------------------------------+
|i3 : netList(f,Boxes=>false)                                     |
|                                                                 |
|o3 = hi therefoo                                                 |
|     -3      1099511627776                                       |
+-----------------------------------------------------------------+
|i4 : netList(f,Boxes=>true,HorizontalSpace=>1,VerticalSpace=>1)  |
|                                                                 |
|     +----------+---------------+                                |
|     |          |               |                                |
|o4 = | hi there | foo           |                                |
|     |          |               |                                |
|     +----------+---------------+                                |
|     |          |               |                                |
|     | -3       | 1099511627776 |                                |
|     |          |               |                                |
|     +----------+---------------+                                |
+-----------------------------------------------------------------+
|i5 : netList(f,Boxes=>true,Alignment=>Center)                    |
|                                                                 |
|     +--------+-------------+                                    |
|o5 = |hi there|     foo     |                                    |
|     +--------+-------------+                                    |
|     |   -3   |1099511627776|                                    |
|     +--------+-------------+                                    |
+-----------------------------------------------------------------+
|i6 : netList(f,Boxes=>true,BaseRow=>1)                           |
|                                                                 |
|     +--------+-------------+                                    |
|     |hi there|foo          |                                    |
|     +--------+-------------+                                    |
|o6 = |-3      |1099511627776|                                    |
|     +--------+-------------+                                    |
+-----------------------------------------------------------------+
|i7 : netList(f,Boxes=>{{1},{1}})                                 |
|                                                                 |
|o7 = hi there|foo                                                |
|     --------+-------------                                      |
|     -3      |1099511627776                                      |
+-----------------------------------------------------------------+
|i8 : netList apply(5,i->apply(i+1,j->(i,j)))                     |
|                                                                 |
|     +------+------+------+------+------+                        |
|o8 = |(0, 0)|      |      |      |      |                        |
|     +------+------+------+------+------+                        |
|     |(1, 0)|(1, 1)|      |      |      |                        |
|     +------+------+------+------+------+                        |
|     |(2, 0)|(2, 1)|(2, 2)|      |      |                        |
|     +------+------+------+------+------+                        |
|     |(3, 0)|(3, 1)|(3, 2)|(3, 3)|      |                        |
|     +------+------+------+------+------+                        |
|     |(4, 0)|(4, 1)|(4, 2)|(4, 3)|(4, 4)|                        |
|     +------+------+------+------+------+                        |
+-----------------------------------------------------------------+
|i9 : netList(apply(5,i->apply(i+1,j->(i,j))),Boxes=>{true,false})|
|                                                                 |
|     ------------------------------                              |
|o9 = (0, 0)                                                      |
|     ------------------------------                              |
|     (1, 0)(1, 1)                                                |
|     ------------------------------                              |
|     (2, 0)(2, 1)(2, 2)                                          |
|     ------------------------------                              |
|     (3, 0)(3, 1)(3, 2)(3, 3)                                    |
|     ------------------------------                              |
|     (4, 0)(4, 1)(4, 2)(4, 3)(4, 4)                              |
|     ------------------------------                              |
+-----------------------------------------------------------------+

Ways to use this method:
========================

  * netList(VisibleList) -- a table of boxes

new AtomicInt from ZZ -- initialize an atomic integer
*****************************************************

Synopsis
========

  * Usage:
        new AtomicInt from x
        new AtomicInt
  * Inputs:
      * x, an integer,
  * Outputs:
      * an atomic integer,

Description
===========

Use this to initialize a new atomic integer.

+-------------------------+
|i1 : new AtomicInt from 5|
|                         |
|o1 = 5                   |
|                         |
|o1 : AtomicInt           |
+-------------------------+

If x is not given, then the initial value is 0.

+------------------+
|i2 : new AtomicInt|
|                  |
|o2 = 0            |
|                  |
|o2 : AtomicInt    |
+------------------+

Ways to use this method:
========================

  * new AtomicInt from ZZ -- initialize an atomic
    integer

new ChainComplex -- make a new chain complex from scratch
*********************************************************

Description
===========

C = new ChainComplex -- make a new chain complex.

The new chain complex is initialized with a differential of degree -1
accessible as C.dd and of type ChainComplexMap.  You
can take the new chain complex and fill in the ring, the modules, and the
differentials.
+-----------------------------------+
|i1 : C = new ChainComplex;         |
+-----------------------------------+
|i2 : C.ring = ZZ;                  |
+-----------------------------------+
|i3 : C#2 = ZZ^1;                   |
+-----------------------------------+
|i4 : C#3 = ZZ^2;                   |
+-----------------------------------+
|i5 : C.dd#3 = matrix {{3,-11}};    |
|                                   |
|              1       2            |
|o5 : Matrix ZZ  <-- ZZ             |
+-----------------------------------+
|i6 : C                             |
|                                   |
|       1       2                   |
|o6 = ZZ  <-- ZZ                    |
|                                   |
|     2       3                     |
|                                   |
|o6 : ChainComplex                  |
+-----------------------------------+
|i7 : C.dd                          |
|                                   |
|           1                  2    |
|o7 = 2 : ZZ  <------------- ZZ  : 3|
|                | 3 -11 |          |
|                                   |
|o7 : ChainComplexMap               |
+-----------------------------------+

Ways to use this method:
========================

  * new ChainComplex -- make a new chain complex from
    scratch

new HashTable from List -- make a hash table from a list
********************************************************

Description
===========

new HashTable from x -- produce a new hash table from a list x.

Elements of x which are options, k => v cause the value v to be stored in x
under the key k.

See also
========

  * hashTable -- make a hash table

Ways to use this method:
========================

  * new HashTable from List -- make a hash
    table from a list

new ZZ from AtomicInt -- load an atomic integer
***********************************************

Synopsis
========

  * Usage:
        new ZZ from x
  * Inputs:
      * x, an atomic integer,
  * Outputs:
      * an integer,

Description
===========

This loads the value of the atomic integer x.  This operation occurs atomically
and is thread safe.

+----------------------+
|i1 : x = new AtomicInt|
|                      |
|o1 = 0                |
|                      |
|o1 : AtomicInt        |
+----------------------+
|i2 : x += 5           |
|                      |
|o2 = 0                |
+----------------------+
|i3 : new ZZ from x    |
|                      |
|o3 = 5                |
+----------------------+

Ways to use this method:
========================

  * new ZZ from AtomicInt -- load an atomic
    integer

newCoordinateSystem -- change variables
***************************************

Description
===========

newCoordinateSystem(S,m) -- takes a one-rowed matrix m of independent linear
forms over a ring R and returns a pair (f,g), where f is a ring map given by
some linear change of coordinates from R to S which sends the last variables of
R to the forms in m, and g is the inverse of f.

The ring S should have the same number of variables as S.
+----------------------------------------------------------+
|i1 : R = ZZ/101[a..d]                                     |
|                                                          |
|o1 = R                                                    |
|                                                          |
|o1 : PolynomialRing                                       |
+----------------------------------------------------------+
|i2 : S = ZZ/101[p..s]                                     |
|                                                          |
|o2 = S                                                    |
|                                                          |
|o2 : PolynomialRing                                       |
+----------------------------------------------------------+
|i3 : (f,g) = newCoordinateSystem(S,matrix{{a+2*b,3*c-d}});|
+----------------------------------------------------------+
|i4 : f                                                    |
|                                                          |
|o4 = map (S, R, {50p, 3r, p + 2q, 3r - s})                |
|                                                          |
|o4 : RingMap S <-- R                                      |
+----------------------------------------------------------+
|i5 : g                                                    |
|                                                          |
|o5 = map (R, S, {-2a, a - 50c, 34b, b - d})               |
|                                                          |
|o5 : RingMap R <-- S                                      |
+----------------------------------------------------------+

Ways to use newCoordinateSystem:
================================

  * "newCoordinateSystem(PolynomialRing,Matrix)"

For the programmer
==================

The object newCoordinateSystem, is a method function.

NewFromMethod
*************

Description
===========

NewFromMethod -- a symbol used as a method name in conjunction with the
new, operator.

Intended for internal use only.

For the programmer
==================

The object NewFromMethod, is a symbol.

newline -- the new line character sequence
******************************************

Description
===========

newline -- a string containing the character or sequence of characters that
represents the end of a line.  To end an output line, you should use
endl, instead, because there is more to ending an output line than
emitting the characters in newline, especially when nets are being used.

This string depends on what your operating system is: on Unix systems it is the
ascii character 10; on Macintoshes it is the ascii character 13, and under
MS-DOS and Windows 95 it is a string of length 2 containing ascii characters 13
and 10.

Try to avoid confusing the newline string described here with the ASCII
character called newline.  That character can be incorporated into a string
with the escape sequence \n, and it always has ASCII code 10.
+---------------+
|i1 : ascii "\n"|
|               |
|o1 = {10}      |
|               |
|o1 : List      |
+---------------+

See also
========

  * Net -- the class of all nets and strings

For the programmer
==================

The object newline, is a string.

NewMethod
*********

Description
===========

NewMethod -- a symbol used as a method name in conjunction with the new,
operator.

Intended for internal use only.

For the programmer
==================

The object NewMethod, is a symbol.

newNetFile -- create a new net file
***********************************

Synopsis
========

  * Usage:
        newNetFile()
  * Outputs:
      * an instance of the type NetFile,

Description
===========

This function is experimental.

For the programmer
==================

The object newNetFile, is a compiled function.

NewOfFromMethod
***************

Description
===========

NewOfFromMethod -- a symbol used as a method name in conjunction with the
new, operator.

Intended for internal use only.

For the programmer
==================

The object NewOfFromMethod, is a symbol.

NewOfMethod
***********

Description
===========

NewOfMethod -- a symbol used as a method name in conjunction with the
new, operator.

Intended for internal use only.

For the programmer
==================

The object NewOfMethod, is a symbol.

newRing -- make a copy of a ring, with some features changed
************************************************************

Synopsis
========

  * Usage:
        S = newRing(R, options)
  * Inputs:
      * R, a polynomial ring, or a quotient ring,
  * Optional inputs,:
      * Variables => a list, default value nothing, see
        monoid(...,Variables=>...),;
      * VariableBaseName => a symbol, default value nothing, see
        monoid(...,VariableBaseName=>...),;
      * Global => a Boolean value, default value nothing, see
        monoid(...,Global=>...),;
      * Local => a Boolean value, default value nothing, see
        monoid(...,Local=>...),;
      * Inverses => a Boolean value, default value nothing, see
        monoid(...,Inverses=>...),;
      * Weights => a list, default value nothing, see
        monoid(...,Weights=>...),;
      * Degrees => a list, default value nothing, see
        monoid(...,Degrees=>...),;
      * DegreeMap => a Boolean value, default value nothing,
        see monoid(...,DegreeMap=>...),;
      * DegreeLift => a Boolean value, default value nothing,
        see monoid(...,DegreeLift=>...),;
      * DegreeRank => an integer, default value nothing, see
        monoid(...,DegreeRank=>...),;
      * Heft => a list, default value nothing, see
        monoid(...,Heft=>...),;
      * Join => a Boolean value, default value nothing, see
        monoid(...,Join=>...),;
      * MonomialOrder => a list, default value nothing, see
        monoid(...,MonomialOrder=>...),;
      * MonomialSize => an integer, default value nothing, see
        monoid(...,MonomialSize=>...),;
      * SkewCommutative => a Boolean value, default value
        nothing, see monoid(...,SkewCommutative=>...),;
      * WeylAlgebra => a list, default value nothing, see
        monoid(...,WeylAlgebra=>...),;
      * Constants (missing documentation) => ..., default value nothing,
      * DegreeGroup (missing documentation) => ..., default value nothing,
  * Outputs:
      * S, a ring, a new ring, constructed in the same way R was,
        over the same coefficient ring, but with the newly specified options
        overriding those used before. See monoid, for a
        description of those options. If R was a quotient ring, then the number
        of variables must be the same, and S will be a quotient ring, too, with
        defining ideal obtained from the old by substituting the new variables
        for the old, preserving their order.

Description
===========

If a different number of variables is given with Variables,
then the list of degrees in R will be ignored.  If a new degree rank is
specified with DegreeRank, then the list of degrees and the
heft vector of R will be ignored.  If a new nonempty list of degrees is
specified with Degrees, then the degree rank and the heft
vector of R will be ignored.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y, MonomialOrder => Lex, Degrees => {3,5}];                    |
+-----------------------------------------------------------------------------+
|i2 : describe newRing(R, MonomialOrder => GRevLex)                           |
|                                                                             |
|o2 = QQ[x..y, Degrees => {3, 5}, Heft => {1}, MonomialOrder =>               |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32}]                                                        |
|{GRevLex => {3, 5} }                                                         |
|{Position => Up    }                                                         |
+-----------------------------------------------------------------------------+
|i3 : describe newRing(R, Variables => 4)                                     |
|                                                                             |
|o3 = QQ[p ..p , Degrees => {4:1}, Heft => {1}, MonomialOrder =>              |
|         0   3                                                               |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32}]                                                        |
|{Lex => 2          }                                                         |
|{Position => Up    }                                                         |
|{GRevLex => {2:1}  }                                                         |
+-----------------------------------------------------------------------------+
|i4 : describe newRing(R, Heft => {2})                                        |
|                                                                             |
|o4 = QQ[x..y, Degrees => {3, 5}, Heft => {2}, MonomialOrder =>               |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32}]                                                        |
|{Lex => 2          }                                                         |
|{Position => Up    }                                                         |
+-----------------------------------------------------------------------------+
|i5 : S = R/(x^2+y^3);                                                        |
+-----------------------------------------------------------------------------+
|i6 : describe newRing(R, Variables => 2)                                     |
|                                                                             |
|o6 = QQ[p ..p , Degrees => {3, 5}, Heft => {1}, MonomialOrder =>             |
|         0   1                                                               |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32}]                                                        |
|{Lex => 2          }                                                         |
|{Position => Up    }                                                         |
+-----------------------------------------------------------------------------+

The default values for the options of newRing are all set to a non-accessible
private symbol whose name is nothing.

Ways to use newRing:
====================

  * "newRing(PolynomialRing)"
  * "newRing(QuotientRing)"

For the programmer
==================

The object newRing, is a method function with options.

next -- get the next object from an iterator
********************************************

Synopsis
========

  * Usage:
        next x
  * Inputs:
      * x, a thing, an iterator;
  * Outputs:
      * a thing, the next object from x;

Description
===========

This gets the next object from an iterator, i.e., something returned by
iterator.

+------------------------------+
|i1 : iter = iterator {1, 2, 3}|
|                              |
|o1 = iter                     |
|                              |
|o1 : Iterator                 |
+------------------------------+
|i2 : next iter                |
|                              |
|o2 = 1                        |
+------------------------------+
|i3 : next iter                |
|                              |
|o3 = 2                        |
+------------------------------+
|i4 : next iter                |
|                              |
|o4 = 3                        |
+------------------------------+

If the iterator is exhausted, then the symbol StopIteration,
is returned.

+------------------+
|i5 : next iter    |
|                  |
|o5 = StopIteration|
|                  |
|o5 : Symbol       |
+------------------+

See also
========

  * Iterator -- class for iterators
  * iterator -- get an iterator
  * StopIteration -- stop iteration

Ways to use next:
=================

  * "next(Iterator)"

For the programmer
==================

The object next, is a method function.

nextkey -- the next key in a database
*************************************

Description
===========

nextkey f -- return the next key available in the database file f.

Returns null, if none.

See also
========

  * Database -- the class of all database files

For the programmer
==================

The object nextkey, is a compiled function.

nextPrime -- compute the smallest prime greater than or equal to a given number
*******************************************************************************

Synopsis
========

  * Usage:
        nextPrime n
  * Inputs:
      * n, a number,
  * Outputs:
      * an integer, the smallest prime $\ge n$

Description
===========

+---------------------+
|i1 : nextPrime 10000 |
|                     |
|o1 = 10007           |
+---------------------+
|i2 : nextPrime 3.5678|
|                     |
|o2 = 5               |
+---------------------+
|i3 : nextPrime (3/7) |
|                     |
|o3 = 2               |
+---------------------+

See also
========

  * isPrime -- whether a integer or polynomial is prime
  * getPrimeWithRootOfUnity -- find a prime p
    with a primitive n-th root of unity r in ZZ/p

Ways to use nextPrime:
======================

  * "nextPrime(Number)"

For the programmer
==================

The object nextPrime, is a method function.

NoPrint -- top level method for non-printing results
****************************************************

Synopsis
========

  * Usage:
        X#{topLevelMode,NoPrint} = f
  * Inputs:
      * X, a type,
      * f, a function,  that can accept something of type X
  * Consequences:
      * At top level, whenever it is time, as indicated by a semicolon at the
        end of an input line, to suppress printing of an output value of type
        X, the function f will be called.

For the programmer
==================

The object NoPrint, is a symbol.

norm
****

Synopsis
========

  * Usage:
        norm M
        norm(p,M)
  * Inputs:
      * M, a mutable matrix, a matrix, a
        ring element, a number, a
        vector, or a list,
      * p, a real number, or an infinite number,
        specifying which norm to compute.  Currently, only
        p=infinity is accepted.
  * Outputs:
      * the $L^p$-norm of M computed to the minimum of the precisions of M and
        of p.

Description
===========

+------------------------------------------------+
|i1 : printingPrecision = 2                      |
|                                                |
|o1 = 2                                          |
+------------------------------------------------+
|i2 : R = RR_100                                 |
|                                                |
|o2 = RR                                         |
|       100                                      |
|                                                |
|o2 : RealField                                  |
+------------------------------------------------+
|i3 : M = 10*random(R^3,R^10)                    |
|                                                |
|o3 = | 2   5.6 1.9 4.1 3.5 2.6 6.1 5.3 .83 .44 ||
|     | 2   3.7 4.1 6.1 4.7 1.2 9   7.4 .95 1.5 ||
|     | 7.4 1.5 4.3 3.4 6.9 6   9.5 10  4.8 8   ||
|                                                |
|                 3          10                  |
|o3 : Matrix RR     <-- RR                       |
|              100        100                    |
+------------------------------------------------+
|i4 : norm M                                     |
|                                                |
|o4 = 9.952219758672894287555632834552           |
|                                                |
|o4 : RR (of precision 100)                      |
+------------------------------------------------+
|i5 : norm_(numeric_20 infinity) M               |
|                                                |
|o5 = 9.952225                                   |
|                                                |
|o5 : RR (of precision 20)                       |
+------------------------------------------------+
|i6 : norm {3/2,4,-5}                            |
|                                                |
|o6 = 5                                          |
+------------------------------------------------+
The norm of a polynomial is the norm of the vector of its coefficients.
+------------------------------------+
|i7 : RR[x]                          |
|                                    |
|o7 = RR  [x]                        |
|       53                           |
|                                    |
|o7 : PolynomialRing                 |
+------------------------------------+
|i8 : (1+x)^5                        |
|                                    |
|      5     4      3      2         |
|o8 = x  + 5x  + 10x  + 10x  + 5x + 1|
|                                    |
|o8 : RR  [x]                        |
|       53                           |
+------------------------------------+
|i9 : norm oo                        |
|                                    |
|o9 = 10                             |
|                                    |
|o9 : RR (of precision 53)           |
+------------------------------------+

Ways to use norm:
=================

  * "norm(InexactField,MutableMatrix)"
  * "norm(InfiniteNumber,Matrix)"
  * "norm(InfiniteNumber,Number)"
  * "norm(InfiniteNumber,RingElement)"
  * "norm(List)"
  * "norm(Matrix)"
  * "norm(MutableMatrix)"
  * "norm(Number)"
  * "norm(RingElement)"
  * "norm(RR,Matrix)"
  * "norm(RR,MutableMatrix)"
  * "norm(RR,Number)"
  * "norm(RR,RingElement)"
  * "norm(Vector)"

For the programmer
==================

The object norm, is a method function.

normalCone
**********

Description
===========

This function is a method function, defined in the core so multiple packages
can add methods to it.

See also
========

  * normalCone(Polyhedron,Polyhedron) (Polyhedra)
    -- computes the normal
    cone of a face of a polyhedron
  * normalCone(Ideal) (ReesAlgebra) -- The normal
    cone of a subscheme

Ways to use normalCone:
=======================

  * "normalCone(Ideal)" -- see associatedGradedRing (ReesAlgebra),
    -- The normal cone of a subscheme
  * "normalCone(Ideal,RingElement)" -- see associatedGradedRing (ReesAlgebra),
    -- The normal cone of a subscheme
  * normalCone(Polyhedron,Polyhedron) (Polyhedra)
    -- computes the normal
    cone of a face of a polyhedron

For the programmer
==================

The object normalCone, is a method function with options.

not documented yet
******************

We haven't documented yet the way to replace this Macaulay function or script.

Nothing -- the empty class
**************************

Description
===========

This class is useful for representing the class of an argument that is missing.
It is also used as the parent for those things that are not themselves types,
i.e., which do not have instances.

Types of Nothing:
=================

  * InexactNumber'

Functions and methods returning an object of class Nothing:
===========================================================

  * addCancelTask(Task,Task) -- specify
    that the completion of one task triggers the cancellation of another
  * addDependencyTask(Task,Task), --
    schedule a task, but ensure that it will not run until another task
    finishes
  * addStartTask(Task,Task) -- schedule a
    task upon completion of another
  * cancelTask(Task) -- stop a task
  * "echoOff(File)" -- see echoOff, -- turn off echoing
  * "echoOn(File)" -- see echoOn, -- turn on echoing
  * "kill(File)" -- see kill, -- kill a process
  * kill(ZZ) -- kill a process
  * linkFile(String,String) -- make a new
    link to a file
  * "remove(Database,String)" -- see remove, -- remove an entry
    from a mutable hash table, list, or database
  * "remove(HashTable,Thing)" -- see remove, -- remove an entry
    from a mutable hash table, list, or database
  * "remove(MutableList,ZZ)" -- see remove, -- remove an entry
    from a mutable hash table, list, or database
  * "scanPairs(HashTable,Function)" -- see scanPairs, -- apply
    a function to the pairs in a hash table

Methods that use an object of class Nothing:
============================================

  * "concatenate(Nothing)" -- see concatenate, -- join
    strings
  * "Nothing << Manipulator" -- see File << Thing, --
    print to a file
  * "Nothing << Thing" -- see File << Thing, -- print to a
    file
  * "getWWW(String,Nothing)" -- see getWWW, -- get a web page
  * "inducedMap(Module,Nothing,Matrix)" -- see
    inducedMap(Module,Module,Matrix),
    -- compute the induced map
  * "inducedMap(Nothing,Module,Matrix)" -- see
    inducedMap(Module,Module,Matrix),
    -- compute the induced map
  * "inducedMap(Nothing,Nothing,Matrix)" -- see
    inducedMap(Module,Module,Matrix),
    -- compute the induced map
  * "inducesWellDefinedMap(Module,Nothing,Matrix)" -- see
    inducesWellDefinedMap, -- whether a map is well
    defined
  * "inducesWellDefinedMap(Nothing,Module,Matrix)" -- see
    inducesWellDefinedMap, -- whether a map is well
    defined
  * "inducesWellDefinedMap(Nothing,Nothing,Matrix)" -- see
    inducesWellDefinedMap, -- whether a map is well
    defined
  * info(Nothing) (missing documentation)
  * "locate(Nothing)" -- see locate, -- locate source code
  * "Manipulator Nothing" -- see Manipulator, -- the class
    of all file manipulators
  * "map(Module,Nothing,RingMap,List)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * "map(Module,Nothing,RingMap,Matrix)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * map(Module,Nothing,List) -- create
    a matrix by giving a doubly nested list of ring elements
  * map(Module,Nothing,Matrix), --
    recast a matrix to have a new target, and a free module as source
  * "modulo(Matrix,Nothing)" -- see modulo(Matrix,Matrix),
    -- find the pre-image (pullback) of image of a
    map (low level version)
  * "modulo(Nothing,Matrix)" -- see modulo(Matrix,Matrix),
    -- find the pre-image (pullback) of image of a
    map (low level version)
  * Nothing #? Thing (missing documentation)
  * Nothing == Nothing (missing documentation)
  * "package(Nothing)" -- see package, -- get containing package
  * "part(Nothing,Nothing,RingElement)" -- see part, -- select
    terms of a polynomial by degree(s) or weight(s)
  * "part(Nothing,Nothing,VisibleList,RingElement)" -- see part, --
    select terms of a polynomial by degree(s) or weight(s)
  * "part(Nothing,ZZ,RingElement)" -- see part, -- select terms of
    a polynomial by degree(s) or weight(s)
  * "part(Nothing,ZZ,VisibleList,RingElement)" -- see part, --
    select terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,Nothing,RingElement)" -- see part, -- select terms of
    a polynomial by degree(s) or weight(s)
  * "part(ZZ,Nothing,VisibleList,RingElement)" -- see part, --
    select terms of a polynomial by degree(s) or weight(s)
  * "sublists(VisibleList,Function,Function,Nothing)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Nothing)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Nothing,Function)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Nothing,Nothing)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "submatrix'(Matrix,Nothing,Nothing)" -- see submatrix',
    -- exclude rows and/or columns of a matrix
  * "submatrix'(Matrix,Nothing,VisibleList)" -- see submatrix',
    -- exclude rows and/or columns of a matrix
  * "submatrix'(Matrix,VisibleList,Nothing)" -- see submatrix',
    -- exclude rows and/or columns of a matrix
  * "subquotient(Matrix,Nothing)" -- see subquotient, --
    make a subquotient module
  * "subquotient(Module,Matrix,Nothing)" -- see subquotient,
    -- make a subquotient module
  * "subquotient(Module,Nothing,Matrix)" -- see subquotient,
    -- make a subquotient module
  * "subquotient(Module,Nothing,Nothing)" -- see subquotient,
    -- make a subquotient module
  * "subquotient(Nothing,Matrix)" -- see subquotient, --
    make a subquotient module
  * "symmetricAlgebra(Nothing,Nothing,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricAlgebra(Nothing,Ring,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricAlgebra(Ring,Nothing,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "urlEncode(Nothing)" -- see urlEncode, -- URL encoding

For the programmer
==================

The object Nothing, is a type, with ancestor class
Thing.

notify -- whether to notify the user when a file is loaded
**********************************************************

Synopsis
========

  * Usage:
        notify = true
        notify = false
  * Consequences:
      * If notify, is set to true, then each time a
        file or a package is loaded, a message will be displayed.

Description
===========

+-----------------------------------------------------------------------------+
|i1 : notify = true                                                           |
|                                                                             |
|o1 = true                                                                    |
+-----------------------------------------------------------------------------+
|i2 : loadPackage "FirstPackage"                                              |
| -- loading FirstPackage.m2                                                  |
| -- opening database /usr/local/lib/Macaulay2/FirstPackage/cache/rawdocumenta|
| -- beginDocumentation: using documentation database, skipping the rest of /u|
| -- package "FirstPackage" loaded                                            |
| -- loaded /usr/local/share/Macaulay2/FirstPackage.m2                        |
|                                                                             |
|o2 = FirstPackage                                                            |
|                                                                             |
|o2 : Package                                                                 |
|-----------------------------------------------------------------------------|
|tion-dcba-8.db                                                               |
|sr/local/share/Macaulay2/FirstPackage.m2                                     |
+-----------------------------------------------------------------------------+

See also
========

  * load -- read Macaulay2 commands
  * needs -- read Macaulay2 commands if necessary
  * loadPackage -- load a package
  * needsPackage -- load a package if not already loaded

For the programmer
==================

The object notify, is a Boolean value.

notImplemented -- print an 'not implemented' error message
**********************************************************

Synopsis
========

  * Usage:
        notImplemented()

Description
===========

notImplemented() prints an error message that says "not implemented yet".

For the programmer
==================

The object notImplemented, is a function closure.

null -- the unique member of the empty class
********************************************

Description
===========

When it is the value of an expression entered into the interpreter, the output
line doesn't appear.  Empty spots in a list are represented by it.

It is the only member of the class Nothing, which strictly
speaking, ought to have no members at all.

An if, expression with no else, clause returns
null, when the predicate is false.

Various routines that prepare data for printing convert null, to an
empty string.
+--------------------+
|i1 : x = {2,3,,4}   |
|                    |
|o1 = {2, 3, , 4}    |
|                    |
|o1 : List           |
+--------------------+
|i2 : net x          |
|                    |
|o2 = {2, 3, , 4}    |
+--------------------+
|i3 : toString x#2   |
|                    |
|o3 = null           |
+--------------------+
|i4 : peek x         |
|                    |
|o4 = {2, 3, null, 4}|
+--------------------+

For the programmer
==================

The object null, is null.

nullaryMethods
**************

Description
===========

This experimental hash table is to contain methods for handling the case where
a method function, f, say, is called with 0 arguments, i.e., as f().

For the programmer
==================

The object nullaryMethods, is a mutable hash table.

nullhomotopy -- make a null homotopy
************************************

Description
===========

nullhomotopy f -- produce a nullhomotopy for a map f of chain complexes.

Whether f is null homotopic is not checked.

Here is part of an example provided by Luchezar Avramov.  We construct a random
module over a complete intersection, resolve it over the polynomial ring, and
produce a null homotopy for the map that is multiplication by one of the
defining equations for the complete intersection.
+-----------------------------------------------------------------------------+
|i1 : A = ZZ/101[x,y];                                                        |
+-----------------------------------------------------------------------------+
|i2 : M = cokernel random(A^3, A^{-2,-2})                                     |
|                                                                             |
|o2 = cokernel | 24x2-36xy-30y2  -22x2-29xy-24y2 |                            |
|              | -29x2+19xy+19y2 -38x2-16xy+39y2 |                            |
|              | -10x2-29xy-8y2  21x2+34xy+19y2  |                            |
|                                                                             |
|                            3                                                |
|o2 : A-module, quotient of A                                                 |
+-----------------------------------------------------------------------------+
|i3 : R = cokernel matrix {{x^3,y^4}}                                         |
|                                                                             |
|o3 = cokernel | x3 y4 |                                                      |
|                                                                             |
|                            1                                                |
|o3 : A-module, quotient of A                                                 |
+-----------------------------------------------------------------------------+
|i4 : N = prune (M**R)                                                        |
|                                                                             |
|o4 = cokernel | -49x2-45xy-27y2 -32x2+23xy-50y2 x3 x2y-44xy2-44y3 20xy2-33y3 |
|              | x2+21xy-49y2    18xy+19y2       0  38xy2-30y3     -9xy2+44y3 |
|              | -8xy-23y2       x2+16xy+17y2    0  -22y3          xy2+y3     |
|                                                                             |
|                            3                                                |
|o4 : A-module, quotient of A                                                 |
|-----------------------------------------------------------------------------|
|y4 0  0  |                                                                   |
|0  y4 0  |                                                                   |
|0  0  y4 |                                                                   |
+-----------------------------------------------------------------------------+
|i5 : C = resolution N                                                        |
|                                                                             |
|      3      8      5                                                        |
|o5 = A  <-- A  <-- A  <-- 0                                                  |
|                                                                             |
|     0      1      2      3                                                  |
|                                                                             |
|o5 : ChainComplex                                                            |
+-----------------------------------------------------------------------------+
|i6 : d = C.dd                                                                |
|                                                                             |
|          3                                                                  |
|o6 = 0 : A  <----------------------------------------------------------------|
|               | -49x2-45xy-27y2 -32x2+23xy-50y2 x3 x2y-44xy2-44y3 20xy2-33y3|
|               | x2+21xy-49y2    18xy+19y2       0  38xy2-30y3     -9xy2+44y3|
|               | -8xy-23y2       x2+16xy+17y2    0  -22y3          xy2+y3    |
|                                                                             |
|          8                                                                  |
|     1 : A  <----------------------------------------------------------------|
|               {2} | -38xy2+32y3     -9xy2+23y3      38y3       21y3       35|
|               {2} | 43xy2+2y3       36y3            -43y3      13y3       -3|
|               {3} | -36xy-4y2       29xy-44y2       36y2       -7y2       25|
|               {3} | 36x2+43xy+29y2  -29x2+44xy-19y2 -36xy-39y2 7xy-7y2    -2|
|               {3} | -43x2+43xy+27y2 -39xy+4y2       43xy-45y2  -13xy+26y2 33|
|               {4} | 0               0               x+18y      50y        -4|
|               {4} | 0               0               -46y       x+34y      -4|
|               {4} | 0               0               -16y       -19y       x+|
|                                                                             |
|          5                                                                  |
|     2 : A  <----- 0 : 3                                                     |
|               0                                                             |
|                                                                             |
|o6 : ChainComplexMap                                                         |
|-----------------------------------------------------------------------------|
|               8                                                             |
|------------- A  : 1                                                         |
| y4 0  0  |                                                                  |
| 0  y4 0  |                                                                  |
| 0  0  y4 |                                                                  |
|                                                                             |
|              5                                                              |
|------------ A  : 2                                                          |
|y3       |                                                                   |
|3y3      |                                                                   |
|y2       |                                                                   |
|5xy+10y2 |                                                                   |
|xy+22y2  |                                                                   |
|4y       |                                                                   |
|3y       |                                                                   |
|49y      |                                                                   |
+-----------------------------------------------------------------------------+
|i7 : s = nullhomotopy (x^3 * id_C)                                           |
|                                                                             |
|          8                             3                                    |
|o7 = 1 : A  <------------------------- A  : 0                                |
|               {2} | 0 x-21y -18y  |                                         |
|               {2} | 0 8y    x-16y |                                         |
|               {3} | 1 49    32    |                                         |
|               {3} | 0 -21   -3    |                                         |
|               {3} | 0 30    -6    |                                         |
|               {4} | 0 0     0     |                                         |
|               {4} | 0 0     0     |                                         |
|               {4} | 0 0     0     |                                         |
|                                                                             |
|          5                                                                  |
|     2 : A  <----------------------------------------------------------------|
|               {5} | -4  21 0 4y      -47x-46y xy+32y2      -5xy-14y2    36xy|
|               {5} | -44 19 0 -7x-37y -27x-18y -38y2        xy+7y2       9xy+|
|               {5} | 0   0  0 0       0        x2-18xy+41y2 -50xy+2y2    44xy|
|               {5} | 0   0  0 0       0        46xy+13y2    x2-34xy-24y2 43xy|
|               {5} | 0   0  0 0       0        16xy+4y2     19xy+47y2    x2-4|
|                                                                             |
|                   5                                                         |
|     3 : 0 <----- A  : 2                                                     |
|              0                                                              |
|                                                                             |
|o7 : ChainComplexMap                                                         |
|-----------------------------------------------------------------------------|
|              8                                                              |
|------------ A  : 1                                                          |
|+10y2    |                                                                   |
|36y2     |                                                                   |
|-48y2    |                                                                   |
|-30y2    |                                                                   |
|9xy-17y2 |                                                                   |
+-----------------------------------------------------------------------------+
|i8 : s*d + d*s                                                               |
|                                                                             |
|          3                    3                                             |
|o8 = 0 : A  <---------------- A  : 0                                         |
|               | x3 0  0  |                                                  |
|               | 0  x3 0  |                                                  |
|               | 0  0  x3 |                                                  |
|                                                                             |
|          8                                       8                          |
|     1 : A  <----------------------------------- A  : 1                      |
|               {2} | x3 0  0  0  0  0  0  0  |                               |
|               {2} | 0  x3 0  0  0  0  0  0  |                               |
|               {3} | 0  0  x3 0  0  0  0  0  |                               |
|               {3} | 0  0  0  x3 0  0  0  0  |                               |
|               {3} | 0  0  0  0  x3 0  0  0  |                               |
|               {4} | 0  0  0  0  0  x3 0  0  |                               |
|               {4} | 0  0  0  0  0  0  x3 0  |                               |
|               {4} | 0  0  0  0  0  0  0  x3 |                               |
|                                                                             |
|          5                              5                                   |
|     2 : A  <-------------------------- A  : 2                               |
|               {5} | x3 0  0  0  0  |                                        |
|               {5} | 0  x3 0  0  0  |                                        |
|               {5} | 0  0  x3 0  0  |                                        |
|               {5} | 0  0  0  x3 0  |                                        |
|               {5} | 0  0  0  0  x3 |                                        |
|                                                                             |
|     3 : 0 <----- 0 : 3                                                      |
|              0                                                              |
|                                                                             |
|o8 : ChainComplexMap                                                         |
+-----------------------------------------------------------------------------+
|i9 : s^2                                                                     |
|                                                                             |
|          5         3                                                        |
|o9 = 2 : A  <----- A  : 0                                                    |
|               0                                                             |
|                                                                             |
|                   8                                                         |
|     3 : 0 <----- A  : 1                                                     |
|              0                                                              |
|                                                                             |
|o9 : ChainComplexMap                                                         |
+-----------------------------------------------------------------------------+

Ways to use nullhomotopy:
=========================

  * "nullhomotopy(ChainComplexMap)"

For the programmer
==================

The object nullhomotopy, is a method function.

nullSpace -- find the null space of a mutable matrix
****************************************************

Synopsis
========

  * Usage:
        nullSpace m
  * Inputs:
      * m, a mutable matrix, over RR, or
        CC,
  * Outputs:
      * a mutable matrix, a mutable matrix whose columns
        span the null space of m

Description
===========

+-------------------------------------------+
|i1 : m = mutableMatrix {{1.p500,1},{-2,-2}}|
|                                           |
|o1 = | 1  1  |                             |
|     | -2 -2 |                             |
|                                           |
|o1 : MutableMatrix                         |
+-------------------------------------------+
|i2 : nullSpace m                           |
|                                           |
|o2 = | 1  |                                |
|     | -1 |                                |
|                                           |
|o2 : MutableMatrix                         |
+-------------------------------------------+
|i3 : precision oo                          |
|                                           |
|o3 = 500                                   |
+-------------------------------------------+

Ways to use nullSpace:
======================

  * "nullSpace(MutableMatrix)"

For the programmer
==================

The object nullSpace, is a method function.

Number -- the class of all numbers
**********************************

Types of number:
================

  * Constant
  * IndeterminateNumber -- the class of all
    indeterminate numbers
  * InexactNumber
  * InfiniteNumber -- the class of all infinite numbers
  * QQ -- the class of all rational numbers
  * ZZ -- the class of all integers

Functions and methods returning a number:
=========================================

  * "contract(Number,Number)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix

Methods that use a number:
==========================

  * "Number % GroebnerBasis" -- see %, -- a binary operator, usually
    used for remainder and reduction
  * "Number % Ideal" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "Number % RingElement" -- see %, -- a binary operator, usually
    used for remainder and reduction
  * "RingElement % Number" -- see %, -- a binary operator, usually
    used for remainder and reduction
  * "Constant * Number" -- see *, -- a binary operator, usually used
    for multiplication
  * "Matrix * Number" -- see *, -- a binary operator, usually used
    for multiplication
  * "Number * Constant" -- see *, -- a binary operator, usually used
    for multiplication
  * "Number * Matrix" -- see *, -- a binary operator, usually used
    for multiplication
  * "Number * Vector" -- see *, -- a binary operator, usually used
    for multiplication
  * "Vector * Number" -- see *, -- a binary operator, usually used
    for multiplication
  * "Constant + Number" -- see +, -- a unary or binary operator,
    usually used for addition
  * "InfiniteNumber + Number" -- see +, -- a unary or binary operator,
    usually used for addition
  * "Matrix + Number" -- see +, -- a unary or binary operator, usually
    used for addition
  * "Number + Constant" -- see +, -- a unary or binary operator,
    usually used for addition
  * "Number + InfiniteNumber" -- see +, -- a unary or binary operator,
    usually used for addition
  * "Number + Matrix" -- see +, -- a unary or binary operator, usually
    used for addition
  * "Constant - Number" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "InfiniteNumber - Number" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "Matrix - Number" -- see -, -- a unary or binary operator, usually
    used for negation or subtraction
  * "Number - Constant" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "Number - InfiniteNumber" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "Number - Matrix" -- see -, -- a unary or binary operator, usually
    used for negation or subtraction
  * "InfiniteNumber // Number" -- see //, -- a binary operator,
    usually used for quotient
  * "Matrix // Number" -- see //, -- a binary operator, usually used
    for quotient
  * "Number // InfiniteNumber" -- see //, -- a binary operator,
    usually used for quotient
  * "Number // Matrix" -- see //, -- a binary operator, usually used
    for quotient
  * "Number // RingElement" -- see //, -- a binary operator, usually
    used for quotient
  * "RingElement // Number" -- see //, -- a binary operator, usually
    used for quotient
  * "acosh(Number)" -- see acosh, -- inverse hyperbolic cosine
  * "acot(Number)" -- see acot, -- compute the inverse cotangent
  * "acoth(Number)" -- see acoth, -- compute the hyperbolic
    arctangent of a number
  * "asinh(Number)" -- see asinh, -- inverse hyperbolic sine
  * "atanh(Number)" -- see atanh, -- compute the hyperbolic
    arctangent of a number
  * "BesselJ(Number,Number)" -- see BesselJ, -- Bessel function
    of the first kind
  * "BesselJ(ZZ,Number)" -- see BesselJ, -- Bessel function of
    the first kind
  * "BesselY(Number,Number)" -- see BesselY, -- Bessel function
    of the second kind
  * "BesselY(ZZ,Number)" -- see BesselY, -- Bessel function of
    the second kind
  * "binomial(Number,Number)" -- see binomial, -- binomial
    coefficient
  * ceiling(Number) -- ceiling function
  * "clean(RR,Number)" -- see clean, -- Set to zero elements that
    are approximately zero
  * "columnAdd(MutableMatrix,ZZ,Number,ZZ)" -- see columnAdd,
    -- add a multiple of one column to another
  * "columnMult(MutableMatrix,ZZ,Number)" -- see columnMult,
    -- multiply a column by a ring element
  * "conjugate(Number)" -- see conjugate, -- complex conjugate
  * "Constant / Number" -- see Constant,
  * "Constant ^ Number" -- see Constant,
  * "Number / Constant" -- see Constant,
  * "Number ^ Constant" -- see Constant,
  * Constant == Number (missing documentation)
  * Constant ? Number (missing documentation)
  * "contract(Matrix,Number)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Number,Matrix)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Number,RingElement)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Number,Vector)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(RingElement,Number)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Vector,Number)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * floor(Number) -- floor function
  * Ideal + Number (missing documentation)
  * "ideal(Number)" -- see ideal(RingElement), --
    make an ideal
  * "imaginaryPart(Number)" -- see imaginaryPart, --
    imaginary part
  * InfiniteNumber == Number (missing documentation)
  * "integrate(Function,InfiniteNumber,Number)" -- see integrate,
    -- numerical integration
  * "integrate(Function,Number,InfiniteNumber)" -- see integrate,
    -- numerical integration
  * "integrate(Function,Number,Number)" -- see integrate, --
    numerical integration
  * "isANumber(Number)" -- see isANumber, -- whether a number
    is not not-a-number
  * isc(Number) (missing documentation)
  * "isFinite(Number)" -- see isFinite, -- whether a number is
    finite
  * isHomogeneous(Number) (missing documentation)
  * "isInfinite(Number)" -- see isInfinite, -- whether a
    number is infinite
  * "isMember(Number,Ideal)" -- see isMember(RingElement,Ideal),
    -- test membership in an ideal
  * "isUnit(Number)" -- see isUnit, -- whether a ring element is
    a unit
  * "lift(Matrix,type of Number)" -- see lift, -- lift to another
    ring
  * "Number ^ Ring" -- see lift, -- lift to another ring
  * "Number ^ RingFamily" -- see lift, -- lift to another ring
  * lift(Module,type of Number) (missing documentation)
  * lift(MutableMatrix,type of Number) (missing documentation)
  * lift(Vector,type of Number) (missing documentation)
  * List % Number (missing documentation)
  * "List / Number" -- see List / RingElement, --
    vector division
  * List // Number (missing documentation)
  * listForm(Number) (missing documentation)
  * "lngamma(Number)" -- see lngamma, -- logarithm of the Gamma
    function
  * "map(Module,Module,Number)" -- see map(Module,Module,RingElement),
    -- construct the map induced by
    multiplication by a ring element on the generators
  * Matrix / Number -- scalar division
  * "Vector / Number" -- see Matrix / Number, -- scalar
    division
  * Matrix == Number (missing documentation)
  * Matrix \\ Number (missing documentation)
  * "Matrix | Number" -- see Matrix | Matrix, -- join
    matrices horizontally
  * "Number | Matrix" -- see Matrix | Matrix, -- join
    matrices horizontally
  * "Matrix || Number" -- see Matrix || Matrix, -- join
    matrices vertically
  * "Number || Matrix" -- see Matrix || Matrix, -- join
    matrices vertically
  * "matrix(Number)" -- see matrix(RingElement),
    -- make a matrix from a ring element
  * "nextPrime(Number)" -- see nextPrime, -- compute the
    smallest prime greater than or equal to a given number
  * "norm(InfiniteNumber,Number)" -- see norm,
  * "norm(Number)" -- see norm,
  * "norm(RR,Number)" -- see norm,
  * Number * Tally (missing documentation)
  * Number * VirtualTally (missing documentation)
  * Number + Ideal (missing documentation)
  * Number == Constant (missing documentation)
  * Number == InfiniteNumber (missing documentation)
  * Number == Matrix (missing documentation)
  * Number == RingElement (missing documentation)
  * Number ? Constant (missing documentation)
  * Number \\ Matrix (missing documentation)
  * "numeric(Number)" -- see numeric, -- convert to floating
    point
  * "numeric(ZZ,Number)" -- see numeric, -- convert to floating
    point
  * part(InfiniteNumber,InfiniteNumber,Number) (missing documentation)
  * part(InfiniteNumber,ZZ,Number) (missing documentation)
  * part(ZZ,InfiniteNumber,Number) (missing documentation)
  * part(ZZ,Number) (missing documentation)
  * part(ZZ,ZZ,Number) (missing documentation)
  * "precision(Number)" -- see precision,
  * "Number _ Ring" -- see promote, -- promote to another ring
  * "quotientRemainder(Number,RingElement)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder
  * "quotientRemainder(RingElement,Number)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder
  * "realPart(Number)" -- see realPart, -- real part
  * "ring(Number)" -- see ring, -- get the associated ring of an
    object
  * RingElement == Number (missing documentation)
  * "RingElement Number" -- see RingElement Sequence,
    -- evaluation of polynomials
  * "rowAdd(MutableMatrix,ZZ,Number,ZZ)" -- see rowAdd, -- add a
    multiple of one row to another
  * "rowMult(MutableMatrix,ZZ,Number)" -- see rowMult, --
    multiply a row by a ring element
  * "substitute(Number,Ring)" -- see substitute, --
    substituting values for variables
  * "substitute(Number,RingFamily)" -- see substitute, --
    substituting values for variables
  * truncate(Number) -- round a number toward zero
  * "vector(Module,Number)" -- see vector, -- make a vector
  * "vector(Number)" -- see vector, -- make a vector

For the programmer
==================

The object Number, is a type, with ancestor class
Thing.

number -- count how many elements of a list satisfy a condition
***************************************************************

Synopsis
========

  * Usage:
        number(A, f)
  * Inputs:
      * A, a list or sequence
      * f, a boolean function
  * Outputs:
      * c, an integer, the number of elements of A that satisfy f

Description
===========

+-------------------------------+
|i1 : number(0..100, isPrime)   |
|                               |
|o1 = 25                        |
+-------------------------------+
|i2 : number(0..100, odd)       |
|                               |
|o2 = 50                        |
+-------------------------------+
|i3 : number(0..100, i -> i==17)|
|                               |
|o3 = 1                         |
+-------------------------------+

To find the first or last index of an element satisfying the condition, see
position. For all indices that match the condition, see
positions. To return the elements, rather than their indices, see
select.

+-------------------------------------+
|i4 : position((10,20,43,105,6), odd) |
|                                     |
|o4 = 2                               |
+-------------------------------------+
|i5 : positions((10,20,43,105,6), odd)|
|                                     |
|o5 = {2, 3}                          |
|                                     |
|o5 : List                            |
+-------------------------------------+
|i6 : select((10,20,43,105,6), odd)   |
|                                     |
|o6 = (43, 105)                       |
|                                     |
|o6 : Sequence                        |
+-------------------------------------+

See also
========

  * all -- whether all elements satisfy a specified condition
  * any -- whether any elements satisfy a specified condition
  * commonest -- the most common elements of a list or tally
  * position -- the first element of a list satisfying a
    condition
  * positions -- which elements of a list satisfy a condition
  * same -- whether everything in a list is the same
  * select -- select from a list, hash table, or string
  * tally -- tally the elements of a list, sequence, array, or
    string
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

For the programmer
==================

The object number, is a function closure.

NumberedVerticalList -- a type of visible self-initializing list that prints vertically
***************************************************************************************

Synopsis
========

  * Usage:
        NumberedVerticalList x
  * Inputs:
      * x, a list,
  * Outputs:
      * a numbered vertical list,

Description
===========

All operations on lists apply to numbered vertical lists, since they inherit
from the type VisibleList.  The only difference is the way
that a numbered vertical list is displayed vertically, with index numbers
labelling the entries.
+--------------------------------+
|i1 : a .. e                     |
|                                |
|o1 = (a, b, c, d, e)            |
|                                |
|o1 : Sequence                   |
+--------------------------------+
|i2 : v = NumberedVerticalList oo|
|                                |
|o2 = {0 => a}                   |
|     {1 => b}                   |
|     {2 => c}                   |
|     {3 => d}                   |
|     {4 => e}                   |
|                                |
|o2 : NumberedVerticalList       |
+--------------------------------+
|i3 : v_1                        |
|                                |
|o3 = b                          |
|                                |
|o3 : Symbol                     |
+--------------------------------+
|i4 : length v                   |
|                                |
|o4 = 5                          |
+--------------------------------+
One may get a normal list back from a vertical list as follows.
+--------------------+
|i5 : toList v       |
|                    |
|o5 = {a, b, c, d, e}|
|                    |
|o5 : List           |
+--------------------+

See also
========

  * VerticalList -- a type of visible self-initializing
    list that prints vertically

Functions and methods returning a numbered vertical list:
=========================================================

  * methods -- list methods

For the programmer
==================

The object NumberedVerticalList, is a self initializing type,
with ancestor classes
VerticalList, < List < VisibleList
< BasicList < Thing.

numColumns(Matrix) -- number of columns in a matrix or mutable matrix
*********************************************************************

Synopsis
========

  * Function: numColumns,
  * Usage:
        numColumns m
  * Inputs:
      * m
  * Outputs:
      * the number of columns in m

Ways to use this method:
========================

  * numColumns(Matrix) -- number of columns in a
    matrix or mutable matrix
  * "numColumns(MutableMatrix)"

numerator -- numerator of a fraction
************************************

Synopsis
========

  * Usage:
        numerator x
  * Inputs:
      * x, a fraction
  * Outputs:
      * the numerator of x

Description
===========

+--------------------+
|i1 : numerator (4/6)|
|                    |
|o1 = 2              |
+--------------------+

+-------------------------------+
|i2 : R = frac(ZZ[x,y]);        |
+-------------------------------+
|i3 : numerator((x+2*y-3)/(x-y))|
|                               |
|o3 = x + 2y - 3                |
|                               |
|o3 : ZZ[x..y]                  |
+-------------------------------+

numerator also works with Hilbert series.
+---------------------------------+
|i4 : R = QQ[a..d]/(a^2,b^2,c^3); |
+---------------------------------+
|i5 : hf = hilbertSeries R        |
|                                 |
|           2    3    4     5    7|
|     1 - 2T  - T  + T  + 2T  - T |
|o5 = ----------------------------|
|                      4          |
|               (1 - T)           |
|                                 |
|o5 : Expression of class Divide  |
+---------------------------------+
|i6 : numerator hf                |
|                                 |
|           2    3    4     5    7|
|o6 = 1 - 2T  - T  + T  + 2T  - T |
|                                 |
|o6 : ZZ[T]                       |
+---------------------------------+

For a Laurent polynomial in a ring with inverses of variables, it gives the
result after clearing all the denominators in each of the terms by multiplying
by a suitable monomial.

+---------------------------------------------------------+
|i7 : R = QQ[x,y,z,Inverses => true, MonomialOrder => Lex]|
|                                                         |
|o7 = R                                                   |
|                                                         |
|o7 : PolynomialRing                                      |
+---------------------------------------------------------+
|i8 : numerator (x*y^-1+y*z^-2+1+y^-1*z^-1)               |
|                                                         |
|        2    2      2                                    |
|o8 = x*z  + y  + y*z  + z                                |
|                                                         |
|o8 : R                                                   |
+---------------------------------------------------------+

See also
========

  * denominator -- denominator of a fraction
  * fraction fields
  * hilbertSeries -- compute the Hilbert series

Ways to use numerator:
======================

  * "numerator(Divide)"

For the programmer
==================

The object numerator, is a method function.

numeric -- convert to floating point
************************************

Synopsis
========

  * Usage:
        numeric x
        numeric(prec,x)
        numeric_prec x
  * Inputs:
      * x
      * prec, an integer, the number of bits of precision to use in
        the computation
  * Outputs:
      * the expression obtained from x by converting the integers, rational
        numbers, and symbolic constants within it to double floating point
        numbers.

Description
===========

+-------------------------------------------------------------------+
|i1 : x = {1,2/3,pi}                                                |
|                                                                   |
|         2                                                         |
|o1 = {1, -, pi}                                                    |
|         3                                                         |
|                                                                   |
|o1 : List                                                          |
+-------------------------------------------------------------------+
|i2 : numeric oo                                                    |
|                                                                   |
|o2 = {1, .666667, 3.14159}                                         |
|                                                                   |
|o2 : List                                                          |
+-------------------------------------------------------------------+
|i3 : numeric_200 pi                                                |
|                                                                   |
|o3 = 3.141592653589793238462643383279502884197169399375105820974944|
|                                                                   |
|o3 : RR (of precision 200)                                         |
+-------------------------------------------------------------------+
|i4 : numeric_100 oo                                                |
|                                                                   |
|o4 = 3.141592653589793238462643383279                              |
|                                                                   |
|o4 : RR (of precision 100)                                         |
+-------------------------------------------------------------------+

See also
========

  * RR -- the class of all real numbers
  * CC -- the class of all complex numbers
  * Constant

Ways to use numeric:
====================

  * "numeric(CC)"
  * "numeric(Constant)"
  * "numeric(IndeterminateNumber)"
  * "numeric(InfiniteNumber)"
  * "numeric(InfiniteNumber,Constant)"
  * "numeric(Matrix)"
  * "numeric(Number)"
  * "numeric(RR)"
  * "numeric(RRi)"
  * "numeric(Vector)"
  * "numeric(VisibleList)"
  * "numeric(ZZ,CC)"
  * "numeric(ZZ,Constant)"
  * "numeric(ZZ,IndeterminateNumber)"
  * "numeric(ZZ,InfiniteNumber)"
  * "numeric(ZZ,Matrix)"
  * "numeric(ZZ,Number)"
  * "numeric(ZZ,RRi)"
  * "numeric(ZZ,Vector)"
  * "numeric(ZZ,VisibleList)"

For the programmer
==================

The object numeric, is a method function.

numericInterval -- converts to an interval
******************************************

Synopsis
========

  * Usage:
        I = numericInterval(c)
        I = numericInterval(prec,c)
  * Inputs:
      * c, an instance of the type Constant,
      * prec, an integer,
  * Outputs:
      * I, a real interval,

Description
===========

Constructs an interval containing c of either the defaultPrecision,
or precision prec

See also
========

  * span(List) -- construct smallest interval
  * span(Sequence) -- construct smallest interval
  * interval -- construct an interval
  * toRRi -- construct an interval

Ways to use numericInterval:
============================

  * "numericInterval(Constant)"
  * "numericInterval(ZZ,Constant)"

For the programmer
==================

The object numericInterval, is a method function.

numgens -- the number of generators
***********************************

Ways to use numgens:
====================

  * numgens(CoherentSheaf) (Varieties) -- the
    number of generators of the underlying module
  * numgens(Ideal) -- number of generators of an
    ideal
  * numgens(Module) -- number of generators of a
    module
  * numgens(Monoid) -- number of generators of a
    monoid
  * "numgens(EngineRing)" -- see numgens(Ring), --
    number of generators of a polynomial ring
  * "numgens(FractionField)" -- see numgens(Ring), --
    number of generators of a polynomial ring
  * "numgens(MonomialIdeal)" -- see numgens(Ring), --
    number of generators of a polynomial ring
  * "numgens(PolynomialRing)" -- see numgens(Ring), --
    number of generators of a polynomial ring
  * "numgens(QuotientRing)" -- see numgens(Ring), --
    number of generators of a polynomial ring
  * numgens(Ring) -- number of generators of a
    polynomial ring

For the programmer
==================

The object numgens, is a method function.

numgens(Ideal) -- number of generators of an ideal
**************************************************

Synopsis
========

  * Function: numgens,
  * Usage:
        numgens I
  * Inputs:
      * I
  * Outputs:
      * an integer, number of generators of I

Description
===========

In Macaulay2, each ideal comes equipped with a matrix of generators.  It is the
number of columns of this matrix that is returned.  If the ideal is
homogeneous, this may or may not be the number of minimal generators.
+-------------------------------------------+
|i1 : R = QQ[a..d];                         |
+-------------------------------------------+
|i2 : I = ideal(a^2-b*d, a^2-b*d, c^2, d^2);|
|                                           |
|o2 : Ideal of R                            |
+-------------------------------------------+
|i3 : numgens I                             |
|                                           |
|o3 = 4                                     |
+-------------------------------------------+

In order to find a more efficient set of generators, use mingens,
or trim.
+---------------------+
|i4 : mingens I       |
|                     |
|o4 = | d2 c2 a2-bd | |
|                     |
|             1      3|
|o4 : Matrix R  <-- R |
+---------------------+
|i5 : numgens trim I  |
|                     |
|o5 = 3               |
+---------------------+

See also
========

  * mingens -- minimal generator matrix
  * trim -- minimize generators and relations
  * generators -- provide matrix or list of generators

Ways to use this method:
========================

  * numgens(Ideal) -- number of generators of an
    ideal

numgens(Module) -- number of generators of a module
***************************************************

Synopsis
========

  * Function: numgens,
  * Usage:
        numgens M
  * Inputs:
      * M
  * Outputs:
      * an integer, number of generators of M

Description
===========

In Macaulay2, each module comes equipped with a matrix of generators.  It is
the number of columns of this matrix which is returned.  If the module is
graded, this may or may not be the number of minimal generators.
+------------------------------------+
|i1 : R = QQ[a..d];                  |
+------------------------------------+
|i2 : M = ker vars R                 |
|                                    |
|o2 = image {1} | -b 0  -c 0  0  -d ||
|           {1} | a  -c 0  0  -d 0  ||
|           {1} | 0  b  a  -d 0  0  ||
|           {1} | 0  0  0  c  b  a  ||
|                                    |
|                             4      |
|o2 : R-module, submodule of R       |
+------------------------------------+
|i3 : generators M                   |
|                                    |
|o3 = {1} | -b 0  -c 0  0  -d |      |
|     {1} | a  -c 0  0  -d 0  |      |
|     {1} | 0  b  a  -d 0  0  |      |
|     {1} | 0  0  0  c  b  a  |      |
|                                    |
|             4      6               |
|o3 : Matrix R  <-- R                |
+------------------------------------+
|i4 : numgens M                      |
|                                    |
|o4 = 6                              |
+------------------------------------+
The number of generators of a free module is its rank.
+-----------------+
|i5 : numgens R^10|
|                 |
|o5 = 10          |
+-----------------+

See also
========

  * generators -- provide matrix or list of generators
  * trim -- minimize generators and relations
  * prune -- prune, e.g., compute a minimal presentation
  * mingens -- minimal generator matrix
  * kernel -- kernel of a ringmap, matrix, or chain complex
  * vars -- variables

Ways to use this method:
========================

  * numgens(Module) -- number of generators of a
    module

numgens(Monoid) -- number of generators of a monoid
***************************************************

Synopsis
========

  * Function: numgens,
  * Usage:
        numgens M
  * Inputs:
      * M
  * Outputs:
      * an integer, number of generators of M

Description
===========

+---------------------------+
|i1 : M = monoid[x_1..x_10];|
+---------------------------+
|i2 : numgens M             |
|                           |
|o2 = 10                    |
+---------------------------+

See also
========

  * monoid -- make or retrieve a monoid

Ways to use this method:
========================

  * numgens(Monoid) -- number of generators of a
    monoid

numgens(Ring) -- number of generators of a polynomial ring
**********************************************************

Synopsis
========

  * Function: numgens,
  * Usage:
        numgens R
  * Inputs:
      * R
  * Outputs:
      * an integer, number of generators of R over the coefficient
        ring

Description
===========

If the ring R is a fraction ring or a (quotient of a) polynomial ring, the
number returned is the number of generators of R over the coefficient ring. In
all other cases, the number of generators is zero.
+-------------------+
|i1 : numgens ZZ    |
|                   |
|o1 = 0             |
+-------------------+
|i2 : A = ZZ[a,b,c];|
+-------------------+
|i3 : numgens A     |
|                   |
|o3 = 3             |
+-------------------+
|i4 : KA = frac A   |
|                   |
|o4 = KA            |
|                   |
|o4 : FractionField |
+-------------------+
|i5 : numgens KA    |
|                   |
|o5 = 3             |
+-------------------+
If the ring is polynomial ring over another polynomial ring, then only the
outermost variables are counted.
+-----------------+
|i6 : B = A[x,y]; |
+-----------------+
|i7 : numgens B   |
|                 |
|o7 = 2           |
+-----------------+
|i8 : C = KA[x,y];|
+-----------------+
|i9 : numgens C   |
|                 |
|o9 = 2           |
+-----------------+
In this case, use the CoefficientRing, option to
generators, to obtain the complete set of generators.
+--------------------------------------------+
|i10 : g = generators(B, CoefficientRing=>ZZ)|
|                                            |
|o10 = {x, y, a, b, c}                       |
|                                            |
|o10 : List                                  |
+--------------------------------------------+
|i11 : #g                                    |
|                                            |
|o11 = 5                                     |
+--------------------------------------------+
Galois fields created using GF, have zero generators, but their
underlying polynomial ring has one generators.
+---------------------------+
|i12 : K = GF(9,Variable=>a)|
|                           |
|o12 = K                    |
|                           |
|o12 : GaloisField          |
+---------------------------+
|i13 : numgens K            |
|                           |
|o13 = 1                    |
+---------------------------+
|i14 : R = ambient K        |
|                           |
|o14 = R                    |
|                           |
|o14 : QuotientRing         |
+---------------------------+
|i15 : numgens R            |
|                           |
|o15 = 1                    |
+---------------------------+

See also
========

  * generators -- provide matrix or list of generators
  * minimalPresentation -- compute a minimal
    presentation
  * GF -- make a finite field
  * ambient -- ambient free module of a subquotient, or ambient
    ring

Ways to use this method:
========================

  * "numgens(EngineRing)"
  * "numgens(FractionField)"
  * "numgens(MonomialIdeal)"
  * "numgens(PolynomialRing)"
  * "numgens(QuotientRing)"
  * numgens(Ring) -- number of generators of a
    polynomial ring

numRows(Matrix) -- number of rows in a matrix or mutable matrix
***************************************************************

Synopsis
========

  * Function: numRows,
  * Usage:
        numRows m
  * Inputs:
      * m
  * Outputs:
      * the number of rows in m

Ways to use this method:
========================

  * numRows(Matrix) -- number of rows in a matrix
    or mutable matrix
  * "numRows(MutableMatrix)"

odd -- tell whether an integer is odd
*************************************

Description
===========

odd x -- returns true or false, tells whether x is an odd integer.

See also even.

For the programmer
==================

The object odd, is a function closure.

of -- a keyword
***************

Description
===========

of -- a keyword used with new.

For the programmer
==================

The object of, is a keyword.

ofClass -- English phrases for types
************************************

Synopsis
========

  * Usage:
        ofClass T
  * Inputs:
      * T, a type, an immutable type, or a
        list, of types
  * Outputs:
      * a sequence, an English phrase in hypertext, using a
        synonym for each type, together with appropriate indefinite articles,
        and, if a list is presented, the word or as a conjunction at the end

Description
===========

When viewed in html, words in the phrase hot link(s) to the documentation
node(s) for the class(es).

+-----------------------------------------------------------------------------+
|i1 : ofClass class 3                                                         |
|                                                                             |
|o1 = an "integer"                                                            |
+-----------------------------------------------------------------------------+
|i2 : peek oo                                                                 |
|                                                                             |
|o2 = SPAN{"an ", TO2{Macaulay2Doc :: ZZ, "integer"}}                         |
+-----------------------------------------------------------------------------+
|i3 : ofClass Ring                                                            |
|                                                                             |
|o3 = a "ring"                                                                |
+-----------------------------------------------------------------------------+
|i4 : needsPackage "Text"                                                     |
|                                                                             |
|o4 = Text                                                                    |
|                                                                             |
|o4 : Package                                                                 |
+-----------------------------------------------------------------------------+
|i5 : SPAN ofClass {HashTable, ProjectiveVariety}                             |
|                                                                             |
|o5 = a "hash table" or a "projective variety"                                |
+-----------------------------------------------------------------------------+
|i6 : document { Key => foo, "We may need ", ofClass ZZ, " and ", ofClass     |
|                                                                             |
|o6 = HashTable{Description => (We may need , an "integer",  and , a "hash    |
|               DocumentTag => User :: foo                                    |
|               "filename" => currentString                                   |
|               Key => foo                                                    |
|               "linenum" => 7                                                |
|                                                                             |
|o6 : HashTable                                                               |
|-----------------------------------------------------------------------------|
|HashTable, "." }                                                             |
|                                                                             |
| table", .)}                                                                 |
+-----------------------------------------------------------------------------+
|i7 : help foo                                                                |
|                                                                             |
|o7 = foo                                                                     |
|     ***                                                                     |
|                                                                             |
|     Description                                                             |
|     ===========                                                             |
|                                                                             |
|     We may need an "integer" and a "hash table".                            |
|                                                                             |
|     For the programmer                                                      |
|     ==================                                                      |
|                                                                             |
|     The object "foo" is a "symbol".                                         |
+-----------------------------------------------------------------------------+

Ways to use ofClass:
====================

  * "ofClass(ImmutableType)"
  * "ofClass(List)"
  * "ofClass(Type)"

For the programmer
==================

The object ofClass, is a method function.

on -- trace a function each time it's run
*****************************************

Synopsis
========

  * Usage:
        on f
  * Inputs:
      * f, a function,
  * Optional inputs,:
      * CallLimit => an integer, default value 100000, the maximum
        number of times to permit the function f to be called
      * Name => a string, default value null, the name to use
        for the function, in case f is an anonymous function (not assigned to a
        global variable)
      * GenerateAssertions => a Boolean value, default value
        false, whether to print assertion statements that can be used as input
        to Macaulay2 to check the behavior of the function remains the same.
        Arguments and values are prepared with toExternalString,
        failure of which is silently ignored.
  * Outputs:
      * a function, a new function that returns the same
        values that f would have returned, but has a few side effects useful
        for debugging: upon entry, it prints its arguments, and upon exit it
        prints its return values.  The display includes the name of f, a
        sequence number in parentheses that tells how many times the function
        has been called, and a number in brackets that gives the nesting
        (recursion) depth. The sequence number allows the entry and exit
        reports to be connected.

Description
===========

Ideally, this function would replace f, i.e., we would write f = on f.
Unfortunately, all the pre-installed system functions are write-protected;
fortunately, their methods are not, and can be replaced.

+-----------------------------------------------------------------------------+
|i1 : ker Matrix := on(lookup(ker,Matrix),GenerateAssertions=>true,Name=>"ker |
|-----------------------------------------------------------------------------|
|");                                                                          |
+-----------------------------------------------------------------------------+
|i2 : f = x -> kernel (x|x);                                                  |
+-----------------------------------------------------------------------------+
|i3 : R = QQ[a..c];                                                           |
+-----------------------------------------------------------------------------+
|i4 : f vars R                                                                |
|-- ker (1) called with OptionTable: OptionTable{SubringLimit => infinity}    |
|-- ker (1) returned CacheFunction: -*a cache function*-                      |
|-- ker (1) called with Matrix: | a b c a b c |                               |
|-- ker (1) returned Module: image {1} | -1 0  0  -b 0  -c |                  |
|--                                {1} | 0  -1 0  a  -c 0  |                  |
|--                                {1} | 0  0  -1 0  b  a  |                  |
|--                                {1} | 1  0  0  0  0  0  |                  |
|--                                {1} | 0  1  0  0  0  0  |                  |
|--                                {1} | 0  0  1  0  0  0  |                  |
|assert( ker(map(R^1,R^{6:{-1}},{{a, b, c, a, b, c}})) === (image(map(R^{6:{-1|
|                                                                             |
|o4 = image {1} | -1 0  0  -b 0  -c |                                         |
|           {1} | 0  -1 0  a  -c 0  |                                         |
|           {1} | 0  0  -1 0  b  a  |                                         |
|           {1} | 1  0  0  0  0  0  |                                         |
|           {1} | 0  1  0  0  0  0  |                                         |
|           {1} | 0  0  1  0  0  0  |                                         |
|                                                                             |
|                             6                                               |
|o4 : R-module, submodule of R                                                |
|-----------------------------------------------------------------------------|
|}},R^{3:{-1}, 3:{-2}},{{-1, 0, 0, -b, 0, -c}, {0, -1, 0, a, -c, 0}, {0, 0,   |
|-----------------------------------------------------------------------------|
|-1, 0, b, a}, {1, 0, 0, 0, 0, 0}, {0, 1, 0, 0, 0, 0}, {0, 0, 1, 0, 0, 0}}))))|
+-----------------------------------------------------------------------------+

See also
========

  * lookup -- look up methods

For the programmer
==================

The object on, is a function closure.

OneExpression -- the class all one expressions
**********************************************

Description
===========

OneExpression a type of Expression, of which there is just
one instance, an expression representing the number 1.

For the programmer
==================

The object OneExpression, is a type, with
ancestor classes Holder, < Expression <
BasicList < Thing.

oo -- the last output value
***************************

Description
===========

oo -- denotes the value of the expression on the previous output line.

See also
========

  * oo -- the last output value
  * ooo -- the next to the last output value
  * oooo -- the third to the last output value

For the programmer
==================

The object oo, is a symbol.

ooo -- the next to the last output value
****************************************

Description
===========

ooo -- denotes the value of the expression on the output line two lines above.

See also
========

  * oo -- the last output value
  * oooo -- the third to the last output value

For the programmer
==================

The object ooo, is a symbol.

oooo -- the third to the last output value
******************************************

Description
===========

oooo -- denotes the value of the expression on the output line three lines
above.

See also
========

  * oo -- the last output value
  * ooo -- the next to the last output value

For the programmer
==================

The object oooo, is a symbol.

openDatabase -- open a database file
************************************

Description
===========

openDatabase "filename" -- open a database file with the given file name.

Ways to use openDatabase:
=========================

  * "openDatabase(String)"

For the programmer
==================

The object openDatabase, is a compiled function.

openDatabaseOut -- open a database file for writing
***************************************************

Description
===========

openDatabaseOut "filename" -- open a database file with the given file name,
and allow changes to be made to it.

Ways to use openDatabaseOut:
============================

  * "openDatabaseOut(String)"

For the programmer
==================

The object openDatabaseOut, is a compiled function.

openFiles -- list the open files
********************************

Description
===========

openFiles() produces a list of all currently open files.

See also
========

  * File -- the class of all files

For the programmer
==================

The object openFiles, is a compiled function.

openIn(String) -- open an input file
************************************

Synopsis
========

  * Function: openIn,
  * Usage:
        openIn fn
  * Inputs:
      * fn
  * Outputs:
      * an open input file whose filename is fn. Filenames starting with ! or
        with $ are treated specially, see openInOut.

Description
===========

+----------------------------------------+
|i1 : "test-file" << "hi there" << close;|
+----------------------------------------+
|i2 : g = openIn "test-file"             |
|                                        |
|o2 = test-file                          |
|                                        |
|o2 : File                               |
+----------------------------------------+
|i3 : fileLength g                       |
|                                        |
|o3 = 8                                  |
+----------------------------------------+
|i4 : atEndOfFile g                      |
|                                        |
|o4 = false                              |
+----------------------------------------+
|i5 : read g                             |
|                                        |
|o5 = hi there                           |
+----------------------------------------+
|i6 : atEndOfFile g                      |
|                                        |
|o6 = true                               |
+----------------------------------------+
|i7 : close g                            |
|                                        |
|o7 = test-file                          |
|                                        |
|o7 : File                               |
+----------------------------------------+
|i8 : removeFile "test-file"             |
+----------------------------------------+

A filename starting with ~/ will have the tilde replaced by the user's home
directory.

See also
========

  * openOut -- open an output file
  * openOutAppend -- open an output file for
    appending
  * openInOut -- open an input output file
  * fileLength -- the length of a file
  * read -- read from a file
  * close -- close a file
  * atEndOfFile -- test for end of file
  * File << Thing -- print to a file

Ways to use this method:
========================

  * openIn(String) -- open an input file

openInOut -- open an input output file
**************************************

Synopsis
========

  * Usage:
        openInOut f
  * Inputs:
      * f, a string, or a file,
  * Outputs:
      * an open input output file

Description
===========

There are various options for the argument f.

  * a string not starting with ! or $: the string is taken as the name of an
    input output file to open.  For example, in Unix, it might be a named pipe.
    A filename starting with ~/ will have the tilde replaced by the user's home
    directory.
  * a string of the form "!cmd": the command cmd will be started, and two pipes
    will be opened, connected to its standard input and standard output file
    descriptors. Warning: pipes hold only 4096 bites, so if you write more than
    that to the resulting input output file (as input for the command) without
    reading any data, you may block while the command is blocked waiting to
    write more output; in this case, Macaulay2 will appear to hang.
  * a string of the form "$hostname:service": a connection will be made to the
    specified service at the specified host.  If the service port is omitted,
    along with the colon, then port 2500 is used.  If the hostname is omitted,
    an incoming connection will be waited for.
  * a listener created previously by openListener,:
    a new connection will be created.  To avoid
    blocking the Macaulay2 process while waiting for the incoming connection,
    use isReady.

In order to open a socket successfully, there must be a process accepting
connections for the desired service on the specified host.

The various forms listed above can be used also with all other input output
operations that open files, such as openIn,
openOut, get, and <<, with data
transfer possible only in the direction specified.  A possibly confusing
asymmetry is that with openIn "!foo" or with get "!foo" the standard input of
the command foo is closed, but with openOut "!foo" the standard output of the
command foo is connected to the standard output of the parent Macaulay2
process.

See also
========

  * openIn -- open an input file
  * openOut -- open an output file
  * openListener -- open a port for listening

Ways to use openInOut:
======================

  * "openInOut(File)"
  * "openInOut(String)"

For the programmer
==================

The object openInOut, is a compiled function.

openListener(String) -- open a port for listening
*************************************************

Synopsis
========

  * Function: openListener,
  * Usage:
        f = openListener s
  * Inputs:
      * s, of the form "$interface:port".  Both parts are optional.  If the
        port is omitted, the colon is optional.
  * Outputs:
      * f, an open listener on the specified interface of the local host at the
        specified service port. If the port is omitted, it is taken to be port
        2500.  If the interface is omitted, the listener accepts connections on
        all interfaces.

Description
===========

Use openInOut f to accept an incoming connection on the listener, returning a
new input output file that serves as the connection.  The function
isReady, can be used to determine whether an incoming
connection has arrived, without blocking.

See also
========

  * openInOut -- open an input output file
  * isReady -- whether a file has data available for
    reading

Ways to use this method:
========================

  * openListener(String) -- open a port for
    listening

openOut(String) -- open an output file
**************************************

Synopsis
========

  * Function: openOut,
  * Usage:
        openOut fn
  * Inputs:
      * fn
  * Outputs:
      * an open output file whose filename is fn. Filenames starting with ! or
        with $ are treated specially, see openInOut.

Description
===========

+----------------------------+
|i1 : g = openOut "test-file"|
|                            |
|o1 = test-file              |
|                            |
|o1 : File                   |
+----------------------------+
|i2 : g << "hi there"        |
|                            |
|o2 = test-file              |
|                            |
|o2 : File                   |
+----------------------------+
|i3 : g << close             |
|                            |
|o3 = test-file              |
|                            |
|o3 : File                   |
+----------------------------+
|i4 : get "test-file"        |
|                            |
|o4 = hi there               |
+----------------------------+
|i5 : removeFile "test-file" |
+----------------------------+

A filename starting with ~/ will have the tilde replaced by the user's home
directory.

See also
========

  * openIn -- open an input file
  * openInOut -- open an input output file
  * openOutAppend -- open an output file for
    appending
  * get -- get the contents of a file
  * removeFile -- remove a file
  * close -- close a file
  * File << Thing -- print to a file

Ways to use this method:
========================

  * openOut(String) -- open an output file

openOutAppend(String) -- open an output file for appending
**********************************************************

Synopsis
========

  * Function: openOutAppend,
  * Usage:
        openOutAppend fn
  * Inputs:
      * fn
  * Outputs:
      * an open output file whose filename is fn

Description
===========

+-------------------------------------+
|i1 : g = openOut "test-file"         |
|                                     |
|o1 = test-file                       |
|                                     |
|o1 : File                            |
+-------------------------------------+
|i2 : g << "hi there" << endl << close|
|                                     |
|o2 = test-file                       |
|                                     |
|o2 : File                            |
+-------------------------------------+
|i3 : h = openOutAppend "test-file"   |
|                                     |
|o3 = test-file                       |
|                                     |
|o3 : File                            |
+-------------------------------------+
|i4 : h << "ho there" << endl << close|
|                                     |
|o4 = test-file                       |
|                                     |
|o4 : File                            |
+-------------------------------------+
|i5 : get "test-file"                 |
|                                     |
|o5 = hi there                        |
|     ho there                        |
+-------------------------------------+
|i6 : removeFile "test-file"          |
+-------------------------------------+

A filename starting with ~/ will have the tilde replaced by the user's home
directory.

See also
========

  * openIn -- open an input file
  * openInOut -- open an input output file
  * openOut -- open an output file
  * File -- the class of all files
  * get -- get the contents of a file
  * removeFile -- remove a file
  * File << Thing -- print to a file

Ways to use this method:
========================

  * openOutAppend(String) -- open an output
    file for appending

Option -- the class of all key-value pairs K => V
*************************************************

Description
===========

Such pairs are used as optional arguments for functions.

+---------------------+
|i1 : o = Limit => 5  |
|                     |
|o1 = Limit => 5      |
|                     |
|o1 : Option          |
+---------------------+
|i2 : peek o          |
|                     |
|o2 = Option{Limit, 5}|
+---------------------+

There is also a way to make new hash tables, from lists of
key-value pairs.

+---------------------------------------------+
|i3 : ht = new HashTable from {a => 5, b => 7}|
|                                             |
|o3 = HashTable{a => 5}                       |
|               b => 7                        |
|                                             |
|o3 : HashTable                               |
+---------------------------------------------+
|i4 : keys ht                                 |
|                                             |
|o4 = {a, b}                                  |
|                                             |
|o4 : List                                    |
+---------------------------------------------+
|i5 : values ht                               |
|                                             |
|o5 = {5, 7}                                  |
|                                             |
|o5 : List                                    |
+---------------------------------------------+
|i6 : pairs ht                                |
|                                             |
|o6 = {(a, 5), (b, 7)}                        |
|                                             |
|o6 : List                                    |
+---------------------------------------------+

These pairs are implemented as lists, so that if z is x => y, then x is z#0 and
y is z#1.

+-----------+
|i7 : o#0   |
|           |
|o7 = Limit |
|           |
|o7 : Symbol|
+-----------+
|i8 : o#1   |
|           |
|o8 = 5     |
+-----------+

See also
========

  * new HashTable from List -- make a hash
    table from a list
  * Thing => Thing -- produce an Option
  * options -- get options

Functions and methods returning an option:
==========================================

  * "Thing => Thing" -- see =>, -- produce an Option

Methods that use an option:
===========================

  * "directSum(Option)" -- see directSum, -- direct sum of
    modules or maps
  * "Option ++ Option" -- see directSum, -- direct sum of
    modules or maps
  * "installAssignmentMethod(Symbol,HashTable,HashTable,Option)" -- see
    installAssignmentMethod, -- install methods
    assignment to the value of an operator
  * "installAssignmentMethod(Symbol,HashTable,Option)" -- see
    installAssignmentMethod, -- install methods
    assignment to the value of an operator
  * Option ** Option (missing documentation)
  * Option ? Option (missing documentation)
  * "package(Option)" -- see package, -- get containing package
  * "substitute(Ideal,Option)" -- see substitute, --
    substituting values for variables
  * "substitute(Matrix,Option)" -- see substitute, --
    substituting values for variables
  * "substitute(Module,Option)" -- see substitute, --
    substituting values for variables
  * "substitute(RingElement,Option)" -- see substitute, --
    substituting values for variables
  * "substitute(Vector,Option)" -- see substitute, --
    substituting values for variables

For the programmer
==================

The object Option, is a type, with ancestor classes
BasicList < Thing.

options -- get options
**********************

See also
========

  * Option -- the class of all key-value pairs K => V

Ways to use options:
====================

  * options(Command) -- get optional arguments and
    default values of functions and methods
  * "options(Function)" -- see options(Command), --
    get optional arguments and default values of functions and methods
  * "options(Sequence)" -- see options(Command), --
    get optional arguments and default values of functions and methods
  * "options(ZZ)" -- see options(Command), -- get
    optional arguments and default values of functions and methods
  * options(Monoid) -- get values used for optional
    arguments
  * "options(PolynomialRing)" -- see options(Monoid),
    -- get values used for optional arguments
  * "options(QuotientRing)" -- see options(Monoid),
    -- get values used for optional arguments
  * "options(Ring)" -- see options(Monoid), -- get
    values used for optional arguments
  * options(Package)

For the programmer
==================

The object options, is a method function with a single argument.

options(Command) -- get optional arguments and default values of functions and methods
**************************************************************************************

Synopsis
========

  * Function: options,
  * Usage:
        options f
  * Inputs:
      * f, a command, a function, a
        sequence, or an integer,
  * Outputs:
      * an option table, or a Boolean value,

Description
===========

The keys of the output are the names of the optional arguments accepted by the
function f and the values are the corresponding default values; or true,
if the function accepts arbitrary options and provides no default
values.

+------------------------------------------------+
|i1 : options res                                |
|                                                |
|o1 = OptionTable{DegreeLimit => null           }|
|                 FastNonminimal => false        |
|                 HardDegreeLimit => {}          |
|                 LengthLimit => infinity        |
|                 PairLimit => infinity          |
|                 ParallelizeByDegree => false   |
|                 SortStrategy => 0              |
|                 StopBeforeComputation => false |
|                 Strategy => null               |
|                 SyzygyLimit => infinity        |
|                                                |
|o1 : OptionTable                                |
+------------------------------------------------+
|i2 : options codim                              |
+------------------------------------------------+
|i3 : options(codim, Ideal)                      |
|                                                |
|o3 = OptionTable{Generic => false}              |
|                                                |
|o3 : OptionTable                                |
+------------------------------------------------+
|i4 : methods intersect                          |
|                                                |
|o4 = {0 => (intersect, Ideal)         }         |
|     {1 => (intersect, RRi, RRi)      }         |
|     {2 => (intersect, RRi)           }         |
|     {3 => (intersect, Ideal, Ideal)  }         |
|     {4 => (intersect, Module)        }         |
|     {5 => (intersect, Set, Set)      }         |
|     {6 => (intersect, Module, Module)}         |
|     {7 => (intersect, Sequence)      }         |
|     {8 => (intersect, List)          }         |
|                                                |
|o4 : NumberedVerticalList                       |
+------------------------------------------------+
|i5 : options 0                                  |
|                                                |
|o5 = OptionTable{MinimalGenerators => true}     |
|                 Strategy => null               |
|                                                |
|o5 : OptionTable                                |
+------------------------------------------------+

See also
========

  * methods -- list methods

Ways to use this method:
========================

  * options(Command) -- get optional arguments and
    default values of functions and methods
  * "options(Function)"
  * "options(Sequence)"
  * "options(ZZ)"

options(Monoid) -- get values used for optional arguments
*********************************************************

Synopsis
========

  * Function: options,

Description
===========

options A -- returns the options used when the polynomial ring or monoid A was
created.

Ways to use this method:
========================

  * options(Monoid) -- get values used for optional
    arguments
  * "options(PolynomialRing)"
  * "options(QuotientRing)"
  * "options(Ring)"

OptionTable -- the class of hash tables for optional arguments
**************************************************************

See also
========

  * >> -- a binary operator, uses include bit shifting, or attaching
    optional inputs to functions

Types of option table:
======================

  * GroebnerBasisOptions

Functions and methods returning an option table:
================================================

  * "methodOptions" -- see methodOptions(Function),
    -- recover the options used when a method
    function was created
  * options -- get options
  * "OptionTable ++ List" -- see OptionTable ++ OptionTable,
    -- a binary operator, usually used for direct sum
  * OptionTable ++ OptionTable -- a binary
    operator, usually used for direct sum
  * readPackage -- read the package preamble

Methods that use an option table:
=================================

  * new OptionTable from List (missing documentation)
  * OptionTable >> Function -- attaching
    options to a function

For the programmer
==================

The object OptionTable, is a type, with
ancestor classes HashTable, < Thing.

OptionTable ++ OptionTable -- a binary operator, usually used for direct sum
****************************************************************************

Synopsis
========

  * Operator: ++,
  * Usage:
        x ++ y
  * Inputs:
      * x
      * y
  * Outputs:
      * a new OptionTable, obtained by merging x and y,
        preferring the default values provided by y

Description
===========

Alternatively, y can be a list of options.

+------------------------------------------------+
|i1 : options res ++ { Alpha => Omega }          |
|                                                |
|o1 = OptionTable{Alpha => Omega                }|
|                 DegreeLimit => null            |
|                 FastNonminimal => false        |
|                 HardDegreeLimit => {}          |
|                 LengthLimit => infinity        |
|                 PairLimit => infinity          |
|                 ParallelizeByDegree => false   |
|                 SortStrategy => 0              |
|                 StopBeforeComputation => false |
|                 Strategy => null               |
|                 SyzygyLimit => infinity        |
|                                                |
|o1 : OptionTable                                |
+------------------------------------------------+

See also
========

  * Option -- the class of all key-value pairs K => V

Ways to use this method:
========================

  * "OptionTable ++ List"
  * OptionTable ++ OptionTable -- a binary
    operator, usually used for direct sum

OptionTable >> Function -- attaching options to a function
**********************************************************

Synopsis
========

  * Operator: >>,
  * Usage:
        g = defs >> fun
  * Inputs:
      * defs, (or a list, of option pairs), whose keys are the
        names of the optional arguments, and whose values are the corresponding
        default values.  Alternatively, if defs is true, then all
        optional arguments are accepted and no defaults are provided.
      * fun, a function that expects optional arguments
  * Outputs:
      * g, a new function that pre-processes the optional arguments and then
        calls fun

Description
===========

The new function g works as follows. The value of g args, say, is obtained by
evaluation of (fun opts)(args'), where args' is obtained from args by removing
the options of the form X=>A (where X is a name of an optional argument), and
opts is a hash table of the same form as defs in which the default values have
been replaced by the user-supplied values, e.g., the value stored under the key
X has been replaced by A.

Remark: defs can also be simply a list of options.

In the following example we use a simple definition for fun so we can see
everything that fun receives.

+-----------------------------------------------------+
|i1 : g = {a=>1, b=>2} >> opts -> args -> {args, opts}|
|                                                     |
|o1 = g                                               |
|                                                     |
|o1 : FunctionClosure                                 |
+-----------------------------------------------------+
|i2 : g x                                             |
|                                                     |
|o2 = {x, OptionTable{a => 1}}                        |
|                     b => 2                          |
|                                                     |
|o2 : List                                            |
+-----------------------------------------------------+
|i3 : g(x,y,b=>66)                                    |
|                                                     |
|o3 = {(x, y), OptionTable{a => 1 }}                  |
|                          b => 66                    |
|                                                     |
|o3 : List                                            |
+-----------------------------------------------------+
|i4 : g(t,u,a=>44,b=>77)                              |
|                                                     |
|o4 = {(t, u), OptionTable{a => 44}}                  |
|                          b => 77                    |
|                                                     |
|o4 : List                                            |
+-----------------------------------------------------+
|i5 : h = true >> opts -> args -> {args, opts}        |
|                                                     |
|o5 = h                                               |
|                                                     |
|o5 : FunctionClosure                                 |
+-----------------------------------------------------+
|i6 : h(t,u,c=>55)                                    |
|                                                     |
|o6 = {(t, u), OptionTable{c => 55}}                  |
|                                                     |
|o6 : List                                            |
+-----------------------------------------------------+

See also
========

  * making new functions with optional arguments
  * OptionTable -- the class of hash tables for optional
    arguments
  * Option -- the class of all key-value pairs K => V
  * => -- produce an Option

Ways to use this method:
========================

  * "Boolean >> Function"
  * "List >> Function"
  * OptionTable >> Function -- attaching
    options to a function

Order -- specify the order of a Hilbert series required
*******************************************************

Description
===========

Order -- an optional argument used with hilbertSeries, to
specify the order of the series requested.

Functions with optional argument named Order:
=============================================

  * hilbertSeries(...,Order=>...)
    -- display the truncated
    power series expansion

For the programmer
==================

The object Order, is a symbol.

order -- a key used internally
*******************************

Description
===========

order -- used as a key inside finite fields under which is stored the number of
elements in the field.  Intended for internal use only

See also
========

  * GaloisField -- the class of all Galois fields

For the programmer
==================

The object order, is a symbol.

OrderedMonoid -- the class of all ordered monoids
*************************************************

Description
===========

An ordered monoid is a multiplicative monoid together with an ordering of its
elements.  The ordering is required to be compatible with the multiplication in
the sense that if x < y then x z < y z.  The class of all ordered monoids is
OrderedMonoid.

The reason for making a separate class for ordered monoids is that monoid rings
can be implemented more efficiently for them - an element of the monoid ring
can be stored as a sorted list, each element of which is a pair consisting of
an element of the monoid and a coefficient. See PolynomialRing.

A free commutative ordered monoid can be created with monoid.

See also
========

  * Monoid -- the class of all monoids

Types of ordered monoid:
========================

  * GeneralOrderedMonoid -- the class of all
    ordered free commutative monoids

For the programmer
==================

The object OrderedMonoid, is a type, with
ancestor classes Monoid, < Type <
MutableHashTable < HashTable <
Thing.

OutputDictionary -- the dictionary for output values
****************************************************

Description
===========

The symbols o1, o2, o3, etc., are used to store the output values arising from
interaction with the user, one line at a time.  The dictionary OutputDictionary
is the dictionary in which those symbols reside.
+-----------------------------------------------------------------------------+
|i1 : 2+2                                                                     |
|                                                                             |
|o1 = 4                                                                       |
+-----------------------------------------------------------------------------+
|i2 : "asdf" | "qwer"                                                         |
|                                                                             |
|o2 = asdfqwer                                                                |
+-----------------------------------------------------------------------------+
|i3 : value \ values OutputDictionary                                         |
|                                                                             |
|o3 = {4, asdfqwer}                                                           |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : dictionaryPath                                                          |
|                                                                             |
|o4 = {GlobalDictionary{}, PackageCitations.Dictionary, Varieties.Dictionary, |
|     ------------------------------------------------------------------------|
|     Truncations.Dictionary, Polyhedra.Dictionary, Saturation.Dictionary,    |
|     ------------------------------------------------------------------------|
|     Elimination.Dictionary, Isomorphism.Dictionary, OnlineLookup.Dictionary,|
|     ------------------------------------------------------------------------|
|     SimpleDoc.Dictionary, InverseSystems.Dictionary,                        |
|     ------------------------------------------------------------------------|
|     ConwayPolynomials.Dictionary, ReesAlgebra.Dictionary,                   |
|     ------------------------------------------------------------------------|
|     TangentCone.Dictionary, Classic.Dictionary, MinimalPrimes.Dictionary,   |
|     ------------------------------------------------------------------------|
|     PrimaryDecomposition.Dictionary, IntegralClosure.Dictionary,            |
|     ------------------------------------------------------------------------|
|     LLLBases.Dictionary, Macaulay2Doc.Dictionary, Core.Dictionary,          |
|     ------------------------------------------------------------------------|
|     GlobalDictionary{...4...}, PackageDictionary}                           |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : peek OutputDictionary                                                   |
|                                                                             |
|o5 = GlobalDictionary{"o1" => o1}                                            |
|                      "o2" => o2                                             |
|                      "o3" => o3                                             |
|                      "o4" => o4                                             |
+-----------------------------------------------------------------------------+

See also
========

  * dictionaryPath

For the programmer
==================

The object OutputDictionary, is an instance of the type
GlobalDictionary.

override -- override default values for optional arguments
**********************************************************

Description
===========

override(defaults,args) overrides default values for optional arguments present
in the argument sequence args.

One possibility is for the argument defaults to be an immutable hash table (of
type OptionTable), and args should be a sequence of
arguments, some of which are optional arguments of the form x => v.  Each such
optional argument is removed from args, and the value in defaults corresponding
to the key x is replaced by v. The value returned is the modified pair
(defaults, args). An error is signalled if the key x does not occur in
defaults.

A second possibility is for the argument defaults to be null, in
which case the keys x are not checked for validity, and no default values are
provided.  The main use of this is to separate the optional arguments from the
other arguments, which can then be used for dispatching to the correct method.

This function is intended for internal use only, and is used in the processing
of optional arguments for method functions that accept them.

+----------------------------------------------------+
|i1 : defs = new OptionTable from { a => 1, b => 2 };|
+----------------------------------------------------+
|i2 : override(defs, (4,b=>6,5))                     |
|                                                    |
|o2 = (OptionTable{a => 1}, (4, 5))                  |
|                  b => 6                            |
|                                                    |
|o2 : Sequence                                       |
+----------------------------------------------------+

For the programmer
==================

The object override, is a compiled function.

pack -- pack elements of a list or string into several shorter lists or strings
*******************************************************************************

Synopsis
========

  * Usage:
        pack(A, n)
        pack(n, A)
  * Inputs:
      * A, a basic list, or a string,
      * n, an integer, how many elements of A to put in each new
        list or string
  * Outputs:
      * L, a list, a list of lists or strings, with the elements
        of A taken n at a time.

Description
===========

The commands pack(A, n) and pack(n, A) produce identical results.

+-------------------------------------------------+
|i1 : pack(a..l, 3)                               |
|                                                 |
|o1 = {{a, b, c}, {d, e, f}, {g, h, i}, {j, k, l}}|
|                                                 |
|o1 : List                                        |
+-------------------------------------------------+
|i2 : pack(3, a..l)                               |
|                                                 |
|o2 = {{a, b, c}, {d, e, f}, {g, h, i}, {j, k, l}}|
|                                                 |
|o2 : List                                        |
+-------------------------------------------------+
|i3 : pack("Hello world!", 4)                     |
|                                                 |
|o3 = {Hell, o wo, rld!}                          |
|                                                 |
|o3 : List                                        |
+-------------------------------------------------+
|i4 : pack(4, "Hello world!")                     |
|                                                 |
|o4 = {Hell, o wo, rld!}                          |
|                                                 |
|o4 : List                                        |
+-------------------------------------------------+

If n doesn't divide the length of A, the last list will have fewer than n
elements.

+------------------------------------------------------+
|i5 : pack(a..m, 3)                                    |
|                                                      |
|o5 = {{a, b, c}, {d, e, f}, {g, h, i}, {j, k, l}, {m}}|
|                                                      |
|o5 : List                                             |
+------------------------------------------------------+

pack and mingle, can be used together to take a transpose of
lists

+-----------------------------------------------------------------------------+
|i6 : pack(2, mingle(a..m, 0..12))                                            |
|                                                                             |
|o6 = {{a, 0}, {b, 1}, {c, 2}, {d, 3}, {e, 4}, {f, 5}, {g, 6}, {h, 7}, {i, 8},|
|     ------------------------------------------------------------------------|
|     {j, 9}, {k, 10}, {l, 11}, {m, 12}}                                      |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * mingle -- mingle elements of several lists
  * sort -- sort a list or columns of a matrix
  * sublists -- process interspersed subsequences of a visible
    list
  * take -- Take some elements from a list or sequence.
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use pack:
=================

  * "pack(BasicList,ZZ)"
  * "pack(String,ZZ)"
  * "pack(ZZ,BasicList)"
  * "pack(ZZ,String)"

For the programmer
==================

The object pack, is a method function.

pager -- display with paging
****************************

Synopsis
========

  * Usage:
        pager x
  * Inputs:
      * x
  * Consequences:
      * x is converted to a net and displayed through the pager specified by
        the environment variable PAGER, if set, else through the program more.

For the programmer
==================

The object pager, is a function closure.

PairsRemaining -- whether to display the number of S-pairs remaining
********************************************************************

Description
===========

PairsRemaining -- an option for status, which specifies whether
to display number of S-pairs remaining.

Functions with optional argument named PairsRemaining:
======================================================

  * "status(...,PairsRemaining=>...)" -- see status, -- status of
    a resolution computation

For the programmer
==================

The object PairsRemaining, is a symbol.

parallelism in engine computations -- parallelism in engine computations
************************************************************************

Some computations in the engine can run using multiple cores on your computer.
Currently, this includes computation of minimal betti diagrams, non-minimal
resolutions, and Groebner bases of 2-sided ideals in associative algebras, all
in the graded case, over a finite field.  Also included is (one of the
algorithms for) the computation of Groebner bases in polynomial rings over
finite fields, whether graded or not.

The variable numTBBThreads controls the number of cores used by Macaulay2. The
default value (zero) means the system can choose an appropriate number of cores
(often the maximum available).  Note that the default behavior is to use
multiple cores.

In minimalBetti, and in freeResolution (Complexes),
with the Strategy => Nonminimal option, more
aggressive parallelism that sometimes uses a lot of memory but can sometimes
produce answers in less time can be enabled using the ParallelizeByDegree
boolean option.

For examples, we show some simple examples of computation which, for larger
size problems, might benefit from using parallelism.  Note that in each of
these cases, the default is to use all available CPU cores for computation. For
these particularly simple examples, the overhead for using multiple cores is
non-trivial with respect to the total computation time.  Significant speedup is
achieved when the time to gauss reduce the requisite matrices is large compared
to creating these matrices.

+-----------------------------------------------------------------------------+
|i1 : numTBBThreads                                                           |
|                                                                             |
|o1 = 0                                                                       |
+-----------------------------------------------------------------------------+
|i2 : I = Grassmannian(1, 6, CoefficientRing => ZZ/101)                       |
|                                                                             |
|o2 = ideal (p   p    - p   p    + p   p   , p   p    - p   p    + p   p   ,  |
|             4,5 3,6    3,5 4,6    3,4 5,6   4,5 2,6    2,5 4,6    2,4 5,6   |
|     ------------------------------------------------------------------------|
|     p   p    - p   p    + p   p   , p   p    - p   p    + p   p   , p   p   |
|      3,5 2,6    2,5 3,6    2,3 5,6   3,4 2,6    2,4 3,6    2,3 4,6   4,5 1,6|
|     ------------------------------------------------------------------------|
|     - p   p    + p   p   , p   p    - p   p    + p   p   , p   p    -       |
|        1,5 4,6    1,4 5,6   3,5 1,6    1,5 3,6    1,3 5,6   2,5 1,6         |
|     ------------------------------------------------------------------------|
|     p   p    + p   p   , p   p    - p   p    + p   p   , p   p    - p   p   |
|      1,5 2,6    1,2 5,6   3,4 1,6    1,4 3,6    1,3 4,6   2,4 1,6    1,4 2,6|
|     ------------------------------------------------------------------------|
|     + p   p   , p   p    - p   p    + p   p   , p   p    - p   p    +       |
|        1,2 4,6   2,3 1,6    1,3 2,6    1,2 3,6   4,5 0,6    0,5 4,6         |
|     ------------------------------------------------------------------------|
|     p   p   , p   p    - p   p    + p   p   , p   p    - p   p    +         |
|      0,4 5,6   3,5 0,6    0,5 3,6    0,3 5,6   2,5 0,6    0,5 2,6           |
|     ------------------------------------------------------------------------|
|     p   p   , p   p    - p   p    + p   p   , p   p    - p   p    +         |
|      0,2 5,6   1,5 0,6    0,5 1,6    0,1 5,6   3,4 0,6    0,4 3,6           |
|     ------------------------------------------------------------------------|
|     p   p   , p   p    - p   p    + p   p   , p   p    - p   p    +         |
|      0,3 4,6   2,4 0,6    0,4 2,6    0,2 4,6   1,4 0,6    0,4 1,6           |
|     ------------------------------------------------------------------------|
|     p   p   , p   p    - p   p    + p   p   , p   p    - p   p    +         |
|      0,1 4,6   2,3 0,6    0,3 2,6    0,2 3,6   1,3 0,6    0,3 1,6           |
|     ------------------------------------------------------------------------|
|     p   p   , p   p    - p   p    + p   p   , p   p    - p   p    +         |
|      0,1 3,6   1,2 0,6    0,2 1,6    0,1 2,6   3,4 2,5    2,4 3,5           |
|     ------------------------------------------------------------------------|
|     p   p   , p   p    - p   p    + p   p   , p   p    - p   p    +         |
|      2,3 4,5   3,4 1,5    1,4 3,5    1,3 4,5   2,4 1,5    1,4 2,5           |
|     ------------------------------------------------------------------------|
|     p   p   , p   p    - p   p    + p   p   , p   p    - p   p    +         |
|      1,2 4,5   2,3 1,5    1,3 2,5    1,2 3,5   3,4 0,5    0,4 3,5           |
|     ------------------------------------------------------------------------|
|     p   p   , p   p    - p   p    + p   p   , p   p    - p   p    +         |
|      0,3 4,5   2,4 0,5    0,4 2,5    0,2 4,5   1,4 0,5    0,4 1,5           |
|     ------------------------------------------------------------------------|
|     p   p   , p   p    - p   p    + p   p   , p   p    - p   p    +         |
|      0,1 4,5   2,3 0,5    0,3 2,5    0,2 3,5   1,3 0,5    0,3 1,5           |
|     ------------------------------------------------------------------------|
|     p   p   , p   p    - p   p    + p   p   , p   p    - p   p    +         |
|      0,1 3,5   1,2 0,5    0,2 1,5    0,1 2,5   2,3 1,4    1,3 2,4           |
|     ------------------------------------------------------------------------|
|     p   p   , p   p    - p   p    + p   p   , p   p    - p   p    +         |
|      1,2 3,4   2,3 0,4    0,3 2,4    0,2 3,4   1,3 0,4    0,3 1,4           |
|     ------------------------------------------------------------------------|
|     p   p   , p   p    - p   p    + p   p   , p   p    - p   p    +         |
|      0,1 3,4   1,2 0,4    0,2 1,4    0,1 2,4   1,2 0,3    0,2 1,3           |
|     ------------------------------------------------------------------------|
|     p   p   )                                                               |
|      0,1 2,3                                                                |
|                                                                             |
|               ZZ                                                            |
|o2 : Ideal of ---[p   ..p   , p   , p   , p   , p   , p   , p   , p   , p   ,|
|              101  0,1   0,2   1,2   0,3   1,3   2,3   0,4   1,4   2,4   3,4 |
|-----------------------------------------------------------------------------|
|p   , p   , p   , p   , p   , p   , p   , p   , p   , p   , p   ]            |
| 0,5   1,5   2,5   3,5   4,5   0,6   1,6   2,6   3,6   4,6   5,6             |
+-----------------------------------------------------------------------------+
|i3 : S = ring I                                                              |
|                                                                             |
|o3 = S                                                                       |
|                                                                             |
|o3 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i4 : elapsedTime minimalBetti I                                              |
| -- 2.379s elapsed                                                           |
|                                                                             |
|            0  1   2   3   4    5   6   7   8  9 10                          |
|o4 = total: 1 35 140 385 819 1080 819 385 140 35  1                          |
|         0: 1  .   .   .   .    .   .   .   .  .  .                          |
|         1: . 35 140 189  84    .   .   .   .  .  .                          |
|         2: .  .   . 196 735 1080 735 196   .  .  .                          |
|         3: .  .   .   .   .    .  84 189 140 35  .                          |
|         4: .  .   .   .   .    .   .   .   .  .  1                          |
|                                                                             |
|o4 : BettiTally                                                              |
+-----------------------------------------------------------------------------+
|i5 : I = ideal I_*;                                                          |
|                                                                             |
|o5 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i6 : elapsedTime minimalBetti(I, ParallelizeByDegree => true)                |
| -- 2.07761s elapsed                                                         |
|                                                                             |
|            0  1   2   3   4    5   6   7   8  9 10                          |
|o6 = total: 1 35 140 385 819 1080 819 385 140 35  1                          |
|         0: 1  .   .   .   .    .   .   .   .  .  .                          |
|         1: . 35 140 189  84    .   .   .   .  .  .                          |
|         2: .  .   . 196 735 1080 735 196   .  .  .                          |
|         3: .  .   .   .   .    .  84 189 140 35  .                          |
|         4: .  .   .   .   .    .   .   .   .  .  1                          |
|                                                                             |
|o6 : BettiTally                                                              |
+-----------------------------------------------------------------------------+
|i7 : I = ideal I_*;                                                          |
|                                                                             |
|o7 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i8 : numTBBThreads = 1                                                       |
|                                                                             |
|o8 = 1                                                                       |
+-----------------------------------------------------------------------------+
|i9 : elapsedTime minimalBetti(I)                                             |
| -- 2.28074s elapsed                                                         |
|                                                                             |
|            0  1   2   3   4    5   6   7   8  9 10                          |
|o9 = total: 1 35 140 385 819 1080 819 385 140 35  1                          |
|         0: 1  .   .   .   .    .   .   .   .  .  .                          |
|         1: . 35 140 189  84    .   .   .   .  .  .                          |
|         2: .  .   . 196 735 1080 735 196   .  .  .                          |
|         3: .  .   .   .   .    .  84 189 140 35  .                          |
|         4: .  .   .   .   .    .   .   .   .  .  1                          |
|                                                                             |
|o9 : BettiTally                                                              |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i10 : needsPackage "Complexes"                                               |
|                                                                             |
|o10 = Complexes                                                              |
|                                                                             |
|o10 : Package                                                                |
+-----------------------------------------------------------------------------+
|i11 : numTBBThreads = 0                                                      |
|                                                                             |
|o11 = 0                                                                      |
+-----------------------------------------------------------------------------+
|i12 : I = ideal I_*;                                                         |
|                                                                             |
|o12 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i13 : elapsedTime freeResolution(I, Strategy => Nonminimal)                  |
| -- 2.22268s elapsed                                                         |
|                                                                             |
|       1      35      241      841      1781      2464      2294      1432   |
|o13 = S  <-- S   <-- S    <-- S    <-- S     <-- S     <-- S     <-- S       |
|                                                                             |
|      0      1       2        3        4         5         6         7       |
|                                                                             |
|o13 : Complex                                                                |
|-----------------------------------------------------------------------------|
|     576      135      14                                                    |
|<-- S    <-- S    <-- S                                                      |
|                                                                             |
|    8        9        10                                                     |
+-----------------------------------------------------------------------------+
|i14 : numTBBThreads = 1                                                      |
|                                                                             |
|o14 = 1                                                                      |
+-----------------------------------------------------------------------------+
|i15 : I = ideal I_*;                                                         |
|                                                                             |
|o15 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i16 : elapsedTime freeResolution(I, Strategy => Nonminimal)                  |
| -- 2.2102s elapsed                                                          |
|                                                                             |
|       1      35      241      841      1781      2464      2294      1432   |
|o16 = S  <-- S   <-- S    <-- S    <-- S     <-- S     <-- S     <-- S       |
|                                                                             |
|      0      1       2        3        4         5         6         7       |
|                                                                             |
|o16 : Complex                                                                |
|-----------------------------------------------------------------------------|
|     576      135      14                                                    |
|<-- S    <-- S    <-- S                                                      |
|                                                                             |
|    8        9        10                                                     |
+-----------------------------------------------------------------------------+

Groebner bases (based on a linear algebra method, e.g. Faugere's F4 algorithm,
are also parallelized.  Note: the MGB Strategy of groebnerBasis is not
currently parallelized.

+-----------------------------------------------------+
|i17 : numTBBThreads = 0                              |
|                                                     |
|o17 = 0                                              |
+-----------------------------------------------------+
|i18 : S = ZZ/101[a..g]                               |
|                                                     |
|o18 = S                                              |
|                                                     |
|o18 : PolynomialRing                                 |
+-----------------------------------------------------+
|i19 : I = ideal random(S^1, S^{4:-5});               |
|                                                     |
|o19 : Ideal of S                                     |
+-----------------------------------------------------+
|i20 : elapsedTime groebnerBasis(I, Strategy => "F4");|
| -- 3.31791s elapsed                                 |
|                                                     |
|              1      108                             |
|o20 : Matrix S  <-- S                                |
+-----------------------------------------------------+
|i21 : numTBBThreads = 1                              |
|                                                     |
|o21 = 1                                              |
+-----------------------------------------------------+
|i22 : I = ideal I_*;                                 |
|                                                     |
|o22 : Ideal of S                                     |
+-----------------------------------------------------+
|i23 : elapsedTime groebnerBasis(I, Strategy => "F4");|
| -- 6.04823s elapsed                                 |
|                                                     |
|              1      108                             |
|o23 : Matrix S  <-- S                                |
+-----------------------------------------------------+
|i24 : numTBBThreads = 10                             |
|                                                     |
|o24 = 10                                             |
+-----------------------------------------------------+
|i25 : I = ideal I_*;                                 |
|                                                     |
|o25 : Ideal of S                                     |
+-----------------------------------------------------+
|i26 : elapsedTime groebnerBasis(I, Strategy => "F4");|
| -- 2.80436s elapsed                                 |
|                                                     |
|              1      108                             |
|o26 : Matrix S  <-- S                                |
+-----------------------------------------------------+

For Groebner basis computation in associative algebras, ParallelizeByDegree is
not relevant.  In this case, use numTBBThreads to control the amount of
parallelism.

+---------------------------------------------------------------------+
|i27 : needsPackage "AssociativeAlgebras"                             |
|                                                                     |
|o27 = AssociativeAlgebras                                            |
|                                                                     |
|o27 : Package                                                        |
+---------------------------------------------------------------------+
|i28 : numTBBThreads = 0                                              |
|                                                                     |
|o28 = 0                                                              |
+---------------------------------------------------------------------+
|i29 : C = threeDimSklyanin(ZZ/101,{2,3,5},{a,b,c})                   |
|                                                                     |
|o29 = C                                                              |
|                                                                     |
|o29 : FreeAlgebraQuotient                                            |
+---------------------------------------------------------------------+
|i30 : I = ideal C                                                    |
|                                                                     |
|               2                         2                         2 |
|o30 = ideal (5a  + 2b*c + 3c*b, 3a*c + 5b  + 2c*a, 2a*b + 3b*a + 5c )|
|                                                                     |
|                ZZ                                                   |
|o30 : Ideal of ---<|a, b, c|>                                        |
|               101                                                   |
+---------------------------------------------------------------------+
|i31 : elapsedTime NCGB(I, 22);                                       |
| -- .702528s elapsed                                                 |
|                                                                     |
|               ZZ            1       ZZ            148               |
|o31 : Matrix (---<|a, b, c|>)  <-- (---<|a, b, c|>)                  |
|              101                   101                              |
+---------------------------------------------------------------------+
|i32 : I = ideal I_*                                                  |
|                                                                     |
|               2                         2                         2 |
|o32 = ideal (5a  + 2b*c + 3c*b, 3a*c + 5b  + 2c*a, 2a*b + 3b*a + 5c )|
|                                                                     |
|                ZZ                                                   |
|o32 : Ideal of ---<|a, b, c|>                                        |
|               101                                                   |
+---------------------------------------------------------------------+
|i33 : numTBBThreads = 1                                              |
|                                                                     |
|o33 = 1                                                              |
+---------------------------------------------------------------------+
|i34 : elapsedTime NCGB(I, 22);                                       |
| -- 1.02134s elapsed                                                 |
|                                                                     |
|               ZZ            1       ZZ            148               |
|o34 : Matrix (---<|a, b, c|>)  <-- (---<|a, b, c|>)                  |
|              101                   101                              |
+---------------------------------------------------------------------+

See also
========

  * minimalBetti -- minimal betti numbers of (the minimal
    free resolution of) a homogeneous ideal or module
  * resolution -- projective resolution
  * freeResolution (Complexes) -- compute a free
    resolution of a module or ideal
  * groebnerBasis -- Gröbner basis, as a matrix
  * NCGB (AssociativeAlgebras) -- Compute a two-sided Groebner
    basis of an ideal to a specified degree
  * parallel programming with threads and tasks

Parenthesize
************

Description
===========

This class is used internally to implement the parentheses inserted by
parts.

For the programmer
==================

The object Parenthesize, is a wrapper type,
with ancestor classes Holder, < Expression
< BasicList < Thing.

parsing precedence, in detail
*****************************

A newline ends a statement if it can, otherwise it acts like any white space.
+-------+
|i1 : 2+|
|     3+|
|     4 |
|       |
|o1 = 9 |
+-------+

Parsing is determined by a triple of numbers attached to each token. The
following table (produced by the command seeParsing),
displays each of these numbers.
+-----------------------------------------------------------------------------+
|parsing     binary    unary                                                  |
|precedence  binding   binding                                                |
|            strength  strength                                               |
|                                                                             |
|     2          2                                                            |
|                                                                             |
|     4          4                                                            |
|                                                                             |
|     6                                                                       |
|                                                                             |
|     8          7                                                            |
|                                                                             |
|    10         10        10                                                  |
|                                                                             |
|    12                   12                                                  |
|                                                                             |
|    14         13               %=  &=  **=  *=  ++=  +=  -=                 |
|                                                                             |
|    16                   16                                                  |
|                                                                             |
|    18         18        18                                                  |
|                                                                             |
|    20         19        20                                                  |
|                                                                             |
|    22         21                                                            |
|                                                                             |
|    22         21        22                                                  |
|                                                                             |
|    24         23                                                            |
|                                                                             |
|    26         25                                                            |
|                                                                             |
|    26         25        26                                                  |
|                                                                             |
|    28         27                                                            |
|                                                                             |
|    28         27        28                                                  |
|                                                                             |
|    30         29                                                            |
|                                                                             |
|    32         31                                                            |
|                                                                             |
|    34                   34                                                  |
|                                                                             |
|    36         35                                                            |
|                                                                             |
|    36         35        36                                                  |
|                                                                             |
|    38         38                                                            |
|                                                                             |
|    40         39                                                            |
|                                                                             |
|    42         42                                                            |
|                                                                             |
|    44         44                                                            |
|                                                                             |
|    46         46                                                            |
|                                                                             |
|    48         48                                                            |
|                                                                             |
|    50         50                                                            |
|                                                                             |
|    50         50        50                                                  |
|                                                                             |
|    52         52                                                            |
|                                                                             |
|    54                    6                                                  |
|                                                                             |
|    56         55                                                            |
|                                                                             |
|    56         56                                                            |
|                                                                             |
|    56         56        56                                                  |
|                                                                             |
|    58         57                                                            |
|                                                                             |
|    60                                                                       |
|                                                                             |
|    60                    6                                                  |
|                                                                             |
|    60                   12                             break                |
|                                                                             |
|    60                   16                                                  |
|                                                                             |
|    60                   72                                                  |
|                                                                             |
|    60         59                                                            |
|                                                                             |
|    62                                                                       |
|                                                                             |
|    64         64                                                            |
|                                                                             |
|    66                                                                       |
|                                                                             |
|    68         68                                                            |
|                                                                             |
|    68         68        59                                                  |
|                                                                             |
|    70                                                                       |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                               operators                     |
|                                                                             |
|                                                                             |
|                                            -*end of file*-                  |
|                                                                             |
|                                            -*end of cell*-                  |
|                                                                             |
|                                              )  ]  |>  }                    |
|                                                                             |
|                                                   ;                         |
|                                                                             |
|                                                   ,                         |
|                                                                             |
|                                         do  else  list  then                |
|                                                                             |
|->  ..<=  ..=  //=  /=  :=  <-  <<=  <==>=  =  ===>=  ==>=  =>  >>  >>=  ??= |
|                                                                             |
|                                        from  in  of  to  when               |
|                                                                             |
|                                                  <<                         |
|                                                                             |
|                                                  |-                         |
|                                                                             |
|                                                 ===>                        |
|                                                                             |
|                                                 <===                        |
|                                                                             |
|                                                 <==>                        |
|                                                                             |
|                                                  ==>                        |
|                                                                             |
|                                                  <==                        |
|                                                                             |
|                                                  or                         |
|                                                                             |
|                                                  ??                         |
|                                                                             |
|                                                  xor                        |
|                                                                             |
|                                                  and                        |
|                                                                             |
|                                                  not                        |
|                                                                             |
|                                           !=  =!=  ==  ===                  |
|                                                                             |
|                                            <  <=  >  >=  ?                  |
|                                                                             |
|                                                  ||                         |
|                                                                             |
|                                                   :                         |
|                                                                             |
|                                                   |                         |
|                                                                             |
|                                                  ^^                         |
|                                                                             |
|                                                   &                         |
|                                                                             |
|                                                ..  ..<                      |
|                                                                             |
|                                                  ++                         |
|                                                                             |
|                                                 +  -                        |
|                                                                             |
|                                                  **                         |
|                                                                             |
|                                                 <|  [                       |
|                                                                             |
|                                                 \  \\                       |
|                                                                             |
|                                               %  /  //                      |
|                                                                             |
|                                                   *                         |
|                                                                             |
|                                                   @                         |
|                                                                             |
|                                           -*...symbols...*-                 |
|                                                                             |
|                                                 (  {                        |
|                                                                             |
| catch  continue  elapsedTime  elapsedTiming  if  return  shield  step  TEST |
|                                                                             |
|                                               for  new                      |
|                                                                             |
|                                  global  local  symbol  threadLocal         |
|                                                                             |
|                                                 SPACE                       |
|                                                                             |
|                                                  (*)                        |
|                                                                             |
|                                                  @@                         |
|                                                                             |
|                                           ^*  ^~  _*  _~  ~                 |
|                                                                             |
|                     #?  .  .?  ^  ^**  ^<  ^<=  ^>  ^>=  _  _<  _<=  _>  _>=|
|                                                                             |
|                                                   #                         |
|                                                                             |
|                                               !  ^!  _!                     |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|@=  @@=  \=  \\=  ^**=  ^=  ^^=  _=  |-=  |=  |_=  ||=                       |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|throw  time  timing  try  while                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
| |_                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
+-----------------------------------------------------------------------------+
Here is the way these numbers work.  The parser maintains a number which called
the current parsing level, or simply, the level. The parser builds up an
expression until it encounters an input token whose parsing precedence is less
than or equal to the current level. The tokens preceding the offending token
are bundled into an expression appropriately and incorporated into the
containing expression.

When an operator or token is encountered, its binding strength serves as the
level for parsing the subsequent expression, unless the current level is
higher, in which case it is used.

Consider a binary operator such as *.  The relationship between its binary
binding strength and its parsing precedence turns out to determine whether
a*b*c is parsed as (a*b)*c or as a*(b*c). When the parser encounters the second
*, the current parsing level is equal to the binding strength of the first *.
If the binding strength is less than the precedence, then the second * becomes
part of the right hand operand of the first *, and the expression is parsed as
a*(b*c).  Otherwise, the expression is parsed as (a*b)*c.

For unary operators, the unary binding strength is used instead of the binary
binding strength to reset the current level.  The reason for having both
numbers is that some operators can be either unary or binary, depending on the
context. A good example is #, which binds as tightly as .,
when used as an infix operator, and binds as loosely as adjacency or function
application when used as a prefix operator.

To handle expressions like b c d, where there are no tokens present which can
serve as a binary multiplication operator, after parsing b, the level will be
set to 1 less than the precedence of an identifier, so that b c d will be
parsed as b (c d).

The comma and semicolon get special treatment: the empty expression can occur
to the right of the comma or semicolon or to the left of the comma.

One of the most unusual aspects of the parsing precedence table above is that [
is assigned a precedence several steps lower than the precedence of symbols and
adjacency, and also lower than the precedence of /.  This was done so
expressions like R/I[x] would be parsed according to mathematical custom, but
it implies that expressions like f g [x] will be parsed in a surprising way,
with f g being evaluated first, even if f and g are both functions.  Suitably
placed parentheses can help, as illustrated in the next example.

+------------------------------+
|i2 : f = x -> (print x; print)|
|                              |
|o2 = f                        |
|                              |
|o2 : FunctionClosure          |
+------------------------------+
|i3 : f f [1,2,3]              |
|f                             |
|[1, 2, 3]                     |
+------------------------------+
|i4 : f f ([1,2,3])            |
|[1, 2, 3]                     |
|print                         |
|                              |
|o4 = print                    |
|                              |
|o4 : FunctionClosure          |
+------------------------------+
|i5 : f (f [1,2,3])            |
|[1, 2, 3]                     |
|print                         |
|                              |
|o5 = print                    |
|                              |
|o5 : FunctionClosure          |
+------------------------------+

part -- select terms of a polynomial by degree(s) or weight(s)
**************************************************************

Synopsis
========

  * Usage:
        part(deg, f)
        part(lo, hi, f)
        part(deg, f)
        part(lo, hi, wt, f)
        part(mdeg, f)
        part_deg f
  * Inputs:
      * f, a ring element, a polynomial
      * deg, an integer, in which degree to select terms from f
      * lo, an integer, or InfiniteNumber,
        the lower bound of degrees to select
      * hi, an integer, or InfiniteNumber,
        the upper bound of degrees to select
      * wt, a list, (optionally) a list of integers to use as
        weights before selecting degrees
      * mdeg, a list, a multidegree, in the case that f is defined
        in a multigraded ring
  * Outputs:
      * a ring element, the sum of all terms of f matching
        the specified degree or range of degrees (after weighting, if weights
        given)

Description
===========

To select terms of a single degree, use part(deg, f). An alternate syntax uses
an underscore.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : f = (x+y+1)^4                                                           |
|                                                                             |
|      4     3      2 2       3    4     3      2         2     3     2       |
|o2 = x  + 4x y + 6x y  + 4x*y  + y  + 4x  + 12x y + 12x*y  + 4y  + 6x  +     |
|     ------------------------------------------------------------------------|
|               2                                                             |
|     12x*y + 6y  + 4x + 4y + 1                                               |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+
|i3 : part(2, f)                                                              |
|                                                                             |
|       2             2                                                       |
|o3 = 6x  + 12x*y + 6y                                                        |
|                                                                             |
|o3 : R                                                                       |
+-----------------------------------------------------------------------------+
|i4 : part_2 f                                                                |
|                                                                             |
|       2             2                                                       |
|o4 = 6x  + 12x*y + 6y                                                        |
|                                                                             |
|o4 : R                                                                       |
+-----------------------------------------------------------------------------+

To select terms within a range of degrees, use part(lo, hi, f).

+--------------------------------+
|i5 : part(1, 2, f)              |
|                                |
|       2             2          |
|o5 = 6x  + 12x*y + 6y  + 4x + 4y|
|                                |
|o5 : R                          |
+--------------------------------+

In the next example, we apply the weights \{2,3\} before selecting terms. In
other words, the term x^ay^b is considered to have degree 2a+3b.

+------------------------------------+
|i6 : part(6, {2,3}, f)              |
|                                    |
|       3     2                      |
|o6 = 4x  + 6y                       |
|                                    |
|o6 : R                              |
+------------------------------------+
|i7 : part(6, 8, {2,3}, f)           |
|                                    |
|      4     3      2         2     2|
|o7 = x  + 4x  + 12x y + 12x*y  + 6y |
|                                    |
|o7 : R                              |
+------------------------------------+

If the generators of the ring were defined to have non-unit degrees, the
weights override those degrees.

+-----------------------------------------------------------------------------+
|i8 : R = QQ[x,y, Degrees=>{2,3}];                                            |
+-----------------------------------------------------------------------------+
|i9 : f = (x+y+1)^4                                                           |
|                                                                             |
|      4       3     2 2     3      3    4        2      2      3     2       |
|o9 = y  + 4x*y  + 6x y  + 4x y + 4y  + x  + 12x*y  + 12x y + 4x  + 6y  +     |
|     ------------------------------------------------------------------------|
|               2                                                             |
|     12x*y + 6x  + 4y + 4x + 1                                               |
|                                                                             |
|o9 : R                                                                       |
+-----------------------------------------------------------------------------+
|i10 : part(2, f)                                                             |
|                                                                             |
|o10 = 4x                                                                     |
|                                                                             |
|o10 : R                                                                      |
+-----------------------------------------------------------------------------+
|i11 : part(2, {1,1}, f)                                                      |
|                                                                             |
|        2             2                                                      |
|o11 = 6y  + 12x*y + 6x                                                       |
|                                                                             |
|o11 : R                                                                      |
+-----------------------------------------------------------------------------+

By omitting lo or hi, but providing a comma indicating the omission, the range
of degrees will be unbounded in the appropriate direction.

+-----------------------------------------------------------------------------+
|i12 : S = QQ[a,b,c]                                                          |
|                                                                             |
|o12 = S                                                                      |
|                                                                             |
|o12 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i13 : g = (a - b*c + 2)^3                                                    |
|                                                                             |
|         3 3       2 2     2        2 2    3               2                 |
|o13 = - b c  + 3a*b c  - 3a b*c + 6b c  + a  - 12a*b*c + 6a  - 12b*c + 12a + |
|      -----------------------------------------------------------------------|
|      8                                                                      |
|                                                                             |
|o13 : S                                                                      |
+-----------------------------------------------------------------------------+
|i14 : part(4, , g)                                                           |
|                                                                             |
|         3 3       2 2     2        2 2                                      |
|o14 = - b c  + 3a*b c  - 3a b*c + 6b c                                       |
|                                                                             |
|o14 : S                                                                      |
+-----------------------------------------------------------------------------+
|i15 : part(, 3, g)                                                           |
|                                                                             |
|       3               2                                                     |
|o15 = a  - 12a*b*c + 6a  - 12b*c + 12a + 8                                   |
|                                                                             |
|o15 : S                                                                      |
+-----------------------------------------------------------------------------+
|i16 : part(, 3, 1..3, g)                                                     |
|                                                                             |
|       3     2                                                               |
|o16 = a  + 6a  + 12a + 8                                                     |
|                                                                             |
|o16 : S                                                                      |
+-----------------------------------------------------------------------------+

Infinite numbers may also be given for the bounds.

+-----------------------------------------------------------------------------+
|i17 : part(4, infinity, g)                                                   |
|                                                                             |
|         3 3       2 2     2        2 2                                      |
|o17 = - b c  + 3a*b c  - 3a b*c + 6b c                                       |
|                                                                             |
|o17 : S                                                                      |
+-----------------------------------------------------------------------------+
|i18 : part(-infinity, 3, g)                                                  |
|                                                                             |
|       3               2                                                     |
|o18 = a  - 12a*b*c + 6a  - 12b*c + 12a + 8                                   |
|                                                                             |
|o18 : S                                                                      |
+-----------------------------------------------------------------------------+
|i19 : part(-infinity, infinity, 1..3, g)                                     |
|                                                                             |
|         3 3       2 2     2        2 2    3               2                 |
|o19 = - b c  + 3a*b c  - 3a b*c + 6b c  + a  - 12a*b*c + 6a  - 12b*c + 12a + |
|      -----------------------------------------------------------------------|
|      8                                                                      |
|                                                                             |
|o19 : S                                                                      |
+-----------------------------------------------------------------------------+

For multigraded rings, use a list to specify a single multidegree in the first
argument. The underscore syntax works here too.

+------------------------------------------------------------------------+
|i20 : R = QQ[x,y,z, Degrees => {{1,0,0},{0,1,0},{0,0,1}}];              |
+------------------------------------------------------------------------+
|i21 : f = (x+y+z)^3                                                     |
|                                                                        |
|       3     2        2    3     2               2        2       2    3|
|o21 = x  + 3x y + 3x*y  + y  + 3x z + 6x*y*z + 3y z + 3x*z  + 3y*z  + z |
|                                                                        |
|o21 : R                                                                 |
+------------------------------------------------------------------------+
|i22 : part({2,0,1}, f)                                                  |
|                                                                        |
|        2                                                               |
|o22 = 3x z                                                              |
|                                                                        |
|o22 : R                                                                 |
+------------------------------------------------------------------------+
|i23 : part_{2,0,1} f                                                    |
|                                                                        |
|        2                                                               |
|o23 = 3x z                                                              |
|                                                                        |
|o23 : R                                                                 |
+------------------------------------------------------------------------+

A range of degrees cannot be asked for in the multigraded case. Polynomial
rings over polynomial rings are multigraded, so either use a multidegree or
specify weights to avoid errors.

+-----------------------------------------------------------+
|i24 : R = QQ[a][x];                                        |
+-----------------------------------------------------------+
|i25 : h = (1+a+x)^3                                        |
|                                                           |
|       3            2      2               3     2         |
|o25 = x  + (3a + 3)x  + (3a  + 6a + 3)x + a  + 3a  + 3a + 1|
|                                                           |
|o25 : R                                                    |
+-----------------------------------------------------------+
|i26 : part(2, {1,0}, h)                                    |
|                                                           |
|               2                                           |
|o26 = (3a + 3)x                                            |
|                                                           |
|o26 : R                                                    |
+-----------------------------------------------------------+
|i27 : part(2, {0,1}, h)                                    |
|                                                           |
|        2      2                                           |
|o27 = 3a x + 3a                                            |
|                                                           |
|o27 : R                                                    |
+-----------------------------------------------------------+
|i28 : part({2,1}, h)                                       |
|                                                           |
|               2                                           |
|o28 = (3a + 3)x                                            |
|                                                           |
|o28 : R                                                    |
+-----------------------------------------------------------+

See also
========

  * degree
  * monomials -- matrix of monomials in a ring element or
    matrix
  * parts -- display terms of a polynomial degree by degree
  * select -- select from a list, hash table, or string
  * someTerms -- select some terms of a polynomial
  * terms -- provide a list of terms of a polynomial
  * graded and multigraded polynomial rings
  * manipulating polynomials

Ways to use part:
=================

  * "part(InfiniteNumber,InfiniteNumber,RingElement)"
  * "part(InfiniteNumber,InfiniteNumber,VisibleList,RingElement)"
  * "part(InfiniteNumber,ZZ,RingElement)"
  * "part(InfiniteNumber,ZZ,VisibleList,RingElement)"
  * "part(List,RingElement)"
  * "part(Nothing,Nothing,RingElement)"
  * "part(Nothing,Nothing,VisibleList,RingElement)"
  * "part(Nothing,ZZ,RingElement)"
  * "part(Nothing,ZZ,VisibleList,RingElement)"
  * "part(ZZ,InfiniteNumber,RingElement)"
  * "part(ZZ,InfiniteNumber,VisibleList,RingElement)"
  * "part(ZZ,Nothing,RingElement)"
  * "part(ZZ,Nothing,VisibleList,RingElement)"
  * "part(ZZ,RingElement)"
  * "part(ZZ,VisibleList,RingElement)"
  * "part(ZZ,ZZ,RingElement)"
  * "part(ZZ,ZZ,VisibleList,RingElement)"
  * part(InfiniteNumber,InfiniteNumber,Number) (missing documentation)
  * part(InfiniteNumber,ZZ,Number) (missing documentation)
  * part(ZZ,InfiniteNumber,Number) (missing documentation)
  * part(ZZ,Number) (missing documentation)
  * part(ZZ,ZZ,Number) (missing documentation)

For the programmer
==================

The object part, is a method function.

Partition -- a type of list representing a partition of a natural number
************************************************************************

See also
========

  * partitions -- list the partitions of an integer
  * conjugate(Partition) -- conjugate a
    partition

Functions and methods returning an object of class Partition:
=============================================================

  * conjugate(Partition) -- conjugate a
    partition

Methods that use an object of class Partition:
==============================================

  * Partition _ ZZ -- get element

For the programmer
==================

The object Partition, is a type, with ancestor
classes BasicList, < Thing.

partition -- partition a set or list by values of a function
************************************************************

Synopsis
========

  * Usage:
        partition(f,L)
        partition(f,L,I)
  * Inputs:
      * f, a function,
      * L, a visible list, or a virtual tally,
  * Outputs:
      * a hash table, whose keys are the possible values of
        the function f on the elements of the list, set or tally L, and the
        corresponding value of the hash table is the list, set or tally of
        elements of L which take that value under f. The optional third
        argument I is a list whose elements will be included as keys in the
        return value, allowing empty lists to appear in the partition.

Description
===========

+-------------------------------------------+
|i1 : L = {1,3,6,5,3,1,2,8,8,8}             |
|                                           |
|o1 = {1, 3, 6, 5, 3, 1, 2, 8, 8, 8}        |
|                                           |
|o1 : List                                  |
+-------------------------------------------+
|i2 : partition(odd, L)                     |
|                                           |
|o2 = HashTable{false => {6, 2, 8, 8, 8}}   |
|               true => {1, 3, 5, 3, 1}     |
|                                           |
|o2 : HashTable                             |
+-------------------------------------------+
|i3 : partition(odd, set L)                 |
|                                           |
|o3 = HashTable{false => set {8, 6, 2}}     |
|               true => set {5, 1, 3}       |
|                                           |
|o3 : HashTable                             |
+-------------------------------------------+
|i4 : partition(odd, tally L)               |
|                                           |
|o4 = HashTable{false => Tally{2 => 1}}     |
|                              6 => 1       |
|                              8 => 3       |
|               true => Tally{1 => 2}       |
|                             3 => 2        |
|                             5 => 1        |
|                                           |
|o4 : HashTable                             |
+-------------------------------------------+
|i5 : partition (even, {3,3,5},{true,false})|
|                                           |
|o5 = HashTable{false => {3, 3, 5}}         |
|               true => {}                  |
|                                           |
|o5 : HashTable                             |
+-------------------------------------------+
The following example partitions the generators of an ideal by degree.
+-----------------------------------------------------------+
|i6 : R = QQ[a..f]                                          |
|                                                           |
|o6 = R                                                     |
|                                                           |
|o6 : PolynomialRing                                        |
+-----------------------------------------------------------+
|i7 : I = ideal"ab,ade,ac3,d4,b3,adf,f4,e10"                |
|                                                           |
|                           3   4   3          4   10       |
|o7 = ideal (a*b, a*d*e, a*c , d , b , a*d*f, f , e  )      |
|                                                           |
|o7 : Ideal of R                                            |
+-----------------------------------------------------------+
|i8 : partition(f -> first degree f, flatten entries gens I)|
|                                                           |
|o8 = HashTable{2 => {a*b}             }                    |
|                             3                             |
|               3 => {a*d*e, b , a*d*f}                     |
|                        3   4   4                          |
|               4 => {a*c , d , f }                         |
|                       10                                  |
|               10 => {e  }                                 |
|                                                           |
|o8 : HashTable                                             |
+-----------------------------------------------------------+

See also
========

  * tally -- tally the elements of a list, sequence, array, or
    string
  * partitions -- list the partitions of an integer
  * sublists -- process interspersed subsequences of a visible
    list

Ways to use partition:
======================

  * "partition(Function,VirtualTally)"
  * "partition(Function,VirtualTally,VisibleList)"
  * "partition(Function,VisibleList)"
  * "partition(Function,VisibleList,VisibleList)"

For the programmer
==================

The object partition, is a method function.

Partition _ ZZ -- get element
*****************************

Synopsis
========

  * Operator: _,
  * Usage:
        p_i
  * Inputs:
      * p
      * i
  * Outputs:
      * an integer, the i-th element of the partition p

Description
===========

+--------------------------------------------------------+
|i1 : partitions 3                                       |
|                                                        |
|o1 = {Partition{3}, Partition{2, 1}, Partition{1, 1, 1}}|
|                                                        |
|o1 : List                                               |
+--------------------------------------------------------+
|i2 : p = new Partition from {2,1}                       |
|                                                        |
|o2 = Partition{2, 1}                                    |
|                                                        |
|o2 : Partition                                          |
+--------------------------------------------------------+
|i3 : p_0                                                |
|                                                        |
|o3 = 2                                                  |
+--------------------------------------------------------+
|i4 : w = toList p                                       |
|                                                        |
|o4 = {2, 1}                                             |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+

See also
========

  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2
  * partitions -- list the partitions of an integer
  * toList -- create a list

Ways to use this method:
========================

  * Partition _ ZZ -- get element

partitions -- list the partitions of an integer
***********************************************

Synopsis
========

  * Usage:
        partitions(n)
        partitions(n, k)
  * Inputs:
      * n, an integer, a nonnegative integer
      * k, an integer, a nonnegative integer, the maximum size of
        each part
  * Outputs:
      * a list, of all partitions of n

Description
===========

+-----------------------------------------------------------------------------+
|i1 : partitions(4)                                                           |
|                                                                             |
|o1 = {Partition{4}, Partition{3, 1}, Partition{2, 2}, Partition{2, 1, 1},    |
|     ------------------------------------------------------------------------|
|     Partition{1, 1, 1, 1}}                                                  |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+
|i2 : partitions(4, 2)                                                        |
|                                                                             |
|o2 = {Partition{2, 2}, Partition{2, 1, 1}, Partition{1, 1, 1, 1}}            |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

Each partition is a basic list of type Partition.

+-----------------------------------+
|i3 : p = new Partition from {2,2,1}|
|                                   |
|o3 = Partition{2, 2, 1}            |
|                                   |
|o3 : Partition                     |
+-----------------------------------+
|i4 : member(p, partitions(5,2))    |
|                                   |
|o4 = true                          |
+-----------------------------------+
|i5 : member(p, partitions(5,1))    |
|                                   |
|o5 = false                         |
+-----------------------------------+
|i6 : conjugate(p)                  |
|                                   |
|o6 = Partition{3, 2}               |
|                                   |
|o6 : Partition                     |
+-----------------------------------+

For ordered lists of exactly k nonnegative integers that sum to n, use
compositions, instead. In the following example, we create
Partition objects from the output of compositions to find all the partitions of
10, of length exactly 4, with no part greater than 5.

+-----------------------------------------------------------------------------+
|i7 : A = unique apply(compositions(4, 10), comp -> rsort comp);              |
+-----------------------------------------------------------------------------+
|i8 : B = select(A, a -> all(a, i -> 0<i and i<6));                           |
+-----------------------------------------------------------------------------+
|i9 : apply(B, b -> new Partition from b)                                     |
|                                                                             |
|o9 = {Partition{5, 3, 1, 1}, Partition{4, 4, 1, 1}, Partition{5, 2, 2, 1},   |
|     ------------------------------------------------------------------------|
|     Partition{4, 3, 2, 1}, Partition{3, 3, 3, 1}, Partition{4, 2, 2, 2},    |
|     ------------------------------------------------------------------------|
|     Partition{3, 3, 2, 2}}                                                  |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+

If partitions n is called on a negative integer n, an empty list is returned.
If a negative integer is given for k, it will cause an error.

See also
========

  * compositions -- list the compositions of an integer
  * conjugate(Partition) -- conjugate a
    partition
  * Partition -- a type of list representing a partition of a
    natural number
  * subsets -- produce the subsets of a set or list
  * combinatorial functions

Ways to use partitions:
=======================

  * "partitions(ZZ)"
  * "partitions(ZZ,ZZ)"

For the programmer
==================

The object partitions, is a method function.

parts -- display terms of a polynomial degree by degree
*******************************************************

Synopsis
========

  * Usage:
        parts f
  * Inputs:
      * f, a ring element,
  * Outputs:
      * an expression, with the terms of f parenthesized
        degree by degree. The degrees are given in increasing order

Description
===========

By default, Macaulay2 displays a polynomial RingElement, by
putting its terms in decreasing order, with respect to the MonomialOrder,
of the ambient ring. On the other hand, parts will display the
terms in order of increasing degree, regardless of the term order of the ring.
Parentheses group together all terms of the same degree.

+---------------------------------------+
|i1 : R = QQ[x,y];                      |
+---------------------------------------+
|i2 : f = (x + y + 1)^2                 |
|                                       |
|      2           2                    |
|o2 = x  + 2x*y + y  + 2x + 2y + 1      |
|                                       |
|o2 : R                                 |
+---------------------------------------+
|i3 : parts f                           |
|                                       |
|                         2           2 |
|o3 = (1) + (2x + 2y) + (x  + 2x*y + y )|
|                                       |
|o3 : Expression of class Sum           |
+---------------------------------------+
|i4 : R = QQ[x,y, MonomialOrder => Lex];|
+---------------------------------------+
|i5 : f = (x + y + 1)^2                 |
|                                       |
|      2                2               |
|o5 = x  + 2x*y + 2x + y  + 2y + 1      |
|                                       |
|o5 : R                                 |
+---------------------------------------+
|i6 : parts f                           |
|                                       |
|                         2           2 |
|o6 = (1) + (2x + 2y) + (x  + 2x*y + y )|
|                                       |
|o6 : Expression of class Sum           |
+---------------------------------------+

The output is an Expression, of a special class, see
Parenthesize. Accessing the individual parenthesized parts of
this expression is difficult, so for this purpose it may be better to use
part.

+-------------------+
|i7 : part(2, f)    |
|                   |
|      2           2|
|o7 = x  + 2x*y + y |
|                   |
|o7 : R             |
+-------------------+
|i8 : part(0, 1, f) |
|                   |
|o8 = 2x + 2y + 1   |
|                   |
|o8 : R             |
+-------------------+

See also
========

  * degree
  * monomials -- matrix of monomials in a ring element or
    matrix
  * part -- select terms of a polynomial by degree(s) or weight(s)
  * select -- select from a list, hash table, or string
  * terms -- provide a list of terms of a polynomial
  * someTerms -- select some terms of a polynomial
  * graded and multigraded polynomial rings
  * manipulating polynomials

Ways to use parts:
==================

  * "parts(RingElement)"

For the programmer
==================

The object parts, is a method function.

pdim -- calculate the projective dimension
******************************************

Synopsis
========

  * Usage:
        pdim M

Caveat
======

For now, the method is to measure the length of a projective resolution.

Ways to use pdim:
=================

  * "pdim(BettiTally)" -- see BettiTally, -- the class of all
    Betti tallies
  * pdim(CoherentSheaf) (Varieties) -- calculate
    the projective dimension
  * pdim(Module) -- calculate the projective dimension
    of a module

For the programmer
==================

The object pdim, is a method function.

pdim(Module) -- calculate the projective dimension of a module
**************************************************************

Synopsis
========

  * Function: pdim,
  * Usage:
        pdim M
  * Inputs:
      * M, a module,
  * Outputs:
      * an integer, the projective dimension

Description
===========

+------------------------------+
|i1 : R = QQ[x,y,z];           |
+------------------------------+
|i2 : I = ideal(x^2, x*y, y*z);|
|                              |
|o2 : Ideal of R               |
+------------------------------+
|i3 : M = R^1/I                |
|                              |
|o3 = cokernel | x2 xy yz |    |
|                              |
|                            1 |
|o3 : R-module, quotient of R  |
+------------------------------+
|i4 : res M                    |
|                              |
|      1      3      2         |
|o4 = R  <-- R  <-- R  <-- 0   |
|                              |
|     0      1      2      3   |
|                              |
|o4 : ChainComplex             |
+------------------------------+
|i5 : pdim M                   |
|                              |
|o5 = 2                        |
+------------------------------+
Notice this is one more than the projective dimension of I as an R-module.
+--------------------+
|i6 : res(module I)  |
|                    |
|      3      2      |
|o6 = R  <-- R  <-- 0|
|                    |
|     0      1      2|
|                    |
|o6 : ChainComplex   |
+--------------------+
|i7 : pdim(module I) |
|                    |
|o7 = 1              |
+--------------------+

Ways to use this method:
========================

  * pdim(Module) -- calculate the projective dimension
    of a module

peek -- examine contents of an object
*************************************

Synopsis
========

  * Usage:
        peek o
  * Inputs:
      * o, a thing, any Macaulay2 object
  * Outputs:
      * a net, laying out the internal contents of o to depth 1,
        bypassing installed methods for displaying the object

Description
===========

This function is used during debugging Macaulay2 programs to examine the
internal structure of objects.

+-------------------------------------------------+
|i1 : set {1, 2, 3}                               |
|                                                 |
|o1 = set {1, 2, 3}                               |
|                                                 |
|o1 : Set                                         |
+-------------------------------------------------+
|i2 : peek oo                                     |
|                                                 |
|o2 = Set{1 => 1}                                 |
|         2 => 1                                  |
|         3 => 1                                  |
+-------------------------------------------------+
|i3 : new MutableHashTable from { a => 3, b => 44}|
|                                                 |
|o3 = MutableHashTable{...2...}                   |
|                                                 |
|o3 : MutableHashTable                            |
+-------------------------------------------------+
|i4 : peek oo                                     |
|                                                 |
|o4 = MutableHashTable{a => 3 }                   |
|                      b => 44                    |
+-------------------------------------------------+

See also
========

  * peek' -- examine contents of an object

For the programmer
==================

The object peek, is a function closure.

peek' -- examine contents of an object
**************************************

Synopsis
========

  * Usage:
        peek'(n, o)
  * Inputs:
      * n, an integer,
      * o, a thing, any Macaulay2 object
  * Outputs:
      * a net, laying out the contents of o, bypassing installed
        formatting and printing methods to depth n

Description
===========

+--------------------------------------+
|i1 : s = factor 112                   |
|                                      |
|      4                               |
|o1 = 2 7                              |
|                                      |
|o1 : Expression of class Product      |
+--------------------------------------+
|i2 : peek s                           |
|                                      |
|              4                       |
|o2 = Product{2 , 7}                   |
+--------------------------------------+
|i3 : peek'_2 s                        |
|                                      |
|o3 = Product{Power{2, 4}, Power{7, 1}}|
+--------------------------------------+

See also
========

  * peek -- examine contents of an object

Ways to use peek':
==================

  * "peek'(ZZ,Thing)"

For the programmer
==================

The object peek', is a method function.

permanents -- ideal generated by square permanents of a matrix
**************************************************************

Synopsis
========

  * Usage:
        permanents(n,M)
  * Inputs:
      * n, an integer, the size of the permanents
      * M, a matrix,
  * Outputs:
      * an ideal,  generated by the permanents of the n by n
        subpermanents of M

Description
===========

The permanent of a square matrix N has the Laplace transform similar to the
Laplace transform of the determinant of N: but all signs are positive.
Permanents are used in combinatorics and in probability. They are
computationally difficult.
+--------------------------------------------+
|i1 : R = ZZ[a..f];                          |
+--------------------------------------------+
|i2 : M = genericMatrix(R,a,2,3)             |
|                                            |
|o2 = | a c e |                              |
|     | b d f |                              |
|                                            |
|             2      3                       |
|o2 : Matrix R  <-- R                        |
+--------------------------------------------+
|i3 : permanents(2,M)                        |
|                                            |
|o3 = ideal (b*c + a*d, b*e + a*f, d*e + c*f)|
|                                            |
|o3 : Ideal of R                             |
+--------------------------------------------+

Caveat
======

See also
========

  * determinant -- determinant of a matrix
  * minors -- ideal generated by minors
  * matrices

Ways to use permanents:
=======================

  * "permanents(ZZ,Matrix)"

For the programmer
==================

The object permanents, is a method function.

permutations -- produce all permutations of a list
**************************************************

Synopsis
========

  * Usage:
        permutations x
  * Inputs:
      * x, a visible list, or an integer,
  * Outputs:
      * a list of all the permutations of the visible list x, or, if x is an
        integer, of the list of integers from 0 through n-1

Description
===========

+-----------------------------------------------------------------------------+
|i1 : permutations {a,b,c,d}                                                  |
|                                                                             |
|o1 = {{a, b, c, d}, {a, b, d, c}, {a, c, b, d}, {a, c, d, b}, {a, d, b, c},  |
|     ------------------------------------------------------------------------|
|     {a, d, c, b}, {b, a, c, d}, {b, a, d, c}, {b, c, a, d}, {b, c, d, a},   |
|     ------------------------------------------------------------------------|
|     {b, d, a, c}, {b, d, c, a}, {c, a, b, d}, {c, a, d, b}, {c, b, a, d},   |
|     ------------------------------------------------------------------------|
|     {c, b, d, a}, {c, d, a, b}, {c, d, b, a}, {d, a, b, c}, {d, a, c, b},   |
|     ------------------------------------------------------------------------|
|     {d, b, a, c}, {d, b, c, a}, {d, c, a, b}, {d, c, b, a}}                 |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+
|i2 : permutations 3                                                          |
|                                                                             |
|o2 = {{0, 1, 2}, {0, 2, 1}, {1, 0, 2}, {1, 2, 0}, {2, 0, 1}, {2, 1, 0}}      |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

Ways to use permutations:
=========================

  * "permutations(VisibleList)"
  * "permutations(ZZ)"

For the programmer
==================

The object permutations, is a method function.

pfaffians -- ideal generated by Pfaffians
*****************************************

Synopsis
========

  * Usage:
        pfaffians(n,M)
  * Inputs:
      * n, an integer, the size of the Pfaffians
      * M, a matrix, which is skew-symmetric, and whose ring is
        an integral domain
  * Outputs:
      * an ideal, the ideal generated by the Pfaffians of the n
        by n principal submatrices of M

Description
===========

The determinant of a skew-symmetric matrix N, i.e., a matrix for which
transpose N + N == 0, is always a perfect square whose square root is called
the Pfaffian of N.
+---------------------------------+
|i1 : R = QQ[a..f];               |
+---------------------------------+
|i2 : M = genericSkewMatrix(R,a,4)|
|                                 |
|o2 = | 0  a  b  c |              |
|     | -a 0  d  e |              |
|     | -b -d 0  f |              |
|     | -c -e -f 0 |              |
|                                 |
|             4      4            |
|o2 : Matrix R  <-- R             |
+---------------------------------+
|i3 : pfaffians(2,M)              |
|                                 |
|o3 = ideal (a, b, d, c, e, f)    |
|                                 |
|o3 : Ideal of R                  |
+---------------------------------+
|i4 : pfaffians(4,M)              |
|                                 |
|o4 = ideal(c*d - b*e + a*f)      |
|                                 |
|o4 : Ideal of R                  |
+---------------------------------+
The Plücker embedding of Gr(2,6) and its secant variety:
+-----------------------------------------------------------------------------+
|i5 : S = QQ[y_0..y_14];                                                      |
+-----------------------------------------------------------------------------+
|i6 : M = genericSkewMatrix(S,y_0,6)                                          |
|                                                                             |
|o6 = | 0    y_0  y_1   y_2   y_3   y_4  |                                    |
|     | -y_0 0    y_5   y_6   y_7   y_8  |                                    |
|     | -y_1 -y_5 0     y_9   y_10  y_11 |                                    |
|     | -y_2 -y_6 -y_9  0     y_12  y_13 |                                    |
|     | -y_3 -y_7 -y_10 -y_12 0     y_14 |                                    |
|     | -y_4 -y_8 -y_11 -y_13 -y_14 0    |                                    |
|                                                                             |
|             6      6                                                        |
|o6 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i7 : pluecker = pfaffians(4,M);                                              |
|                                                                             |
|o7 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i8 : betti res pluecker                                                      |
|                                                                             |
|            0  1  2  3  4  5 6                                               |
|o8 = total: 1 15 35 42 35 15 1                                               |
|         0: 1  .  .  .  .  . .                                               |
|         1: . 15 35 21  .  . .                                               |
|         2: .  .  . 21 35 15 .                                               |
|         3: .  .  .  .  .  . 1                                               |
|                                                                             |
|o8 : BettiTally                                                              |
+-----------------------------------------------------------------------------+
|i9 : secantvariety = pfaffians(6,M)                                          |
|                                                                             |
|o9 = ideal(y y y  - y y y  - y y y   + y y y   + y y y   - y y y   + y y y   |
|            4 7 9    3 8 9    4 6 10    2 8 10    3 6 11    2 7 11    4 5 12 |
|     ------------------------------------------------------------------------|
|     - y y y   + y y  y   - y y y   + y y y   - y y  y   + y y y   - y y y   |
|        1 8 12    0 11 12    3 5 13    1 7 13    0 10 13    2 5 14    1 6 14 |
|     ------------------------------------------------------------------------|
|     + y y y  )                                                              |
|        0 9 14                                                               |
|                                                                             |
|o9 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
Pfaffians of a Moore matrix generate the ideal of a Heisenberg invariant
elliptic normal curve in projective Fourspace:
+------------------------------------------------------------+
|i10 : R = QQ[x_0..x_4]                                      |
|                                                            |
|o10 = R                                                     |
|                                                            |
|o10 : PolynomialRing                                        |
+------------------------------------------------------------+
|i11 : y = {0,1,13,-13,-1}                                   |
|                                                            |
|o11 = {0, 1, 13, -13, -1}                                   |
|                                                            |
|o11 : List                                                  |
+------------------------------------------------------------+
|i12 : M = matrix table(5,5, (i,j)-> x_((i+j)%5)*y_((i-j)%5))|
|                                                            |
|o12 = | 0      -x_1   -13x_2 13x_3  x_4    |                |
|      | x_1    0      -x_3   -13x_4 13x_0  |                |
|      | 13x_2  x_3    0      -x_0   -13x_1 |                |
|      | -13x_3 13x_4  x_0    0      -x_2   |                |
|      | -x_4   -13x_0 13x_1  x_2    0      |                |
|                                                            |
|              5      5                                      |
|o12 : Matrix R  <-- R                                       |
+------------------------------------------------------------+
|i13 : I = pfaffians(4,M);                                   |
|                                                            |
|o13 : Ideal of R                                            |
+------------------------------------------------------------+
|i14 : betti res I                                           |
|                                                            |
|             0 1 2 3                                        |
|o14 = total: 1 5 5 1                                        |
|          0: 1 . . .                                        |
|          1: . 5 5 .                                        |
|          2: . . . 1                                        |
|                                                            |
|o14 : BettiTally                                            |
+------------------------------------------------------------+

Caveat
======

The algorithm used is a modified Gaussian reduction/Bareiss algorithm, which
uses division and therefore we must assume that the ring of M is an integral
domain.

The skew symmetry of M is not checked, but the algorithm proceeds as if it
were, with somewhat unpredictable results!

See also
========

  * determinant -- determinant of a matrix
  * matrices

Ways to use pfaffians:
======================

  * "pfaffians(ZZ,Matrix)"

For the programmer
==================

The object pfaffians, is a method function.

pi
**

Description
===========

This constant represents the mathematical constant $\pi$, symbolically.

+-------------------------------------+
|i1 : pi                              |
|                                     |
|o1 = pi                              |
|                                     |
|o1 : Constant                        |
+-------------------------------------+
|i2 : +pi                             |
|                                     |
|o2 = 3.141592653589793               |
|                                     |
|o2 : RR (of precision 53)            |
+-------------------------------------+
|i3 : numeric_100 pi                  |
|                                     |
|o3 = 3.141592653589793238462643383279|
|                                     |
|o3 : RR (of precision 100)           |
+-------------------------------------+
|i4 : 2. * pi                         |
|                                     |
|o4 = 6.283185307179586               |
|                                     |
|o4 : RR (of precision 53)            |
+-------------------------------------+

For the programmer
==================

The object pi, is an instance of the type Constant.

pivots(Matrix) -- list of pivot locations of a matrix
*****************************************************

Synopsis
========

  * Function: pivots,
  * Usage:
        pivots f
  * Inputs:
      * f
  * Outputs:
      * a list, of positions (r,c) which are the positions of the
        non-zero lead terms (in each column)

Description
===========

+-------------------------------------------------------------+
|i1 : f = matrix{{1,3,0,0,3,5,2,0,0},{0,0,0,1,3,6,7,8,0}}     |
|                                                             |
|o1 = | 1 3 0 0 3 5 2 0 0 |                                   |
|     | 0 0 0 1 3 6 7 8 0 |                                   |
|                                                             |
|              2       9                                      |
|o1 : Matrix ZZ  <-- ZZ                                       |
+-------------------------------------------------------------+
|i2 : pivots f                                                |
|                                                             |
|o2 = {(0, 0), (0, 1), (1, 3), (1, 4), (1, 5), (1, 6), (1, 7)}|
|                                                             |
|o2 : List                                                    |
+-------------------------------------------------------------+

This function is used in the current implementation of the Smith normal form.

Caveat
======

Should be implemented in the engine.

See also
========

  * smithNormalForm -- smith normal form
    for a matrix over ZZ or a PID

Ways to use this method:
========================

  * pivots(Matrix) -- list of pivot locations of a
    matrix

plus -- addition
****************

Description
===========

plus(x,y,...) -- yields the sum of its arguments.

If there are no arguments, the answer is the integer 0.

For the programmer
==================

The object plus, is a compiled function.

poincare(ChainComplex) -- assemble degrees of a chain complex into a polynomial
*******************************************************************************

Synopsis
========

  * Function: poincare,
  * Usage:
        poincare C
  * Inputs:
      * C, a chain complex,
  * Outputs:
      * a ring element, in the Laurent polynomial ring
        degrees ring, whose variables correspond to the
        degrees of the ambient ring

Description
===========

We compute poincare, for a chain complex.

+----------------------------------+
|i1 : R = ZZ/32003[a..h];          |
+----------------------------------+
|i2 : C = res ideal(a*b, c*d, e*f) |
|                                  |
|      1      3      3      1      |
|o2 = R  <-- R  <-- R  <-- R  <-- 0|
|                                  |
|     0      1      2      3      4|
|                                  |
|o2 : ChainComplex                 |
+----------------------------------+
|i3 : poincare C                   |
|                                  |
|           2     4    6           |
|o3 = 1 - 3T  + 3T  - T            |
|                                  |
|o3 : ZZ[T]                        |
+----------------------------------+

Note that since the Hilbert series is additive in exact sequences, for a free
resolution this only depends on the Betti numbers of the resolution. For more
details, see Hilbert functions and free resolutions.

+-----------------------+
|i4 : b = betti C       |
|                       |
|            0 1 2 3    |
|o4 = total: 1 3 3 1    |
|         0: 1 . . .    |
|         1: . 3 . .    |
|         2: . . 3 .    |
|         3: . . . 1    |
|                       |
|o4 : BettiTally        |
+-----------------------+
|i5 : poincare b        |
|                       |
|           2     4    6|
|o5 = 1 - 3T  + 3T  - T |
|                       |
|o5 : ZZ[T]             |
+-----------------------+

See also
========

  * poincareN -- assemble degrees into polynomial
  * degreesRing -- the ring or monoid of degrees
  * hilbertFunction -- the Hilbert function
  * hilbertSeries -- compute the Hilbert series
  * hilbertPolynomial -- compute the Hilbert
    polynomial
  * reduceHilbert -- reduce a Hilbert series expression
  * poincare(BettiTally) -- the class of all Betti tallies

Ways to use this method:
========================

  * poincare(ChainComplex) -- assemble
    degrees of a chain complex into a polynomial

polarize -- given a monomial ideal, computes the squarefree monomial ideal obtained via polarization
****************************************************************************************************

Synopsis
========

  * Usage:
        polarize M
        polarize(M, VariableBaseName => "x")
  * Inputs:
      * M, a monomial ideal,
  * Optional inputs,:
      * VariableBaseName => a string, default value "z",
        specified letter or string for the new variables
  * Outputs:
      * I, a monomial ideal, a squarefree monomial ideal
        in a new polynomial ring

Description
===========

Polarization takes each minimal generator of a monomial ideal to a squarefree
monomial in a new ring. The procedure is to define a new variable $z_{i,j}$ for
the $j$th power of the $i$th variable in the original ring. For instance,
polarizing the ideal $I=(x^3, y^2, xy)$, of the ring $\mathbb{Q}[x,y]$, results
in the ideal $(z_{0,0}z_{0,1}z_{0,2}, z_{1,0}z_{1,1}, z_{0,0}z_{1,0})$ of
$\mathbb{Q}[z_{0,0},z_{0,1},z_{0,2},z_{1,0},z_{1,1}]$.

This is code adapted from the Monomial Ideals chapter, written by Greg Smith
and Serkan Hosten, of Computations in algebraic geometry with Macaulay 2. See
https://macaulay2.com/Book/ComputationsBook/chapters/monomialIdeals/chapter-
wrapper.pdf for the chapter PDF, and https://macaulay2.com/Book/ for more
information on this book.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = monomialIdeal(x^2,y^3,x*y^2*z,y*z^4);                               |
|                                                                             |
|o2 : MonomialIdeal of R                                                      |
+-----------------------------------------------------------------------------+
|i3 : J = polarize(I)                                                         |
|                                                                             |
|o3 = monomialIdeal (z      z      , z      z      z      , z      z      z   |
|                     {0, 0} {0, 1}   {1, 0} {1, 1} {1, 2}   {0, 0} {1, 0} {1,|
|     ------------------------------------------------------------------------|
|       z      , z      z      z      z      z      )                         |
|     1} {2, 0}   {1, 0} {2, 0} {2, 1} {2, 2} {2, 3}                          |
|                                                                             |
|o3 : MonomialIdeal of QQ[z      , z      , z      , z      , z      , z      |
|                          {0, 0}   {0, 1}   {1, 0}   {1, 1}   {1, 2}   {2, 0}|
|-----------------------------------------------------------------------------|
|, z      , z      , z      ]                                                 |
|   {2, 1}   {2, 2}   {2, 3}                                                  |
+-----------------------------------------------------------------------------+

By default, the variables in the new rings are named $z_{i,j}$. To use a
different letter (or longer string) instead of z, use the VariableBaseName
option.

+-----------------------------------------------------------------------------+
|i4 : R = QQ[a,b,c];                                                          |
+-----------------------------------------------------------------------------+
|i5 : I = monomialIdeal(a^2*b^2,b^2*c^2,a*b*c^4);                             |
|                                                                             |
|o5 : MonomialIdeal of R                                                      |
+-----------------------------------------------------------------------------+
|i6 : J = polarize(I, VariableBaseName => "x")                                |
|                                                                             |
|o6 = monomialIdeal (x      x      x      x      , x      x      x      x     |
|                     {0, 0} {0, 1} {1, 0} {1, 1}   {1, 0} {1, 1} {2, 0} {2,  |
|     ------------------------------------------------------------------------|
|       , x      x      x      x      x      x      )                         |
|     1}   {0, 0} {1, 0} {2, 0} {2, 1} {2, 2} {2, 3}                          |
|                                                                             |
|o6 : MonomialIdeal of QQ[x      , x      , x      , x      , x      , x      |
|                          {0, 0}   {0, 1}   {1, 0}   {1, 1}   {2, 0}   {2, 1}|
|-----------------------------------------------------------------------------|
|, x      , x      ]                                                          |
|   {2, 2}   {2, 3}                                                           |
+-----------------------------------------------------------------------------+
|i7 : J = polarize(I, VariableBaseName => "foo")                              |
|                                                                             |
|o7 = monomialIdeal (foo      foo      foo      foo      , foo      foo       |
|                       {0, 0}   {0, 1}   {1, 0}   {1, 1}     {1, 0}   {1,    |
|     ------------------------------------------------------------------------|
|       foo      foo      , foo      foo      foo      foo      foo           |
|     1}   {2, 0}   {2, 1}     {0, 0}   {1, 0}   {2, 0}   {2, 1}   {2,        |
|     ------------------------------------------------------------------------|
|       foo      )                                                            |
|     2}   {2, 3}                                                             |
|                                                                             |
|o7 : MonomialIdeal of QQ[foo      , foo      , foo      , foo      , foo     |
|                            {0, 0}     {0, 1}     {1, 0}     {1, 1}     {2, 0|
|-----------------------------------------------------------------------------|
| , foo      , foo      , foo      ]                                          |
|}     {2, 1}     {2, 2}     {2, 3}                                           |
+-----------------------------------------------------------------------------+

Variables are always indexed from 0. To use an unindexed variable naming
scheme, the polarized ideal can always be mapped to a new ring after it is
created. The following code is one way to do this.

+-------------------------------------------+
|i8 : S = ring J;                           |
+-------------------------------------------+
|i9 : T = QQ[a..h];                         |
+-------------------------------------------+
|i10 : F = map(T, S, first entries vars T); |
|                                           |
|o10 : RingMap T <-- S                      |
+-------------------------------------------+
|i11 : F(J)                                 |
|                                           |
|o11 = ideal (a*b*c*d, c*d*e*f, a*c*e*f*g*h)|
|                                           |
|o11 : Ideal of T                           |
+-------------------------------------------+

See also
========

  * isSquareFree -- whether something is square free
    monomial ideal
  * monomialIdeal -- make a monomial ideal
  * radical (MinimalPrimes) -- the radical of an ideal
  * substitution and maps between rings
  * working with multiple rings

Ways to use polarize:
=====================

  * "polarize(MonomialIdeal)"

For the programmer
==================

The object polarize, is a method function with options.

PolynomialRing -- the class of all ordered monoid rings
*******************************************************

Description
===========

Every element of a polynomial ring is also a RingElement.

See also
========

  * polynomial rings

Functions and methods returning a polynomial ring:
==================================================

  * degreesRing -- the ring or monoid of degrees
  * "InexactFieldFamily Array" -- see Ring Array, -- the
    standard way to make a polynomial ring
  * Ring Array -- the standard way to make a polynomial ring
  * "InexactFieldFamily List" -- see Ring List, -- make a
    local polynomial ring
  * Ring List -- make a local polynomial ring
  * "InexactFieldFamily Monoid" -- see Ring Monoid, -- make
    a polynomial ring
  * Ring Monoid -- make a polynomial ring

Methods that use a polynomial ring:
===================================

  * "ambient(PolynomialRing)" -- see ambient(Ring), --
    ambient polynomial ring
  * "codim(PolynomialRing)" -- see codim(QuotientRing),
    -- compute the codimension
  * degreeGroup(PolynomialRing) (missing documentation)
  * "describe(PolynomialRing)" -- see describe, -- real
    description
  * "dim(PolynomialRing)" -- see dim(Ring), -- compute the
    Krull dimension
  * "flattenRing(PolynomialRing)" -- see flattenRing, --
    write a ring as a (quotient of a) polynomial ring
  * "Grassmannian(ZZ,ZZ,PolynomialRing)" -- see Grassmannian(ZZ,ZZ),
    -- the Grassmannian of linear subspaces of a
    vector space
  * "heft(PolynomialRing)" -- see heft, -- heft vector of ring or
    monoid
  * hilbertSeries(PolynomialRing), --
    compute the Hilbert series of a ring
  * "isAffineRing(PolynomialRing)" -- see isAffineRing, --
    whether something is an affine ring
  * isHomogeneous(PolynomialRing) (missing documentation)
  * "isPolynomialRing(PolynomialRing)" -- see isPolynomialRing,
    -- whether something is a polynomial ring
  * "isSkewCommutative(PolynomialRing)" -- see isSkewCommutative,
    -- whether a ring has skew commuting variables
  * isWeylAlgebra(PolynomialRing) (missing documentation)
  * "newCoordinateSystem(PolynomialRing,Matrix)" -- see
    newCoordinateSystem, -- change variables
  * "newRing(PolynomialRing)" -- see newRing, -- make a copy of
    a ring, with some features changed
  * "numgens(PolynomialRing)" -- see numgens(Ring), --
    number of generators of a polynomial ring
  * "options(PolynomialRing)" -- see options(Monoid),
    -- get values used for optional arguments
  * "precision(PolynomialRing)" -- see precision,
  * presentation(PolynomialRing,QuotientRing)
    -- presentation of a
    quotient ring
  * selectVariables(List,PolynomialRing)
    -- make a subring of a
    polynomial ring generated by selected variables

For the programmer
==================

The object PolynomialRing, is a type, with
ancestor classes EngineRing, < Ring <
Type < MutableHashTable < HashTable
< Thing.

position -- the first element of a list satisfying a condition
**************************************************************

Synopsis
========

  * Usage:
        position(A, f)
        position(A, B, f)
        position(A, f, Reverse => true)
        position(n, f)
  * Inputs:
      * A, a visible list,
      * B, a visible list,
      * n, an integer,
      * f, a function,
  * Optional inputs,:
      * Reverse => ..., default value false
  * Outputs:
      * p, an integer, the first index to satisfy the boolean
        function f

Description
===========

position(A, f) returns the smallest index i such that f(A#i) is true. If no
element satisfies the condition, see null, is returned.

+--------------------------------------------+
|i1 : position((10,20,43,105,6,93), odd)     |
|                                            |
|o1 = 2                                      |
+--------------------------------------------+
|i2 : position((10,20,43,105,6,93), i -> i<0)|
+--------------------------------------------+

Use position(A, B, f) to return the smallest index i such that f(A#i, B#i) is
true.

+-------------------------------------------------------------------+
|i3 : position((10,20,43,105,6,93),(18,82,12,7,35,92), (a,b) -> a>b)|
|                                                                   |
|o3 = 2                                                             |
+-------------------------------------------------------------------+

The Reverse option will return the largest index instead.

+-----------------------------------------------------------------------------+
|i4 : position((10,20,43,105,6,93), odd, Reverse => true)                     |
|                                                                             |
|o4 = 5                                                                       |
+-----------------------------------------------------------------------------+
|i5 : position((10,20,43,105,6,93),(18,82,12,7,35,92), (a,b) -> a>b, Reverse  |
|                                                                             |
|o5 = 5                                                                       |
|-----------------------------------------------------------------------------|
|=> true)                                                                     |
+-----------------------------------------------------------------------------+

Use position(n, f) to return the smallest index i such that f(i) is true.

+--------------------------------------+
|i6 : position(17, i -> i^2 % 17 == 13)|
|                                      |
|o6 = 8                                |
+--------------------------------------+

To find all indices of elements satisfying the condition, see positions.
To return the elements, rather than their indices, see
select. The function number, counts the number of
elements satisfying the condition.

+----------------------------------------+
|i7 : positions((10,20,43,105,6,93), odd)|
|                                        |
|o7 = {2, 3, 5}                          |
|                                        |
|o7 : List                               |
+----------------------------------------+
|i8 : select((10,20,43,105,6,93), odd)   |
|                                        |
|o8 = (43, 105, 93)                      |
|                                        |
|o8 : Sequence                           |
+----------------------------------------+
|i9 : number((10,20,43,105,6,93), odd)   |
|                                        |
|o9 = 3                                  |
+----------------------------------------+

See also
========

  * minPosition -- position of the smallest element
  * maxPosition -- position of the largest element
  * number -- count how many elements of a list satisfy a
    condition
  * positions -- which elements of a list satisfy a condition
  * select -- select from a list, hash table, or string
  * take -- Take some elements from a list or sequence.
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use position:
=====================

  * "position(VisibleList,Function)"
  * "position(VisibleList,VisibleList,Function)"
  * "position(ZZ,Function)"

For the programmer
==================

The object position, is a method function with options.

positions -- which elements of a list satisfy a condition
*********************************************************

Synopsis
========

  * Usage:
        positions(A, f)
  * Inputs:
      * A, a visible list,
      * f, a function,
  * Outputs:
      * p, a list, the list of indices i such that f(A#i) is true

Description
===========

The indices are listed in ascending order. If no element satisfies the
condition, an empty list is returned.

+---------------------------------------------+
|i1 : positions((10,20,43,105,6,93), odd)     |
|                                             |
|o1 = {2, 3, 5}                               |
|                                             |
|o1 : List                                    |
+---------------------------------------------+
|i2 : positions((10,20,43,105,6,93), i -> i<0)|
|                                             |
|o2 = {}                                      |
|                                             |
|o2 : List                                    |
+---------------------------------------------+
|i3 : positions(100..110, isPrime)            |
|                                             |
|o3 = {1, 3, 7, 9}                            |
|                                             |
|o3 : List                                    |
+---------------------------------------------+

To find the first or last index of an element satisfying the condition, see
position. To return the elements, rather than their indices,
see select. The function number, counts the number
of elements satisfying the condition.

+-----------------------------------------------------+
|i4 : position((10,20,43,105,6), odd)                 |
|                                                     |
|o4 = 2                                               |
+-----------------------------------------------------+
|i5 : position((10,20,43,105,6), odd, Reverse => true)|
|                                                     |
|o5 = 3                                               |
+-----------------------------------------------------+
|i6 : select((10,20,43,105,6), odd)                   |
|                                                     |
|o6 = (43, 105)                                       |
|                                                     |
|o6 : Sequence                                        |
+-----------------------------------------------------+
|i7 : number((10,20,43,105,6), odd)                   |
|                                                     |
|o7 = 2                                               |
+-----------------------------------------------------+

See also
========

  * minPosition -- position of the smallest element
  * maxPosition -- position of the largest element
  * number -- count how many elements of a list satisfy a
    condition
  * position -- the first element of a list satisfying a
    condition
  * select -- select from a list, hash table, or string
  * take -- Take some elements from a list or sequence.
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use positions:
======================

  * "positions(MutableList,Function)"
  * "positions(VisibleList,Function)"

For the programmer
==================

The object positions, is a method function.

Power -- the class of all power expressions
*******************************************

Description
===========

Power is a type of Expression, representing a power.

Normally power expressions with an exponent equal to 1 will not be produced.
But it is desirable for factor, to return a product of powers,
and some of them will have 1 as exponent.  The routines for printing of
expressions will take this into account, suppress exponents equal to 1, and
arrange for parenthesization correctly.

Methods that use a power expression:
====================================

  * RingMap Power (missing documentation)

For the programmer
==================

The object Power, is a header type, with
ancestor classes Expression, < BasicList <
Thing.

power -- power
**************

Synopsis
========

  * Usage:
        (x,n)

Description
===========

power(x,n) yields the n-th power of x.

See also
========

  * ^ -- a binary operator, usually used for powers

For the programmer
==================

The object power, is a compiled function.

powermod -- powers of integers mod N
************************************

Synopsis
========

  * Usage:
        powermod(x,i,N)
  * Inputs:
      * x, an integer,
      * i, an integer,
      * N, an integer,
  * Outputs:
      * an integer, the i-th power of x modulo N

Description
===========

+--------------------------------------------+
|i1 : powermod(2,3,10)                       |
|                                            |
|o1 = 8                                      |
+--------------------------------------------+
|i2 : powermod(2,4,10)                       |
|                                            |
|o2 = 6                                      |
+--------------------------------------------+
|i3 : powermod(2,30000,100000)               |
|                                            |
|o3 = 9376                                   |
+--------------------------------------------+
|i4 : powermod(2,30000,100000000000000000000)|
|                                            |
|o4 = 35833790694215909376                   |
+--------------------------------------------+
|i5 : powermod(2,3331333,3331333)            |
|                                            |
|o5 = 2                                      |
+--------------------------------------------+

Ways to use powermod:
=====================

  * "powermod(ZZ,ZZ,ZZ)"

For the programmer
==================

The object powermod, is a compiled function.

powers
******

Synopsis
========

  * Usage:
        x^n
  * Inputs:
      * x, a ring map,
      * n, an integer,
  * Outputs:
      * the n-th power of x

Precision -- name of an optional argument.
******************************************

Functions with optional argument named Precision:
=================================================

  * hilbertBasis(Matrix,Precision=>...) (missing documentation)
  * intersect(RRi,RRi,Precision=>...) (missing documentation)
  * "intersection(RRi,RRi,Precision=>...)" -- see intersection(RRi,RRi),
    -- computes intersection of input intervals
  * "interval(...,Precision=>...)" -- see interval, --
    construct an interval
  * rays(Matrix,Precision=>...) (missing documentation)
  * "roots(RingElement,Precision=>...)" -- see roots(RingElement),
    -- compute the roots of a polynomial
  * "solve(...,Precision=>...)" -- see solve, -- solve linear
    equation(s)

For the programmer
==================

The object Precision, is a symbol.

precision
*********

Synopsis
========

  * Usage:
        precision x
  * Inputs:
      * x, a ring, a matrix, a ring element,
        or a number,
  * Outputs:
      * an integer, the precision to which x or its instances are
        stored

Description
===========

+----------------------+
|i1 : precision 3p111  |
|                      |
|o1 = 111              |
+----------------------+
|i2 : precision (RR[x])|
|                      |
|o2 = 53               |
+----------------------+
|i3 : precision 3      |
|                      |
|o3 = infinity         |
|                      |
|o3 : InfiniteNumber   |
+----------------------+

Ways to use precision:
======================

  * "precision(FractionField)"
  * "precision(GaloisField)"
  * "precision(InexactField)"
  * "precision(InexactNumber)"
  * "precision(Matrix)"
  * "precision(MutableMatrix)"
  * "precision(Number)"
  * "precision(PolynomialRing)"
  * "precision(QuotientRing)"
  * "precision(Ring)"
  * "precision(RingElement)"

For the programmer
==================

The object precision, is a method function.

prefixPath -- absolute locations of Macaulay2 files
***************************************************

Description
===========

The absolute location of a Macaulay2 file can be obtained by concatenating
three components: (a) the prefix, which is one of the members of the list
prefixPath,; (b) the relative location of the directory containing
the file, as recorded in the hash table Layout,; and (c)
the base name of the file. The value of prefixPath, is used
by installPackage, when determining how to direct
documentation hyperlinks from one package to another.

The initial value of prefixPath, contains just the following
two optional items. If the variable prefixDirectory, was
given a non-null value initially or by a -e command line argument, then it will
be the last element of prefixPath.  If the -q option was not
given on the command line used to invoke Macaulay2, then the value of
applicationDirectory()|"local/" will be the first element of prefixPath.
No attempt is made to synchronize the value of prefixPath,
with the values of prefixDirectory, and of
applicationDirectory(), which may change.

When running a newly compiled version of Macaulay2, adding something like -E
'prefixDirectory="/usr/"' to the command line is a good way to direct
hyperlinks created by installPackage, to the
documentation provided by an older copy of Macaulay2 installed with the prefix
/usr/, and that, in turn, is easily done within emacs by the keystroke sequence
C-u f12, which offers you a chance to edit the command line.

The initial value of prefixPath, described above can be
overridden by the user's initialization file).

The list prefixPath, should be distinguished from the list
path, which is used to locate files to be loaded, by functions
such as searchPath, load,
loadPackage, and needsPackage.

The following example shows the list of places where we might find the source
code of a package called Foo after it has been installed by
installPackage.

+-----------------------------------------------------------------------------+
|i1 : stack apply(prefixPath, p -> p | Layout#1#"packages" | "Foo.m2")        |
|                                                                             |
|o1 = /usr/local/share/Macaulay2/                                             |
|     ------------------------------------------------------------------------|
|     Foo.m2                                                                  |
+-----------------------------------------------------------------------------+

This example shows the list of places where we might reasonably find the html
file documenting a function named bar in a package called Foo.

+-----------------------------------------------------------------------------+
|i2 : stack apply(prefixPath, p -> p | replace("PKG","Foo",Layout#1#"packageht|
|                                                                             |
|o2 = /usr/local/share/doc/                                                   |
|     ------------------------------------------------------------------------|
|     Macaulay2/Foo/html/bar.html                                             |
|-----------------------------------------------------------------------------|
|ml") | "bar.html")                                                           |
+-----------------------------------------------------------------------------+

This example shows the list of places where we might reasonably find the info
file documenting a package called Foo.

+-----------------------------------------------------------------------------+
|i3 : stack apply(prefixPath, p -> p | Layout#1#"info" | "Foo.info")          |
|                                                                             |
|o3 = /usr/local/share/info/Foo.                                              |
|     ------------------------------------------------------------------------|
|     info                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * commandLine -- the command line arguments
  * Invoking the program
  * applicationDirectory -- the path to the user's
    application directory
  * prefixDirectory -- the prefix directory
  * path -- list of directories to look in
  * searchPath -- search a path for a
    file
  * load -- read Macaulay2 commands
  * loadPackage -- load a package
  * needsPackage -- load a package if not already loaded

For the programmer
==================

The object prefixPath, is a list.

preimage -- preimage of a map
*****************************

Description
===========

preimage of an ideal under a ring map
=====================================

  * Usage:
        preimage(f, I)
  * Inputs:
      * f, a ring map,
      * M, an ideal, in the target of $f$;
  * Outputs:
      * an ideal, the preimage of $I$ under the map $f$;
+------------------------------+
|i1 : R = QQ[x,y,z]            |
|                              |
|o1 = R                        |
|                              |
|o1 : PolynomialRing           |
+------------------------------+
|i2 : S = QQ[t,u]              |
|                              |
|o2 = S                        |
|                              |
|o2 : PolynomialRing           |
+------------------------------+
|i3 : f = map(R, S, {x*y, y*z})|
|                              |
|o3 = map (R, S, {x*y, y*z})   |
|                              |
|o3 : RingMap R <-- S          |
+------------------------------+
|i4 : preimage_f ideal(x^2,y^2)|
|                              |
|             2        2       |
|o4 = ideal (u , t*u, t )      |
|                              |
|o4 : Ideal of S               |
+------------------------------+

preimage of a submodule under a module map
==========================================

  * Usage:
        preimage(f, M)
  * Inputs:
      * f, a matrix,
      * M, a module, a submodule in the target of $f$;
  * Outputs:
      * a module, the preimage of $M$ under the map $f$;

$M$ and target, of $f$ should have the same ambient,
module.

See also
========

  * coimage -- coimage of a map
  * image -- image of a map
  * kernel -- kernel of a ringmap, matrix, or chain complex
  * source -- source of a map
  * target -- target of a map

Ways to use preimage:
=====================

  * "preimage(Matrix,Module)"
  * "preimage(RingMap,Ideal)"

For the programmer
==================

The object preimage, is a method function.

prepend -- add an element to the beginning of a list
****************************************************

Synopsis
========

  * Usage:
        prepend(x, L)
  * Inputs:
      * L, a basic list,
      * x, a thing,
  * Outputs:
      * a basic list, the list obtained by adding the element
        x to the beginning of list L

Description
===========

+-------------------------------+
|i1 : prepend(3, {1, 7, 8, 3})  |
|                               |
|o1 = {3, 1, 7, 8, 3}           |
|                               |
|o1 : List                      |
+-------------------------------+
|i2 : L = {"old", "old", "old"};|
+-------------------------------+
|i3 : prepend("new", L)         |
|                               |
|o3 = {new, old, old, old}      |
|                               |
|o3 : List                      |
+-------------------------------+

The new list will be of the same class, as L.

+-------------------+
|i4 : K = (a, b, c);|
+-------------------+
|i5 : prepend(z, K) |
|                   |
|o5 = (z, a, b, c)  |
|                   |
|o5 : Sequence      |
+-------------------+

Only a single element can be prepended with this function. To prepend the
elements of a list, use join. To add the new element to the end of
the list, or at a particular index, use append, or insert,
respectively.

+-----------------------+
|i6 : join((x, y, z), K)|
|                       |
|o6 = (x, y, z, a, b, c)|
|                       |
|o6 : Sequence          |
+-----------------------+
|i7 : append(K, z)      |
|                       |
|o7 = (a, b, c, z)      |
|                       |
|o7 : Sequence          |
+-----------------------+
|i8 : insert(1, z, K)   |
|                       |
|o8 = (a, z, b, c)      |
|                       |
|o8 : Sequence          |
+-----------------------+

Prepend always returns a new list, rather than modifying the input list, even
if L is a MutableList.

+--------------------------------------+
|i9 : L = new MutableList from {2,3,5};|
+--------------------------------------+
|i10 : peek prepend(7, L)              |
|                                      |
|o10 = MutableList{7, 2, 3, 5}         |
+--------------------------------------+
|i11 : peek L                          |
|                                      |
|o11 = MutableList{2, 3, 5}            |
+--------------------------------------+

Notice that the order of the arguments is switched in prepend versus append: we
write prepend(x, L) and append(L, x). A good way to remember this is that the
new element is visually placed before or after the list, depending on where we
want it to appear in the output.

See also
========

  * append -- add an element to the end of a list
  * insert -- copy a list, inserting an element
  * join -- join lists, sequences, and iterable objects
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use prepend:
====================

  * "prepend(Thing,BasicList)"

For the programmer
==================

The object prepend, is a compiled function.

presentation -- presentation of a module or ring
************************************************

See also
========

  * minimalPresentation -- compute a minimal
    presentation

Ways to use presentation:
=========================

  * presentation(Module) -- presentation of a
    module
  * presentation(PolynomialRing,QuotientRing)
    -- presentation of a
    quotient ring
  * "presentation(QuotientRing)" -- see
    presentation(PolynomialRing,QuotientRing),
    -- presentation of a
    quotient ring

For the programmer
==================

The object presentation, is a method function.

presentation(Module) -- presentation of a module
************************************************

Synopsis
========

  * Function: presentation,
  * Usage:
        presentation M
  * Inputs:
      * M
  * Outputs:
      * a matrix, a presentation matrix of M

Description
===========

A presentation of M is a map p so that coker p is isomorphic to M.  The
presentation obtained is expressed in terms of the given generators, i.e., the
modules cover M and target p are identical. The isomorphism can be obtained as
map(M,coker p,1).

Since a module M may be described as a submodule or a subquotient module of a
free module, some computation may be required to produce a presentation.  See
also trim, or minimalPresentation,
which do a bit more work to try to eliminate redundant generators.
+-----------------------------------------------------------------------------+
|i1 : R = QQ[a,b,c];                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal"a2-b2,abc"                                                    |
|                                                                             |
|             2    2                                                          |
|o2 = ideal (a  - b , a*b*c)                                                  |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : M = I/(I^2+a*I)                                                         |
|                                                                             |
|o3 = subquotient (| a2-b2 abc |, | a4-2a2b2+b4 a3bc-ab3c a2b2c2 a3-ab2 a2bc  |
|                                                                             |
|                               1                                             |
|o3 : R-module, subquotient of R                                              |
|-----------------------------------------------------------------------------|
||)                                                                           |
+-----------------------------------------------------------------------------+
|i4 : presentation M                                                          |
|                                                                             |
|o4 = {2} | a b2 0 0  |                                                       |
|     {3} | 0 0  a b2 |                                                       |
|                                                                             |
|             2      4                                                        |
|o4 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * minimalPresentation -- compute a minimal
    presentation
  * trim -- minimize generators and relations
  * generators -- provide matrix or list of generators
  * relations -- the defining relations
  * cover -- get the covering free module

Ways to use this method:
========================

  * presentation(Module) -- presentation of a
    module

presentation(PolynomialRing,QuotientRing) -- presentation of a quotient ring
****************************************************************************

Synopsis
========

  * Function: presentation,
  * Usage:
        presentation B
        presentation(A,B)
  * Inputs:
      * A
      * B, a quotient ring of A
  * Outputs:
      * a matrix, whose image is the ideal of A defining B

Description
===========

If A is not present, then it is understood to be the ultimate ambient
polynomial ring of B. In general, A may be any ring of which B is a quotient.

In the examples below, A is the ultimate ambient polynomial ring of A, B and C.
+-------------------------------+
|i1 : A = QQ[a..d];             |
+-------------------------------+
|i2 : B = A/(a^2,b^3);          |
+-------------------------------+
|i3 : C = B/(a*b*c,b*c*d, b^2); |
+-------------------------------+
|i4 : presentation A            |
|                               |
|o4 = 0                         |
|                               |
|             1                 |
|o4 : Matrix A  <-- 0           |
+-------------------------------+
|i5 : presentation B            |
|                               |
|o5 = | a2 b3 |                 |
|                               |
|             1      2          |
|o5 : Matrix A  <-- A           |
+-------------------------------+
|i6 : presentation C            |
|                               |
|o6 = | abc bcd b2 a2 b3 |      |
|                               |
|             1      5          |
|o6 : Matrix A  <-- A           |
+-------------------------------+
|i7 : presentation(B,C)         |
|                               |
|o7 = | abc bcd b2 |            |
|                               |
|             1      3          |
|o7 : Matrix B  <-- B           |
+-------------------------------+
|i8 : presentation(A,C)         |
|                               |
|o8 = | abc bcd b2 a2 b3 |      |
|                               |
|             1      5          |
|o8 : Matrix A  <-- A           |
+-------------------------------+
|i9 : minimalPresentation C     |
|                               |
|              QQ[a..d]         |
|o9 = --------------------------|
|       2   3                 2 |
|     (a , b , a*b*c, b*c*d, b )|
|                               |
|o9 : QuotientRing              |
+-------------------------------+

Caveat
======

The given presentation is often not minimal

See also
========

  * minimalPresentation -- compute a minimal
    presentation

Ways to use this method:
========================

  * presentation(PolynomialRing,QuotientRing)
    -- presentation of a
    quotient ring
  * "presentation(QuotientRing)"

pretty -- a pretty printer
**************************

Description
===========

This function is experimental and under development.

For the programmer
==================

The object pretty, is a method function with a single argument.

PrimitiveElement -- specify a primitive element
***********************************************

Description
===========

PrimitiveElement => g -- an option used with GF.

The value can be a ring element providing a primitive element, or the symbol
FindOne, (the default) which specifies that GF, should
search for a primitive element.

Functions with optional argument named PrimitiveElement:
========================================================

  * "GF(...,PrimitiveElement=>...)" -- see GF, -- make a finite field

For the programmer
==================

The object PrimitiveElement, is a symbol.

Print -- top level method for printing results
**********************************************

Synopsis
========

  * Usage:
        X#{topLevelMode,Print} = f
  * Inputs:
      * X, a type,
      * f, a function,  that can print something of type X
  * Consequences:
      * at top level, whenever it is time to print an output value of type X,
        the function f will be called

Description
===========

The function f is responsible for printing the output prompt and for applying
the BeforePrint, and AfterPrint, methods,
if desired.
+-----------------------------------------------------------------------------+
|i1 : code Thing#{Standard,Print}                                             |
|                                                                             |
|o1 = /usr/local/share/Macaulay2/Core/robust.m2:133:25-149:6:                 |
|     --source code:                                                          |
|     Thing#{Standard,Print} = x -> (                                         |
|          oprompt := concatenate(interpreterDepth:"o", toString lineNumber, "|
|          save := printWidth;                                                |
|          if printWidth != 0 then printWidth = printWidth - #oprompt;        |
|          z := robustNet x;                                                  |
|          wrapper := lookup(global Wrap,class x);                            |
|          if wrapper =!= null then (                                         |
|               fun := () -> z = wrapper z;                                   |
|               try timelimit(printingTimeLimit, fun)                         |
|               else (                                                        |
|                    alarm 0;                                                 |
|                    global debugError <- fun;                                |
|                    stderr << "--error or time limit reached in applying Wrap|
|               );                                                            |
|          << endl << oprompt << z << endl;                                   |
|          printWidth = save;                                                 |
|          )                                                                  |
|-----------------------------------------------------------------------------|
|= ");                                                                        |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|method to output; type 'debugError()' to see it" << endl << endl);           |
+-----------------------------------------------------------------------------+

For the programmer
==================

The object Print, is a symbol.

print -- print something
************************

Synopsis
========

  * Usage:
        print x

Description
===========

print x prints x on the standard output followed by a new line.
+-------------------------+
|i1 : print "Hello world!"|
|Hello world!             |
+-------------------------+
The return value is null.

For the programmer
==================

The object print, is a function closure.

printerr -- print something to stderr
*************************************

Synopsis
========

  * Usage:
        printerr x
  * Inputs:
      * x, a string, a net, or a basic list,

Description
===========

Print x, each line prepended with --, to stderr.  This is useful
for displaying warning messages and verbose logs.

+-----------------------------+
|i1 : printerr "Hello, world!"|
| -- Hello, world!            |
+-----------------------------+
|i2 : printerr("foo" || "bar")|
| -- foo                      |
| -- bar                      |
+-----------------------------+

If x is a basic list, then its elements are first joined with
horizontalJoin.

+---------------------------+
|i3 : printerr("foo", "bar")|
| -- foobar                 |
+---------------------------+

For the programmer
==================

The object printerr, is a function closure.

printingAccuracy -- current accuracy for printing numbers
*********************************************************

Synopsis
========

  * Usage:
        printingAccuracy = n
  * Inputs:
      * n, an integer,
  * Consequences:
      * Henceforth, inexact numbers are printed with at most n digits to the
        right of the decimal point displayed. The special case where n=-1 is
        interpreted as meaning n=infinity, and this case is used when a number
        appears alone on an output line.

Description
===========

+-------------------------------------------------------+
|i1 : printingPrecision,printingAccuracy                |
|                                                       |
|o1 = (6, -1)                                           |
|                                                       |
|o1 : Sequence                                          |
+-------------------------------------------------------+
|i2 : 1p100e-5/3                                        |
|                                                       |
|o2 = .000003333333333333333333333333333333             |
|                                                       |
|o2 : RR (of precision 100)                             |
+-------------------------------------------------------+
|i3 : x = {1p100e-5/3,1p100e-4/3,1p100e-3/3,1p100e-2/3} |
|                                                       |
|o3 = {.00000333333, .0000333333, .000333333, .00333333}|
|                                                       |
|o3 : List                                              |
+-------------------------------------------------------+
|i4 : printingAccuracy = 8                              |
|                                                       |
|o4 = 8                                                 |
+-------------------------------------------------------+
|i5 : x                                                 |
|                                                       |
|o5 = {.00000333, .00003333, .00033333, .00333333}      |
|                                                       |
|o5 : List                                              |
+-------------------------------------------------------+
|i6 : printingAccuracy = 4                              |
|                                                       |
|o6 = 4                                                 |
+-------------------------------------------------------+
|i7 : x                                                 |
|                                                       |
|o7 = {0, 0, .0003, .0033}                              |
|                                                       |
|o7 : List                                              |
+-------------------------------------------------------+

See also
========

  * printingAccuracy -- current accuracy for printing
    numbers
  * printingLeadLimit -- maximum number of leading
    zeroes to use when printing real numbers
  * printingTrailLimit -- maximum number of
    additional trailing digits to use when printing real numbers
  * printingSeparator -- string used to separate
    mantissa from exponent when printing real numbers
  * format -- format a string or a real number

For the programmer
==================

The object printingAccuracy, is an integer.

printingLeadLimit -- maximum number of leading zeroes to use when printing real numbers
***************************************************************************************

Synopsis
========

  * Usage:
        printingLeadLimit = n
  * Inputs:
      * n, an integer,
  * Consequences:
      * Real numbers are printed with at most n leading zeroes.

Description
===========

+--------------------------------+
|i1 : 1/30000000000.             |
|                                |
|o1 = 3.333333333333333e-11      |
|                                |
|o1 : RR (of precision 53)       |
+--------------------------------+
|i2 : printingLeadLimit          |
|                                |
|o2 = 5                          |
+--------------------------------+
|i3 : printingLeadLimit = 20     |
|                                |
|o3 = 20                         |
+--------------------------------+
|i4 : 1/30000000000.             |
|                                |
|o4 = .00000000003333333333333333|
|                                |
|o4 : RR (of precision 53)       |
+--------------------------------+

See also
========

  * printingPrecision -- current precision for
    printing numbers
  * printingAccuracy -- current accuracy for printing
    numbers
  * printingTrailLimit -- maximum number of
    additional trailing digits to use when printing real numbers
  * printingSeparator -- string used to separate
    mantissa from exponent when printing real numbers
  * format -- format a string or a real number

For the programmer
==================

The object printingLeadLimit, is an integer.

printingPrecision -- current precision for printing numbers
***********************************************************

Synopsis
========

  * Usage:
        printingPrecision = n
  * Inputs:
      * n, an integer,
  * Consequences:
      * Henceforth, inexact numbers are printed with at most n digits of
        precision. Meaningless digits will not be displayed. The special case
        where n=0 is interpreted as meaning n=infinity, and this case is used
        when a number appears alone on an output line to display all the
        meaningful digits.

Description
===========

+---------------------------------------+
|i1 : 1/3p100                           |
|                                       |
|o1 = .3333333333333333333333333333335  |
|                                       |
|o1 : RR (of precision 100)             |
+---------------------------------------+
|i2 : {1/3p100}                         |
|                                       |
|o2 = {.333333}                         |
|                                       |
|o2 : List                              |
+---------------------------------------+
|i3 : printingPrecision                 |
|                                       |
|o3 = 6                                 |
+---------------------------------------+
|i4 : printingPrecision = 16            |
|                                       |
|o4 = 16                                |
+---------------------------------------+
|i5 : {1/3p100}                         |
|                                       |
|o5 = {.3333333333333333}               |
|                                       |
|o5 : List                              |
+---------------------------------------+
|i6 : printingPrecision = 0             |
|                                       |
|o6 = 0                                 |
+---------------------------------------+
|i7 : {1/3p100}                         |
|                                       |
|o7 = {.3333333333333333333333333333335}|
|                                       |
|o7 : List                              |
+---------------------------------------+

For complex numbers, if printingAccuracy, is set to its
default value of -1, the two parts of the number are treated together (although
a digit further further to the right of the point may sometimes be displayed in
the smaller part).

+----------------------------------------+
|i8 : printingAccuracy                   |
|                                        |
|o8 = -1                                 |
+----------------------------------------+
|i9 : printingPrecision = 16             |
|                                        |
|o9 = 16                                 |
+----------------------------------------+
|i10 : {1p100e12/3+1p100/3*ii}           |
|                                        |
|o10 = {333333333333.3333+.33333*ii}     |
|                                        |
|o10 : List                              |
+----------------------------------------+
|i11 : printingAccuracy = 10             |
|                                        |
|o11 = 10                                |
+----------------------------------------+
|i12 : {1p100e12/3+1p100/3*ii}           |
|                                        |
|o12 = {333333333333.3333+.3333333333*ii}|
|                                        |
|o12 : List                              |
+----------------------------------------+

See also
========

  * printingAccuracy -- current accuracy for printing
    numbers
  * printingLeadLimit -- maximum number of leading
    zeroes to use when printing real numbers
  * printingTrailLimit -- maximum number of
    additional trailing digits to use when printing real numbers
  * printingSeparator -- string used to separate
    mantissa from exponent when printing real numbers
  * format -- format a string or a real number

For the programmer
==================

The object printingPrecision, is an integer.

printingSeparator -- string used to separate mantissa from exponent when printing real numbers
**********************************************************************************************

Synopsis
========

  * Usage:
        printingSeparator = s
  * Inputs:
      * s, a string,
  * Consequences:
      * The string s will be used to separate mantissa and exponent when
        printing real numbers.

Description
===========

+----------------------------+
|i1 : 3000000000000.         |
|                            |
|o1 = 3e12                   |
|                            |
|o1 : RR (of precision 53)   |
+----------------------------+
|i2 : printingSeparator      |
|                            |
|o2 = e                      |
+----------------------------+
|i3 : printingSeparator = "E"|
|                            |
|o3 = E                      |
+----------------------------+
|i4 : 3000000000000.         |
|                            |
|o4 = 3E12                   |
|                            |
|o4 : RR (of precision 53)   |
+----------------------------+

See also
========

  * printingPrecision -- current precision for
    printing numbers
  * printingAccuracy -- current accuracy for printing
    numbers
  * printingLeadLimit -- maximum number of leading
    zeroes to use when printing real numbers
  * printingTrailLimit -- maximum number of
    additional trailing digits to use when printing real numbers
  * format -- format a string or a real number

For the programmer
==================

The object printingSeparator, is a string.

printingTimeLimit
*****************

Description
===========

This variable specifies the number of seconds to allow for printing an output
line

For the programmer
==================

The object printingTimeLimit, is an integer.

printingTrailLimit -- maximum number of additional trailing digits to use when printing real numbers
****************************************************************************************************

Synopsis
========

  * Usage:
        printingTrailLimit = n
  * Inputs:
      * n, an integer,
  * Consequences:
      * Real numbers are printed with at most n additional trailing digits, in
        addition to those specified by printingPrecision.

Description
===========

+----------------------------+
|i1 : 3000000000000.         |
|                            |
|o1 = 3e12                   |
|                            |
|o1 : RR (of precision 53)   |
+----------------------------+
|i2 : printingTrailLimit     |
|                            |
|o2 = 5                      |
+----------------------------+
|i3 : printingTrailLimit = 20|
|                            |
|o3 = 20                     |
+----------------------------+
|i4 : 3000000000000.         |
|                            |
|o4 = 3000000000000          |
|                            |
|o4 : RR (of precision 53)   |
+----------------------------+

See also
========

  * printingPrecision -- current precision for
    printing numbers
  * printingAccuracy -- current accuracy for printing
    numbers
  * printingLeadLimit -- maximum number of leading
    zeroes to use when printing real numbers
  * printingSeparator -- string used to separate
    mantissa from exponent when printing real numbers
  * format -- format a string or a real number

For the programmer
==================

The object printingTrailLimit, is an integer.

printString -- lowlevel function to print a string, net, or symbol
******************************************************************

Description
===========

printString(o,s) -- send the string s to the output file o.

This function is intended for internal use only.

The argument s may also be a sequence or list, in which case its elements are
printed.  If an integer is encountered, then it specifies a number of spaces to
be printed.  If a symbol or indeterminate is encountered, its name is printed.
If null, is encountered, nothing is printed.

+----------------------------------------+
|i1 : printString(stdio, (a,10,"b",20,c))|
|a          b                    c       |
|o1 = stdio                              |
|                                        |
|o1 : File                               |
+----------------------------------------+

For the programmer
==================

The object printString, is a compiled function.

printWidth
**********

Synopsis
========

  * Usage:
        printWidth = n
  * Inputs:
      * n, an integer, the width to use for wrapping printed output
  * Consequences:
      * The function
      * wrap
      *  will use
      * n
      *  as the window width when wrapping certain types of output.

For the programmer
==================

The object printWidth, is an integer.

Product -- the class of all product expressions
***********************************************

Description
===========

Product is a type of Expression, representing a product.

Methods that use a product expression:
======================================

  * RingMap Product (missing documentation)

For the programmer
==================

The object Product, is a wrapper type, with
ancestor classes AssociativeExpression, <
Expression < BasicList < Thing.

product
*******

Description
===========

product provides the product of the members of a list or set, optionally with a
function applied to each one.

Ways to use product:
====================

  * product(List) -- product of elements
  * product(Set) -- product of elements
  * product(VirtualTally) -- product of
    elements
  * product(VisibleList,Function),
    -- product of values of a function
  * product(VisibleList,VisibleList,Function)
    -- product of results of
    applying a function pairwise
  * product(ZZ,Function) -- product of
    consecutive values of a function

For the programmer
==================

The object product, is a method function.

product(List) -- product of elements
************************************

Synopsis
========

  * Function: product,

Description
===========

product v yields the product of the elements in the list v.

+------------------------+
|i1 : product {1,2,3,4,5}|
|                        |
|o1 = 120                |
+------------------------+

Ways to use this method:
========================

  * product(List) -- product of elements

product(Set) -- product of elements
***********************************

Synopsis
========

  * Function: product,

Description
===========

product v yields the product of the elements in the set v.
+-----------------------------------------------------------------+
|i1 : a = set select(1..50, isPrime)                              |
|                                                                 |
|o1 = set {2, 3, 5, 37, 7, 41, 43, 11, 13, 47, 17, 19, 23, 29, 31}|
|                                                                 |
|o1 : Set                                                         |
+-----------------------------------------------------------------+
|i2 : product a                                                   |
|                                                                 |
|o2 = 614889782588491410                                          |
+-----------------------------------------------------------------+

See also
========

  * product

Ways to use this method:
========================

  * product(Set) -- product of elements

product(VirtualTally) -- product of elements
********************************************

Synopsis
========

  * Function: product,

Description
===========

product v yields the product of the elements in the tally v.

+-----------------------------------+
|i1 : a = tally{2,2,2,2,2,3,3,3,5,5}|
|                                   |
|o1 = Tally{2 => 5}                 |
|           3 => 3                  |
|           5 => 2                  |
|                                   |
|o1 : Tally                         |
+-----------------------------------+
|i2 : product a                     |
|                                   |
|o2 = 21600                         |
+-----------------------------------+

See also
========

  * product

Ways to use this method:
========================

  * product(VirtualTally) -- product of
    elements

product(VisibleList,Function) -- product of values of a function
****************************************************************

Synopsis
========

  * Function: product,

Description
===========

product(v,f) yields the product of the expressions obtained by applying f to
each of the elements of the list or sequence v.

+------------------------------+
|i1 : product(1 .. 5, i -> i^2)|
|                              |
|o1 = 14400                    |
+------------------------------+

See also
========

  * product

Ways to use this method:
========================

  * product(VisibleList,Function),
    -- product of values of a function

product(VisibleList,VisibleList,Function) -- product of results of applying a function pairwise
***********************************************************************************************

Synopsis
========

  * Function: product,

Description
===========

product(v,w,f) yields the product of the results obtained by applying f to each
of the pairs (i,j) of elements from the lists v and w, which should be of the
same length.

+----------------------------------------+
|i1 : M = monoid [x,y,z];                |
+----------------------------------------+
|i2 : product({2,3,4},{x,y,z},(i,j)->j^i)|
|                                        |
|      2 3 4                             |
|o2 = x y z                              |
|                                        |
|o2 : M                                  |
+----------------------------------------+

See also
========

  * product

Ways to use this method:
========================

  * product(VisibleList,VisibleList,Function)
    -- product of results of
    applying a function pairwise

product(ZZ,Function) -- product of consecutive values of a function
*******************************************************************

Synopsis
========

  * Function: product,

Description
===========

product(n,f) compute the product f(0) * f(1) * ... * f(n-1).

+---------------------------+
|i1 : product(5, i -> 2*i+1)|
|                           |
|o1 = 945                   |
+---------------------------+

See also
========

  * product

Ways to use this method:
========================

  * product(ZZ,Function) -- product of
    consecutive values of a function

ProductOrder -- product ordering
********************************

Description
===========

ProductOrder{n1, ..., nr} -- an optional argument of MonomialOrder,
in monoids handled by the engine, to indicate that
the monomial order is the product of r graded reverse lex orders, each with n1,
n2, ..., nr variables.

This syntax is left here for compatibility with previous Macaulay2 versions.
+-------------------------------------------------------+
|i1 : R = ZZ[a..e, MonomialOrder => ProductOrder {3,2}];|
+-------------------------------------------------------+
The new syntax is R = ZZ[a..e, MonomialOrder => {3,2}];.

See also
========

  * definition of product (block) orders

For the programmer
==================

The object ProductOrder, is a self initializing type,
with ancestor classes BasicList, <
Thing.

profile -- profile a function
*****************************

Description
===========

f = profile f -- replace a global function f by a profiled version.

The new function is the same as the old one, except that when the new function
is run, it will record the number of times it is called and the total execution
time.  Use the command profileSummary, to display the
data recorded so far.
+-----------------------------------------------------------------------------+
|i1 : R = ZZ/31[x]                                                            |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : f = (x^110+1)*(x^13+1)                                                  |
|                                                                             |
|      123    110    13                                                       |
|o2 = x    + x    + x   + 1                                                   |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+
|i3 : time factor f                                                           |
| -- used 0.00261483s (cpu); 0.00261159s (thread); 0s (gc)                    |
|                                                                             |
|              2        2       2       2       2       4     3      2        |
|o3 = (x + 1)(x  - 15)(x  + 8)(x  + 4)(x  + 2)(x  + 1)(x  - 4x  + 11x  - 4x + |
|                                                                             |
|o3 : Expression of class Product                                             |
|-----------------------------------------------------------------------------|
|    4     3     2            4     3     2            10     8     6     4   |
|1)(x  - 6x  - 2x  - 6x + 1)(x  + 9x  - 4x  + 9x + 1)(x   - 5x  - 8x  - 4x  - |
|-----------------------------------------------------------------------------|
|   2       10     8      6     4      2       10      8    6    4     2      |
|13x  + 1)(x   - 9x  + 15x  - 2x  + 10x  + 1)(x   - 10x  - x  - x  + 9x  +    |
|-----------------------------------------------------------------------------|
|    10      8     6     4      2       10      8     6     4     2       10  |
|1)(x   - 11x  - 8x  - 4x  + 11x  + 1)(x   - 13x  - 4x  - 8x  - 5x  + 1)(x   +|
|-----------------------------------------------------------------------------|
|   8     6      4     2       10      8     6     4      2       10      8   |
|13x  - 2x  + 15x  + 5x  + 1)(x   + 11x  - 4x  - 8x  - 11x  + 1)(x   + 10x  - |
|-----------------------------------------------------------------------------|
|  6      4     2       10     8    6    4      2       10     8      6     4 |
|2x  + 15x  - 9x  + 1)(x   + 9x  - x  - x  - 10x  + 1)(x   + 5x  + 15x  - 2x  |
|-----------------------------------------------------------------------------|
|     2                                                                       |
|+ 13x  + 1)                                                                  |
+-----------------------------------------------------------------------------+
|i4 : g = () -> factor f                                                      |
|                                                                             |
|o4 = g                                                                       |
|                                                                             |
|o4 : FunctionClosure                                                         |
+-----------------------------------------------------------------------------+
|i5 : g = profile g                                                           |
|                                                                             |
|o5 = g                                                                       |
|                                                                             |
|o5 : FunctionClosure                                                         |
+-----------------------------------------------------------------------------+
|i6 : h = profile("h", () -> factor f)                                        |
|                                                                             |
|o6 = h                                                                       |
|                                                                             |
|o6 : FunctionClosure                                                         |
+-----------------------------------------------------------------------------+
|i7 : for i to 10 do (g();h();h())                                            |
+-----------------------------------------------------------------------------+
|i8 : profileSummary                                                          |
|g: 11 times, used .0261745 seconds                                           |
|h: 22 times, used .0521394 seconds                                           |
+-----------------------------------------------------------------------------+

Ways to use profile:
====================

  * "profile(Function)"
  * "profile(String,Function)"

For the programmer
==================

The object profile, is a method function.

profileSummary -- display profiling data
****************************************

Description
===========

profileSummary -- a command that will display the data accumulated by running
functions produced with profile.

For the programmer
==================

The object profileSummary, is a command.

Program -- external program object
**********************************

Description
===========

A hash table returned by findProgram, with the following
strings as keys:

  * "name", the name of the loaded program.  This comes from the first argument
    passed to findProgram.  It is also what is displayed
    when printing a Program.
  * "path", the path to the program as determined by findProgram.
  * "prefix", a sequence of two strings identifying the prefix prepended to the
    binary executables.  See findProgram, specifically the
    description of the Prefix option, for more.
  * "version", a string containing the version number of the program.  Only
    present if findProgram, was called with the
    MinimumVersion option.

See also
========

  * programPaths -- user-defined external program paths
  * findProgram -- load external program

Functions and methods returning an object of class Program:
===========================================================

  * findProgram -- load external program

Methods that use an object of class Program:
============================================

  * Program << Thing -- run program with input
    redirection
  * "runProgram(Program,String)" -- see runProgram, -- run an
    external program
  * "runProgram(Program,String,String)" -- see runProgram, --
    run an external program

For the programmer
==================

The object Program, is a type, with ancestor
classes HashTable, < Thing.

Program << Thing -- run program with input redirection
******************************************************

Synopsis
========

  * Operator: <<,
  * Usage:
        prog << x
  * Inputs:
      * prog, an instance of the type Program,
      * x, a thing,
  * Outputs:
      * an instance of the type ProgramRun,

Description
===========

Write x to a temporary file and run prog with this file as input using input
redirection (the < operator in a POSIX shell).

+--------------------------+
|i1 : M2 = findProgram "M2"|
|                          |
|o1 = M2                   |
|                          |
|o1 : Program              |
+--------------------------+
|i2 : M2 << "2 + 2"        |
|                          |
|o2 = 0                    |
|                          |
|o2 : ProgramRun           |
+--------------------------+
|i3 : toString oo          |
|                          |
|o3 =                      |
|     i1 : 2 + 2           |
|                          |
|     o1 = 4               |
+--------------------------+

See also
========

  * findProgram -- load external program
  * runProgram -- run an external program

Ways to use this method:
========================

  * Program << Thing -- run program with input
    redirection

programPaths -- user-defined external program paths
***************************************************

Description
===========

A mutable hash table containing user-defined paths to external programs used by
Macaulay2.  Its keys are strings containing the names of programs and must
coincide with the first argument of findProgram.

It is only necessary to define a path in this way if a program is installed in
a non-standard location.  In particular, see findProgram,
already checks prefixDirectory | currentLayout#"programs", (where the programs
shipped with Macaulay2 are installed) and all of the directories in the user's
PATH environment variable.

If you use a particular program frequently and it is installed in a
non-standard location, then it may be useful to add a line to your
initialization file, defining its path in this way.

See also
========

  * Program -- external program object
  * findProgram -- load external program

For the programmer
==================

The object programPaths, is a mutable hash table.

ProgramRun -- result of running an external program
***************************************************

Description
===========

A hash table returned by runProgram, with the following
strings as keys:

  * "command", the command that was used to run the program.
  * "output", the output of the program to stdout.
  * "error", the output of the program to stderr.
  * "return value", the return value of the program, possibly multiplied by 256
    (see run).  Note that this is what is displayed when printing a
    ProgramRun object.

In addition, if runProgram, is called with the KeepFiles
option set to true, then the following keys will be present:

  * "output file", the path to a file containing the output of the program to
    stdout.
  * "error file", the path to a file containing the output of the program to
    stderr.

See also
========

  * runProgram -- run an external program

Functions and methods returning an object of class ProgramRun:
==============================================================

  * runProgram -- run an external program

Methods that use an object of class ProgramRun:
===============================================

  * status(ProgramRun) -- get the return status
    of a program run

For the programmer
==================

The object ProgramRun, is a type, with ancestor
classes HashTable, < Thing.

Projective -- whether to produce a projective Hilbert polynomial
****************************************************************

Description
===========

Projective -- an optional argument used with hilbertPolynomial,
to specify the way the Hilbert Polynomial is expressed.

Functions with optional argument named Projective:
==================================================

  * hilbertPolynomial(...,Projective=>...)
    -- choose how to
    display the Hilbert polynomial

For the programmer
==================

The object Projective, is a symbol.

ProjectiveHilbertPolynomial -- the class of all Hilbert polynomials
*******************************************************************

Description
===========

For convenience, these polynomials are expressed in terms of the Hilbert
polynomials of projective space.

The functions degree, and dim, are designed so they
correspond the degree and dimension of the algebraic variety that may have been
used to produce the Hilbert polynomial.
+-------------------------------------------+
|i1 : Z = Proj(QQ[x_0..x_12]/(x_0^3+x_12^3))|
|                                           |
|o1 = Z                                     |
|                                           |
|o1 : ProjectiveVariety                     |
+-------------------------------------------+
|i2 : hilbertPolynomial Z                   |
|                                           |
|o2 = P  - 3*P   + 3*P                      |
|      9      10      11                    |
|                                           |
|o2 : ProjectiveHilbertPolynomial           |
+-------------------------------------------+

Functions and methods returning a projective Hilbert polynomial:
================================================================

  * "ProjectiveHilbertPolynomial * ZZ" -- see *, -- a binary
    operator, usually used for multiplication
  * "ZZ * ProjectiveHilbertPolynomial" -- see *, -- a binary
    operator, usually used for multiplication
  * "ProjectiveHilbertPolynomial + ProjectiveHilbertPolynomial" -- see +,
    -- a unary or binary operator, usually used for addition
  * "ProjectiveHilbertPolynomial + ZZ" -- see +, -- a unary or binary
    operator, usually used for addition
  * "ZZ + ProjectiveHilbertPolynomial" -- see +, -- a unary or binary
    operator, usually used for addition
  * "- ProjectiveHilbertPolynomial" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "ProjectiveHilbertPolynomial - ProjectiveHilbertPolynomial" -- see -,
    -- a unary or binary operator, usually used for negation or subtraction
  * "ProjectiveHilbertPolynomial - ZZ" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "ZZ - ProjectiveHilbertPolynomial" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * diff(ProjectiveHilbertPolynomial)
  * diff(ProjectiveHilbertPolynomial,ZZ)
  * hilbertPolynomial -- compute the Hilbert
    polynomial
  * projectiveHilbertPolynomial -- Hilbert
    polynomial of projective space

Methods that use a projective Hilbert polynomial:
=================================================

  * degree(ProjectiveHilbertPolynomial)
  * dim(ProjectiveHilbertPolynomial)
    -- the degree of the Hilbert
    polynomial
  * euler(ProjectiveHilbertPolynomial) (Varieties)
    -- constant term of the
    Hilbert polynomial
  * hilbertSeries(ProjectiveHilbertPolynomial)
    -- compute the Hilbert
    series of a projective Hilbert polynomial
  * ProjectiveHilbertPolynomial == ProjectiveHilbertPolynomial (missing
    documentation)
  * ProjectiveHilbertPolynomial == ZZ (missing documentation)
  * ProjectiveHilbertPolynomial ZZ, --
    value of polynomial
  * ZZ == ProjectiveHilbertPolynomial (missing documentation)

For the programmer
==================

The object ProjectiveHilbertPolynomial, is a
type, with ancestor classes HashTable, <
Thing.

projectiveHilbertPolynomial -- Hilbert polynomial of projective space
*********************************************************************

Description
===========

projectiveHilbertPolynomial n -- produces the projective Hilbert polynomial
corresponding to projective space of dimension n.
projectiveHilbertPolynomial(n,d) -- produces the projective Hilbert polynomial
corresponding to the graded ring of projective space of dimension n, but with
its generator in degree -d.

See also
========

  * ProjectiveHilbertPolynomial -- the
    class of all Hilbert polynomials

Ways to use projectiveHilbertPolynomial:
========================================

  * "projectiveHilbertPolynomial(ZZ)"
  * "projectiveHilbertPolynomial(ZZ,ZZ)"

For the programmer
==================

The object projectiveHilbertPolynomial, is a
method function.

ProjectiveHilbertPolynomial ZZ -- value of polynomial
*****************************************************

Synopsis
========

  * Operator: SPACE,

Description
===========

P i -- the value of a projective Hilbert polynomial P at an integer i.

+------------------------------------------------------+
|i1 : P = projectiveHilbertPolynomial 2                |
|                                                      |
|o1 = P                                                |
|      2                                               |
|                                                      |
|o1 : ProjectiveHilbertPolynomial                      |
+------------------------------------------------------+
|i2 : apply(0 .. 12, i -> P i)                         |
|                                                      |
|o2 = (1, 3, 6, 10, 15, 21, 28, 36, 45, 55, 66, 78, 91)|
|                                                      |
|o2 : Sequence                                         |
+------------------------------------------------------+

See also
========

  * ProjectiveHilbertPolynomial -- the
    class of all Hilbert polynomials

Ways to use this method:
========================

  * ProjectiveHilbertPolynomial ZZ, --
    value of polynomial

promote -- promote to another ring
**********************************

Synopsis
========

  * Usage:
        promote(f,R)
  * Inputs:
      * f, a ring element, an ideal, or a
        matrix, over some base ring of R
      * R, a ring,
  * Outputs:
      * a ring element, or a matrix, over R

Description
===========

Promote the given ring element or matrix f to an element or matrix of R, via
the natural map to R. This is semantically equivalent to creating the natural
ring map from ring f --> R and mapping f via this map.

+---------------------------+
|i1 : R = QQ[a..d]; f = a^2;|
+---------------------------+
|i3 : S = R/(a^2-b-1);      |
+---------------------------+
|i4 : promote(2/3,S)        |
|                           |
|     2                     |
|o4 = -                     |
|     3                     |
|                           |
|o4 : S                     |
+---------------------------+
|i5 : F = map(R,QQ);  F(2/3)|
|                           |
|o5 : RingMap R <-- QQ      |
|                           |
|     2                     |
|o6 = -                     |
|     3                     |
|                           |
|o6 : R                     |
+---------------------------+
|i7 : promote(f,S)          |
|                           |
|o7 = b + 1                 |
|                           |
|o7 : S                     |
+---------------------------+
|i8 : G = map(S,R); G(f)    |
|                           |
|o8 : RingMap S <-- R       |
|                           |
|o9 = b + 1                 |
|                           |
|o9 : S                     |
+---------------------------+

Promotion of real numbers to rational numbers is accomplished by using all of
the bits of the internal representation.

+---------------------------------+
|i10 : promote(101.,QQ)           |
|                                 |
|o10 = 101                        |
|                                 |
|o10 : QQ                         |
+---------------------------------+
|i11 : promote(.101,QQ)           |
|                                 |
|       3638908498915361          |
|o11 = -----------------          |
|      36028797018963968          |
|                                 |
|o11 : QQ                         |
+---------------------------------+
|i12 : factor denominator oo      |
|                                 |
|       55                        |
|o12 = 2                          |
|                                 |
|o12 : Expression of class Product|
+---------------------------------+
|i13 : ooo + 0.                   |
|                                 |
|o13 = .101                       |
|                                 |
|o13 : RR (of precision 53)       |
+---------------------------------+
|i14 : oo === .101                |
|                                 |
|o14 = true                       |
+---------------------------------+

For promotion of ring elements, there is the following shorter notation.

+----------+
|i15 : 13_R|
|          |
|o15 = 13  |
|          |
|o15 : R   |
+----------+

If you wish to promote a module to another ring, either promote the
corresponding matrices, use the natural ring map, or use tensor product of
matrices or modules.

+-----------------------------------------+
|i16 : use R;                             |
+-----------------------------------------+
|i17 : I = ideal(a^2,a^3,a^4)             |
|                                         |
|              2   3   4                  |
|o17 = ideal (a , a , a )                 |
|                                         |
|o17 : Ideal of R                         |
+-----------------------------------------+
|i18 : promote(I,S)                       |
|                                         |
|                              2          |
|o18 = ideal (b + 1, a*b + a, b  + 2b + 1)|
|                                         |
|o18 : Ideal of S                         |
+-----------------------------------------+
|i19 : m = image matrix{{a^2,a^3,a^4}}    |
|                                         |
|o19 = image | a2 a3 a4 |                 |
|                                         |
|                              1          |
|o19 : R-module, submodule of R           |
+-----------------------------------------+
|i20 : promote(gens m,S)                  |
|                                         |
|o20 = | b+1 ab+a b2+2b+1 |               |
|                                         |
|              1      3                   |
|o20 : Matrix S  <-- S                    |
+-----------------------------------------+
|i21 : G m                                |
|                                         |
|o21 = image | b+1 ab+a b2+2b+1 |         |
|                                         |
|                              1          |
|o21 : S-module, submodule of S           |
+-----------------------------------------+
|i22 : m ** S                             |
|                                         |
|o22 = cokernel {2} | a  0  |             |
|               {3} | -1 a  |             |
|               {4} | 0  -1 |             |
|                                         |
|                             3           |
|o22 : S-module, quotient of S            |
+-----------------------------------------+
A special feature is that if f is rational, and R is not an algebra over
QQ, then an element of R is provided by attempting the evident division.

See also
========

  * baseRings -- store the list of base rings of a ring
  * lift -- lift to another ring
  * liftable -- whether lifting to another ring is possible
  * substitution and maps between rings
  * substitute -- substituting values for variables
  * Matrix ** Ring -- tensor product
  * setupPromote -- set up promote from one ring to
    another

Ways to use promote:
====================

  * "promote(RR,type of QQ)"
  * promote(Constant,type of InexactNumber') (missing documentation)
  * promote(Constant,type of RingElement) (missing documentation)
  * promote(IndexedVariable,type of RingElement) (missing documentation)

For the programmer
==================

The object promote, is a method function.

protect -- protect a symbol
***************************

Synopsis
========

  * Usage:
        protect s
  * Inputs:
      * s, a symbol,
  * Outputs:
      * s, a symbol,
  * Consequences:
      * the symbol s is protected from having its value changed

Description
===========

There is no function for unprotecting symbols.

+---------------------+
|i1 : mutable symbol s|
|                     |
|o1 = true            |
+---------------------+
|i2 : s = 5           |
|                     |
|o2 = 5               |
+---------------------+
|i3 : s               |
|                     |
|o3 = 5               |
+---------------------+
|i4 : protect symbol s|
|                     |
|o4 = s               |
|                     |
|o4 : Symbol          |
+---------------------+
|i5 : mutable symbol s|
|                     |
|o5 = false           |
+---------------------+
|i6 : try s = 7       |
+---------------------+
|i7 : s               |
|                     |
|o7 = 5               |
+---------------------+

See also
========

  * isMutable -- whether something may be modified
  * try -- catch an error

For the programmer
==================

The object protect, is a compiled function.

prune -- prune, e.g., compute a minimal presentation
****************************************************

See also
========

  * minimalPresentation -- compute a minimal
    presentation

Ways to use prune:
==================

  * "prune(Ideal)" -- see minimalPresentation(Ideal),
    -- compute a minimal presentation of the
    quotient ring defined by an ideal
  * "prune(Matrix)" -- see minimalPresentation(Matrix),
    -- minimally present source and target of
    a matrix
  * "prune(ChainComplex)" -- see minimalPresentation(Module),
    -- minimal presentation of a module
  * "prune(ChainComplexMap)" -- see minimalPresentation(Module),
    -- minimal presentation of a module
  * "prune(GradedModule)" -- see minimalPresentation(Module),
    -- minimal presentation of a module
  * "prune(GradedModuleMap)" -- see minimalPresentation(Module),
    -- minimal presentation of a module
  * "prune(Module)" -- see minimalPresentation(Module),
    -- minimal presentation of a module
  * "prune(Ring)" -- see minimalPresentation(Ring),
    -- compute a minimal presentation of a
    quotient ring
  * prune(CoherentSheaf) (missing documentation)
  * prune(SheafMap) (missing documentation)
  * prune(SheafOfRings) (missing documentation)

For the programmer
==================

The object prune, is a method function with options.

pruningMap
**********

Description
===========

This symbol is used as a key for storing results in modules, by
minimalPresentation.

For the programmer
==================

The object pruningMap, is a symbol.

Pseudocode -- the class of pseudocodes
**************************************

Description
===========

The Macaulay2 interpreter compiles its language into pseudocode, which is
evaluated later, step by step.  At each step, the evaluator is considering a
pseudocode item.  These pseudocode items are normally not available to the
user, but the internal function pseudocode, can convert a
function closure to pseudocode and display their contents, the function
value, can evaluate it (bindings of values to local symbols are enclosed
with the pseudocode), the operator ===, can be used for
equality testing, and when the debugger is activated after an error, the
variable current, contains the pseudocode step whose execution
produced the error.

See also
========

  * disassemble -- disassemble a pseudocode or function

Types of Pseudocode:
====================

  * "PseudocodeClosure"

Methods that use an object of class Pseudocode:
===============================================

  * "code(Pseudocode)" -- see code, -- display source code
  * disassemble(Pseudocode) (missing documentation)
  * "locate(Pseudocode)" -- see locate, -- locate source code
  * Pseudocode _ ZZ (missing documentation)
  * toList(Pseudocode) (missing documentation)
  * value(Pseudocode) -- execute pseudocode

For the programmer
==================

The object Pseudocode, is a type, with ancestor
class Thing.

pseudocode -- produce the pseudocode for a function
***************************************************

Synopsis
========

  * Usage:
        pseudocode f
  * Inputs:
      * f, a function closure,
  * Outputs:
      * an instance of the type PseudocodeClosure, the
        pseudocode of the function f

Description
===========

+----------------------------------------------------------------------------+
|i1 : pseudocode(() -> 2+4*3)                                                |
|                                                                            |
|o1 = function restargs false                                                |
|              numparms 0                                                    |
|              framesize 0                                                   |
|              frameID 11672                                                 |
|              body 2-OP + 2                                                 |
|                          2-OP * 4                                          |
|                                 3                                          |
|                                                                            |
|o1 : PseudocodeClosure                                                      |
+----------------------------------------------------------------------------+
|i2 : disassemble oo                                                         |
|                                                                            |
|o2 = (function restargs: false numparms: 0 framesize: 0 frameID: 11672 (2-OP|
|     + 2 (2-OP * 4 3)))                                                     |
+----------------------------------------------------------------------------+
|i3 : pseudocode functionBody(() -> 2+4*3)                                   |
|                                                                            |
|o3 = 2-OP + 2                                                               |
|            2-OP * 4                                                        |
|                   3                                                        |
|                                                                            |
|o3 : Pseudocode                                                             |
+----------------------------------------------------------------------------+
|i4 : disassemble oo                                                         |
|                                                                            |
|o4 = (2-OP + 2 (2-OP * 4 3))                                                |
+----------------------------------------------------------------------------+

One can look at specific part of the code by using _:

+----------------------------------------------------------------------+
|i5 : pseudocode resolution                                            |
|                                                                      |
|o5 = function restargs true                                           |
|              numparms 1                                              |
|              framesize 1                                             |
|              frameID 203                                             |
|              body adjacent global-fetch 403                          |
|                            sequence local-fetch 1 1                  |
|                                     adjacent global-fetch 352        |
|                                              sequence local-fetch 0 1|
|                                                       local-fetch 0 0|
|                                                                      |
|o5 : PseudocodeClosure                                                |
+----------------------------------------------------------------------+
|i6 : oo_4_1_1_0                                                       |
|                                                                      |
|o6 = global-fetch 352                                                 |
|                                                                      |
|o6 : Pseudocode                                                       |
+----------------------------------------------------------------------+
|i7 : value oo                                                         |
|                                                                      |
|o7 = override                                                         |
|                                                                      |
|o7 : CompiledFunction                                                 |
+----------------------------------------------------------------------+

It may be useful to look at code during debugging, as in the following
demonstration.

+-----------------------------------------------------------------------------+
|i8 : load "Macaulay2Doc/demo1.m2"                                            |
+-----------------------------------------------------------------------------+
|i9 : code g                                                                  |
|                                                                             |
|o9 = /usr/local/share/Macaulay2/Macaulay2Doc/                                |
|     demo1.m2:11:4-14:9: --source code:                                      |
|     g = y -> (                                                              |
|          c := f(y-1);                                                       |
|          d := f(y-2);                                                       |
|          c+d)                                                               |
+-----------------------------------------------------------------------------+
|i10 : g 2                                                                    |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|8:10-8:13: --source code:                                                    |
|     b := 1/x;                                                               |
|-----------------------------------------------------------------------------|
|error: division by zero                                                      |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
|ii11 : code current                                                          |
|                                                                             |
|oo11 = /usr/local/share/Macaulay2/Macaulay2Doc/                              |
|       demo1.m2:8:10-8:13: --source code:                                    |
|            b := 1/x;                                                        |
+-----------------------------------------------------------------------------+
|ii12 : current                                                               |
|                                                                             |
|oo12 = 2-OP / 1                                                              |
|              local-fetch 0 0                                                |
|                                                                             |
|oo12 : PseudocodeClosure                                                     |
+-----------------------------------------------------------------------------+
|ii13 : disassemble current                                                   |
|                                                                             |
|oo13 = (2-OP / 1 (local-fetch 0 0))                                          |
+-----------------------------------------------------------------------------+

See also
========

  * disassemble -- disassemble a pseudocode or function

Ways to use pseudocode:
=======================

  * pseudocode(FunctionBody) (missing documentation)
  * pseudocode(FunctionClosure) (missing documentation)

For the programmer
==================

The object pseudocode, is a compiled function.

pseudoRemainder -- compute the pseudo-remainder
***********************************************

Synopsis
========

  * Usage:
        pseudoRemainder(f,g)
  * Inputs:
      * f, a ring element,
      * g, a ring element, in the same polynomial ring R as
        f
  * Outputs:
      * a ring element, the pseudo remainder of the
        polynomial f by the polynomial g

Description
===========

Let x be the first variable of R appearing in g.  Suppose that g has degree d
in x, and that the coefficient of x^d in g (as an element of R, but not
involving the variable x) is c. The pseudo remainder of f by g is the
polynomial h of degree less than d in x such that c^(e-d+1) * f = q*g + h,
where f has degree e in x.
+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : f = x^4                                                                 |
|                                                                             |
|      4                                                                      |
|o2 = x                                                                       |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+
|i3 : g = x^2*y + 13*x^2*y^4 +x*y^2-3*x - 1                                   |
|                                                                             |
|        2 4    2       2                                                     |
|o3 = 13x y  + x y + x*y  - 3x - 1                                            |
|                                                                             |
|o3 : R                                                                       |
+-----------------------------------------------------------------------------+
|i4 : (lg, cg) = topCoefficients g                                            |
|                                                                             |
|       2     4                                                               |
|o4 = (x , 13y  + y)                                                          |
|                                                                             |
|o4 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i5 : h = pseudoRemainder(f,g)                                                |
|                                                                             |
|            6        4       3      4        2            2                  |
|o5 = - 27x*y  + 87x*y  - 2x*y  + 14y  - 27x*y  + 6x*y - 6y  + 27x + y + 9    |
|                                                                             |
|o5 : R                                                                       |
+-----------------------------------------------------------------------------+
|i6 : (cg^3 * f - h) % g                                                      |
|                                                                             |
|o6 = 0                                                                       |
|                                                                             |
|o6 : R                                                                       |
+-----------------------------------------------------------------------------+
|i7 : q = (cg^3 * f - h) // g                                                 |
|                                                                             |
|         2 8      2 5        6        4    2 2      3      4            2    |
|o7 = 169x y  + 26x y  - 13x*y  + 39x*y  + x y  - x*y  + 14y  + 3x*y - 6y  + y|
|     ------------------------------------------------------------------------|
|     + 9                                                                     |
|                                                                             |
|o7 : R                                                                       |
+-----------------------------------------------------------------------------+
|i8 : cg^3*f == h + q*g                                                       |
|                                                                             |
|o8 = true                                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

There is no pseudo-division implemented, and the only way to change the notion
of what the top variable is, is to change to a ring where the variables are in
a different order

See also
========

  * topCoefficients -- first variable and its
    coefficient of a polynomial or matrix

Ways to use pseudoRemainder:
============================

  * "pseudoRemainder(RingElement,RingElement)"

For the programmer
==================

The object pseudoRemainder, is a method function.

pullback -- compute the pullback morphism
*****************************************

See also
========

  * pushout -- compute the pushout morphism

Ways to use pullback:
=====================

  * pullback(Matrix,Matrix) (missing documentation)
  * pullback(SheafMap,SheafMap) (missing documentation)

For the programmer
==================

The object pullback, is a method function with options.

pushForward(RingMap,Module)
***************************

Synopsis
========

  * Function: pushForward,
  * Usage:
        pushForward(F,M)
  * Inputs:
      * F, a ring map F: R --> S, graded
      * M, over S, graded
  * Optional inputs,:
      * MonomialOrder => ..., default value Eliminate, the type of monomial
        ordering to use in the computation, as keyword, either Eliminate,
        see ProductOrder, or Lex,
      * UseHilbertFunction => a Boolean value, default value
        true, whether to use the Hilbert function as a hint for the Gröbner
        basis computation, if M and F are homogeneous
      * StopBeforeComputation => a Boolean value, default value
        false, see gb(...,StopBeforeComputation=>...),
      * DegreeLimit => a Boolean value, default value {}, see
        gb(...,DegreeLimit=>...),
      * PairLimit => a Boolean value, default value infinity,
        see gb(...,PairLimit=>...),
      * Strategy (missing documentation) => ..., default value null,
  * Outputs:
      * a module, M, considered as an R-module

Description
===========

Currently, R and S must both be polynomial rings over the same base field.

This function first checks to see whether M will be a finitely generated
R-module via F.  If not, an error message describing the codimension of M/(vars
of S)M is given (this is equal to the dimension of R if and only if M is a
finitely generated R-module.

Assuming that it is, the push forward F_*(M) is computed.  This is done by
first finding a presentation for M in terms of a set of elements that generates
M as an S-module, and then applying the routine coimage, to a
map whose target is M and whose source is a free module over R.

Example: The Auslander-Buchsbaum formula
========================================

Let's illustrate the Auslander-Buchsbaum formula. First construct some rings
and make a module of projective dimension 2.
+--------------------------------------+
|i1 : R4 = ZZ/32003[a..d];             |
+--------------------------------------+
|i2 : R5 = ZZ/32003[a..e];             |
+--------------------------------------+
|i3 : R6 = ZZ/32003[a..f];             |
+--------------------------------------+
|i4 : M = coker genericMatrix(R6,a,2,3)|
|                                      |
|o4 = cokernel | a c e |               |
|              | b d f |               |
|                                      |
|                              2       |
|o4 : R6-module, quotient of R6        |
+--------------------------------------+
|i5 : pdim M                           |
|                                      |
|o5 = 2                                |
+--------------------------------------+
Create ring maps.
+-----------------------------------------------------------------------------+
|i6 : G = map(R6,R5,{a+b+c+d+e+f,b,c,d,e})                                    |
|                                                                             |
|o6 = map (R6, R5, {a + b + c + d + e + f, b, c, d, e})                       |
|                                                                             |
|o6 : RingMap R6 <-- R5                                                       |
+-----------------------------------------------------------------------------+
|i7 : F = map(R5,R4,random(R5^1, R5^{4:-1}))                                  |
|                                                                             |
|o7 = map (R5, R4, {107a + 4376b - 5570c + 3187d + 3783e, - 5307a + 8570b -   |
|                                                                             |
|o7 : RingMap R5 <-- R4                                                       |
|-----------------------------------------------------------------------------|
|15344c + 8444d - 10480e, 10359a - 7464b - 8251c + 2653d + 5071e, - 6203a +   |
|-----------------------------------------------------------------------------|
|12365b - 13508c - 9480d - 11950e})                                           |
+-----------------------------------------------------------------------------+
The module M, when thought of as an R5 or R4 module, has the same depth, but
since depth M + pdim M = dim ring, the projective dimension will drop to 1,
respectively 0, for these two rings.
+----------------------------------------+
|i8 : P = pushForward(G,M)               |
|                                        |
|o8 = cokernel | c -de               |   |
|              | d bc-ad+bd+cd+d2+de |   |
|                                        |
|                              2         |
|o8 : R5-module, quotient of R5          |
+----------------------------------------+
|i9 : pdim P                             |
|                                        |
|o9 = 1                                  |
+----------------------------------------+
|i10 : Q = pushForward(F,P)              |
|                                        |
|        3                               |
|o10 = R4                                |
|                                        |
|o10 : R4-module, free, degrees {0..1, 0}|
+----------------------------------------+
|i11 : pdim Q                            |
|                                        |
|o11 = 0                                 |
+----------------------------------------+

Example: generic projection of a homogeneous coordinate ring
============================================================

We compute the pushforward N of the homogeneous coordinate ring M of the
twisted cubic curve in P^3.
+-------------------------------------------------+
|i12 : P3 = QQ[a..d];                             |
+-------------------------------------------------+
|i13 : M = comodule monomialCurveIdeal(P3,{1,2,3})|
|                                                 |
|o13 = cokernel | c2-bd bc-ad b2-ac |             |
|                                                 |
|                               1                 |
|o13 : P3-module, quotient of P3                  |
+-------------------------------------------------+
The result is a module with the same codimension, degree and genus as the
twisted cubic, but the support is a cubic in the plane, necessarily having one
node.
+-----------------------------------------------------------------------------+
|i14 : P2 = QQ[a,b,c];                                                        |
+-----------------------------------------------------------------------------+
|i15 : F = map(P3,P2,random(P3^1, P3^{-1,-1,-1}))                             |
|                                                                             |
|                    8         4    4   9    5    8    10   3    1     7      |
|o15 = map (P3, P2, {-a + 2b + -c + -d, -a + -b + -c + --d, -a + -b + --c +   |
|                    9         7    7   7    2    7     7   7    3    10      |
|                                                                             |
|o15 : RingMap P3 <-- P2                                                      |
|-----------------------------------------------------------------------------|
|2                                                                            |
|-d})                                                                         |
|3                                                                            |
+-----------------------------------------------------------------------------+
|i16 : N = pushForward(F,M)                                                   |
|                                                                             |
|o16 = cokernel {0} | 2746576531440ab-2534266045640b2-24211900548045ac+       |
|               {1} | -1917669755925a+2274660185954b-8894633060340c           |
|                                                                             |
|                               2                                             |
|o16 : P2-module, quotient of P2                                              |
|-----------------------------------------------------------------------------|
|23443561995420bc-14394825893700c2                                            |
|                                                                             |
|-----------------------------------------------------------------------------|
|41713631071245a2-35589962516920b2-617284418550345ac+601115991475020bc-       |
|-41832913217265a+52275870074434b-238856615455140c                            |
|-----------------------------------------------------------------------------|
|382187702981700c2 3911698210192282843849600b3-66754622794389240566784600b2c-3|
|                  -1498815844682001881230562400a2+254768860673620533091717387|
|-----------------------------------------------------------------------------|
|649526991392070087758253375ac2+3478861359062826352315326900bc2-23720190082343|
|2ab-1049823644956341399785147872b2-3147838871484802066664262615ac+25700166781|
|-----------------------------------------------------------------------------|
|18457722851500c3                                                             |
|91191391969780310bc-2690990325409766765255811900c2                           |
|-----------------------------------------------------------------------------|
|0                                                                            |
|3104325504225a3-8141096469258a2b+7037566250256ab2-1999589995808b3+           |
|-----------------------------------------------------------------------------|
|                                                                             |
|7766700637860a2c-13411647220680abc+5703323436000b2c+6283781809200ac2-        |
|-----------------------------------------------------------------------------|
|                                 |                                           |
|5281643577600bc2+1508835384000c3 |                                           |
+-----------------------------------------------------------------------------+
|i17 : hilbertPolynomial M                                                    |
|                                                                             |
|o17 = - 2*P  + 3*P                                                           |
|           0      1                                                          |
|                                                                             |
|o17 : ProjectiveHilbertPolynomial                                            |
+-----------------------------------------------------------------------------+
|i18 : hilbertPolynomial N                                                    |
|                                                                             |
|o18 = - 2*P  + 3*P                                                           |
|           0      1                                                          |
|                                                                             |
|o18 : ProjectiveHilbertPolynomial                                            |
+-----------------------------------------------------------------------------+
|i19 : ann N                                                                  |
|                                                                             |
|                          3                 2                    2           |
|o19 = ideal(3104325504225a  - 8141096469258a b + 7037566250256a*b  -         |
|      -----------------------------------------------------------------------|
|                    3                 2                                      |
|      1999589995808b  + 7766700637860a c - 13411647220680a*b*c +             |
|      -----------------------------------------------------------------------|
|                    2                    2                   2               |
|      5703323436000b c + 6283781809200a*c  - 5281643577600b*c  +             |
|      -----------------------------------------------------------------------|
|                    3                                                        |
|      1508835384000c )                                                       |
|                                                                             |
|o19 : Ideal of P2                                                            |
+-----------------------------------------------------------------------------+
Note: these examples are from the original Macaulay script by David Eisenbud.

Caveat
======

The module M must be homogeneous, as must R, S, and f.  If you need this
function in more general situations, please write it and send it to the
Macaulay2 authors, or ask them to write it!

Ways to use this method:
========================

  * pushForward(RingMap,Module)

pushout -- compute the pushout morphism
***************************************

See also
========

  * pullback -- compute the pullback morphism

Ways to use pushout:
====================

  * pushout(Matrix,Matrix) (missing documentation)
  * pushout(SheafMap,SheafMap) (missing documentation)

For the programmer
==================

The object pushout, is a method function.

QQ -- the class of all rational numbers
***************************************

Description
===========

+--------------+
|i1 : 1/2 + 3/5|
|              |
|     11       |
|o1 = --       |
|     10       |
|              |
|o1 : QQ       |
+--------------+

Functions and methods returning a rational number:
==================================================

  * "QQ * QQ" -- see *, -- a binary operator, usually used for
    multiplication
  * "QQ * ZZ" -- see *, -- a binary operator, usually used for
    multiplication
  * "ZZ * QQ" -- see *, -- a binary operator, usually used for
    multiplication
  * "+ QQ" -- see +, -- a unary or binary operator, usually used for
    addition
  * "QQ + QQ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "QQ + ZZ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "ZZ + QQ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "- QQ" -- see -, -- a unary or binary operator, usually used for
    negation or subtraction
  * "QQ - QQ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "QQ - ZZ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "ZZ - QQ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "QQ / QQ" -- see /, -- a binary operator, usually used for
    division
  * "QQ / ZZ" -- see /, -- a binary operator, usually used for
    division
  * "ZZ / QQ" -- see /, -- a binary operator, usually used for
    division
  * "gcd(QQ,QQ)" -- see gcd, -- greatest common divisor
  * "gcd(QQ,ZZ)" -- see gcd, -- greatest common divisor
  * "gcd(ZZ,QQ)" -- see gcd, -- greatest common divisor
  * latticeVolume (Polyhedra) -- Returning the lattice
    volume of a polyhedron.
  * volume (Polyhedra) -- computes the volume of a polytope

Methods that use a rational number:
===================================

  * "QQ !" -- see !, -- factorial
  * "CC % QQ" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "QQ % QQ" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "QQ % ZZ" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "RR % QQ" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "CC * QQ" -- see *, -- a binary operator, usually used for
    multiplication
  * "QQ * CC" -- see *, -- a binary operator, usually used for
    multiplication
  * "QQ * RR" -- see *, -- a binary operator, usually used for
    multiplication
  * "QQ * RRi" -- see *, -- a binary operator, usually used for
    multiplication
  * "RR * QQ" -- see *, -- a binary operator, usually used for
    multiplication
  * "RRi * QQ" -- see *, -- a binary operator, usually used for
    multiplication
  * "CC + QQ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "QQ + CC" -- see +, -- a unary or binary operator, usually used
    for addition
  * "QQ + RR" -- see +, -- a unary or binary operator, usually used
    for addition
  * "QQ + RRi" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RR + QQ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RRi + QQ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "CC - QQ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "QQ - CC" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "QQ - RR" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "QQ - RRi" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RR - QQ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RRi - QQ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "CC / QQ" -- see /, -- a binary operator, usually used for
    division
  * "QQ / CC" -- see /, -- a binary operator, usually used for
    division
  * "QQ / RR" -- see /, -- a binary operator, usually used for
    division
  * "QQ / RRi" -- see /, -- a binary operator, usually used for
    division
  * "RR / QQ" -- see /, -- a binary operator, usually used for
    division
  * "RRi / QQ" -- see /, -- a binary operator, usually used for
    division
  * "CC // QQ" -- see //, -- a binary operator, usually used for
    quotient
  * "QQ // QQ" -- see //, -- a binary operator, usually used for
    quotient
  * "QQ // ZZ" -- see //, -- a binary operator, usually used for
    quotient
  * "RR // QQ" -- see //, -- a binary operator, usually used for
    quotient
  * "abs(QQ)" -- see abs, -- absolute value function
  * "QQ * BettiTally" -- see BettiTally, -- the class of all
    Betti tallies
  * CC == QQ (missing documentation)
  * "crossPolytope(ZZ,QQ)" -- see crossPolytope (Polyhedra),
    -- computes the d-dimensional crosspolytope with
    diameter 2s
  * "factor(QQ)" -- see factor(RingElement), --
    factor a ring element
  * "hypercube(ZZ,QQ)" -- see hypercube (Polyhedra), -- Returns
    the d-dimensional hypercube
  * "hypercube(ZZ,QQ,QQ)" -- see hypercube (Polyhedra), --
    Returns the d-dimensional hypercube
  * "hypercube(ZZ,QQ,ZZ)" -- see hypercube (Polyhedra), --
    Returns the d-dimensional hypercube
  * "hypercube(ZZ,ZZ,QQ)" -- see hypercube (Polyhedra), --
    Returns the d-dimensional hypercube
  * "imaginaryPart(QQ)" -- see imaginaryPart, -- imaginary
    part
  * "interval(QQ)" -- see interval, -- construct an interval
  * "interval(QQ,QQ)" -- see interval, -- construct an interval
  * "interval(QQ,RR)" -- see interval, -- construct an interval
  * "interval(QQ,ZZ)" -- see interval, -- construct an interval
  * "interval(RR,QQ)" -- see interval, -- construct an interval
  * "interval(ZZ,QQ)" -- see interval, -- construct an interval
  * isMember(QQ,RRi) -- membership test in an
    interval
  * "isReal(QQ)" -- see isReal, -- whether a number is real
  * "lcm(QQ,QQ)" -- see lcm, -- least common multiple
  * "lcm(QQ,ZZ)" -- see lcm, -- least common multiple
  * "lcm(ZZ,QQ)" -- see lcm, -- least common multiple
  * "lift(CC,type of QQ)" -- see lift, -- lift to another ring
  * "lift(Ideal,type of QQ)" -- see lift, -- lift to another ring
  * "lift(Matrix,type of CC_*,type of QQ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of QQ,type of QQ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of QQ,type of ZZ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of RR_*,type of QQ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of RRi_*,type of QQ)" -- see lift, -- lift to
    another ring
  * "lift(QQ,type of QQ)" -- see lift, -- lift to another ring
  * "lift(QQ,type of ZZ)" -- see lift, -- lift to another ring
  * "lift(RR,type of QQ)" -- see lift, -- lift to another ring
  * "lift(RRi,type of QQ)" -- see lift, -- lift to another ring
  * "promote(RR,type of QQ)" -- see promote, -- promote to
    another ring
  * QQ * Polyhedron (Polyhedra) -- rescales a
    polyhedron by a given positive factor
  * QQ == CC (missing documentation)
  * QQ == QQ (missing documentation)
  * QQ == RR (missing documentation)
  * QQ == RRi (missing documentation)
  * QQ == ZZ (missing documentation)
  * "realPart(QQ)" -- see realPart, -- real part
  * "round(QQ)" -- see round, -- round a number
  * RR == QQ (missing documentation)
  * RRi == QQ (missing documentation)
  * "simplex(ZZ,QQ)" -- see simplex (Polyhedra), -- Produces a
    full-dimensional simplex
  * "toCC(QQ)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,QQ)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,QQ,QQ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,QQ,RR)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,QQ,ZZ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,RR,QQ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,ZZ,QQ)" -- see toCC, -- convert to high-precision
    complex number
  * ZZ == QQ (missing documentation)

For the programmer
==================

The object QQ, is a ring, with ancestor classes
Number, < Thing.

QRDecomposition -- compute a QR decomposition of a real matrix
**************************************************************

Synopsis
========

  * Usage:
        (Q,R) = QRDecomposition A
  * Inputs:
      * A, a matrix, or a mutable matrix,
        over $RR_{53}$
  * Outputs:
      * Q, a matrix,
      * R, a matrix, $(Q,R)$ is the QR-decomposition of $A$

Description
===========

If $A$ is a $m \times n$ matrix whose columns are linearly independent, the
$QR$ decomposition of $A$ is $QR = A$, where $Q$ is an $m \times m$ orthogonal
matrix and $R$ is an upper triangular $m \times n$ matrix.

+----------------------------------------------------------------------+
|i1 : A = random(RR^5, RR^3)                                           |
|                                                                      |
|o1 = | .892712  .714827 .909047  |                                    |
|     | .673395  .89189  .314897  |                                    |
|     | .29398   .231053 .0741835 |                                    |
|     | .632944  .461944 .808694  |                                    |
|     | .0258884 .775187 .362835  |                                    |
|                                                                      |
|                5         3                                           |
|o1 : Matrix RR    <-- RR                                              |
|              53        53                                            |
+----------------------------------------------------------------------+
|i2 : (Q,R) = QRDecomposition A                                        |
|                                                                      |
|o2 = (| -.677131  .143091  .247563  |, | -1.31837 -1.22811 -1.1883  |)|
|      | -.510777  -.324257 -.666994 |  | 0        -.816018 -.175579 | |
|      | -.222987  .0524494 -.347041 |  | 0        0        .523234  | |
|      | -.480095  .156448  .507738  |                                 |
|      | -.0196366 -.92041  .339994  |                                 |
|                                                                      |
|o2 : Sequence                                                         |
+----------------------------------------------------------------------+

$R$ is upper triangular, and $Q$ is (close to) orthogonal.

+----------------------------------------------+
|i3 : R                                        |
|                                              |
|o3 = | -1.31837 -1.22811 -1.1883  |           |
|     | 0        -.816018 -.175579 |           |
|     | 0        0        .523234  |           |
|                                              |
|                3         3                   |
|o3 : Matrix RR    <-- RR                      |
|              53        53                    |
+----------------------------------------------+
|i4 : (transpose Q) * Q                        |
|                                              |
|o4 = | 1            -2.77556e-17 2.77556e-17 ||
|     | -2.77556e-17 1            -2.498e-16  ||
|     | 2.77556e-17  -2.498e-16   1           ||
|                                              |
|                3         3                   |
|o4 : Matrix RR    <-- RR                      |
|              53        53                    |
+----------------------------------------------+
|i5 : clean(1e-10, oo)                         |
|                                              |
|o5 = | 1 0 0 |                                |
|     | 0 1 0 |                                |
|     | 0 0 1 |                                |
|                                              |
|                3         3                   |
|o5 : Matrix RR    <-- RR                      |
|              53        53                    |
+----------------------------------------------+
|i6 : R - (transpose Q) * A                    |
|                                              |
|o6 = | 0           0            2.22045e-16 | |
|     | 0           -3.33067e-16 0           | |
|     | 8.32667e-17 -1.66533e-16 1.11022e-16 | |
|                                              |
|                3         3                   |
|o6 : Matrix RR    <-- RR                      |
|              53        53                    |
+----------------------------------------------+
|i7 : clean(1e-10, oo)                         |
|                                              |
|o7 = | 0 0 0 |                                |
|     | 0 0 0 |                                |
|     | 0 0 0 |                                |
|                                              |
|                3         3                   |
|o7 : Matrix RR    <-- RR                      |
|              53        53                    |
+----------------------------------------------+

If the input is a MutableMatrix, then so are the output
matrices.

+-----------------------------------------------------------------------------+
|i8 : A = mutableMatrix(RR_53, 13, 5);                                        |
+-----------------------------------------------------------------------------+
|i9 : fillMatrix A                                                            |
|                                                                             |
|o9 = | .706096 .606588  .605659  .174853 .370833 |                           |
|     | .127435 .848005  .96518   .626892 .339222 |                           |
|     | .254482 .191734  .681683  .350611 .062212 |                           |
|     | .741046 .403215  .914199  .379495 .465736 |                           |
|     | .108386 .615911  .887381  .237252 .40273  |                           |
|     | .348931 .0147867 .169813  .116721 .164647 |                           |
|     | .562428 .223028  .965004  .444183 .713493 |                           |
|     | .246268 .388829  .0647412 .644366 .909537 |                           |
|     | .153346 .557119  .877846  .194945 .566034 |                           |
|     | .830833 .873708  .0340514 .518585 .305423 |                           |
|     | .538554 .7037    .507989  .987173 .732358 |                           |
|     | .873665 .681869  .150294  .568273 .562839 |                           |
|     | .415912 .276259  .656391  .184779 .629991 |                           |
|                                                                             |
|o9 : MutableMatrix                                                           |
+-----------------------------------------------------------------------------+
|i10 : (Q,R) = QRDecomposition A                                              |
|                                                                             |
|o10 = (| -.373219  .00053571 -.0145186 .434826   -.0273305 |, | -1.89191     |
|       | -.0673582 -.640249  -.160526  -.10301   .310349   |  | 0            |
|       | -.134511  .0235031  -.312596  -.211448  .462328   |  | 0            |
|       | -.391693  .202931   -.312943  .0456648  .146375   |  | 0            |
|       | -.0572895 -.453214  -.233381  .214532   -.100994  |  | 0            |
|       | -.184434  .24735    -.0733514 -.0385991 .0314994  |                 |
|       | -.297281  .225982   -.452339  -.214843  -.131288  |                 |
|       | -.130169  -.153513  .179847   -.466939  -.58274   |                 |
|       | -.0810536 -.368715  -.2545    .236721   -.32996   |                 |
|       | -.439151  -.138065  .495715   .204262   .184438   |                 |
|       | -.284662  -.208589  .0850958  -.577067  .107535   |                 |
|       | -.461791  .0602065  .325632   .0156234  -.0364137 |                 |
|       | -.219838  .070582   -.240391  .103952   -.379431  |                 |
|      -----------------------------------------------------------------------|
|      -1.62694 -1.56271 -1.38193  -1.52288 |)                                |
|      -1.15333 -.947084 -.695353  -.566482 |                                 |
|      0        -1.57949 -.0484065 -.388761 |                                 |
|      0        0        -.784772  -.515486 |                                 |
|      0        0        0         -.778323 |                                 |
|                                                                             |
|o10 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i11 : Q*R-A                                                                  |
|                                                                             |
|o11 = | -2.22045e-16 5.55112e-16 1.11022e-15  2.77556e-16  3.33067e-16  |    |
|      | 0            0           2.22045e-16  0            1.66533e-16  |    |
|      | 0            5.55112e-17 -1.11022e-16 -5.55112e-17 -1.11022e-16 |    |
|      | 1.11022e-16  2.22045e-16 4.44089e-16  0            1.11022e-16  |    |
|      | 0            0           1.11022e-16  0            0            |    |
|      | 0            1.11022e-16 1.94289e-16  5.55112e-17  -2.77556e-17 |    |
|      | 0            1.66533e-16 1.11022e-16  0            1.11022e-16  |    |
|      | 0            1.11022e-16 1.11022e-16  1.11022e-16  1.11022e-16  |    |
|      | 0            0           1.11022e-16  2.77556e-17  0            |    |
|      | 0            2.22045e-16 3.33067e-16  1.11022e-16  2.22045e-16  |    |
|      | 0            1.11022e-16 2.22045e-16  -1.11022e-16 0            |    |
|      | -1.11022e-16 2.22045e-16 3.33067e-16  1.11022e-16  1.11022e-16  |    |
|      | -5.55112e-17 1.11022e-16 2.22045e-16  0            1.11022e-16  |    |
|                                                                             |
|o11 : MutableMatrix                                                          |
+-----------------------------------------------------------------------------+
|i12 : clean(1e-10,oo)                                                        |
|                                                                             |
|o12 = | 0 0 0 0 0 |                                                          |
|      | 0 0 0 0 0 |                                                          |
|      | 0 0 0 0 0 |                                                          |
|      | 0 0 0 0 0 |                                                          |
|      | 0 0 0 0 0 |                                                          |
|      | 0 0 0 0 0 |                                                          |
|      | 0 0 0 0 0 |                                                          |
|      | 0 0 0 0 0 |                                                          |
|      | 0 0 0 0 0 |                                                          |
|      | 0 0 0 0 0 |                                                          |
|      | 0 0 0 0 0 |                                                          |
|      | 0 0 0 0 0 |                                                          |
|      | 0 0 0 0 0 |                                                          |
|                                                                             |
|o12 : MutableMatrix                                                          |
+-----------------------------------------------------------------------------+

This function works by calling lapack routines, and so only uses the first 53
bits of precision. Lapack also has a way of returning an encoded pair of
matrices that contain enough information to reconstruct $Q, R$.

Caveat
======

If the matrices are over higher precision real or complex fields, such as
$RR_100$, this extra precision is not used in the computation

See also
========

  * clean -- Set to zero elements that are approximately zero

Ways to use QRDecomposition:
============================

  * "QRDecomposition(Matrix)"
  * "QRDecomposition(MutableMatrix)"

For the programmer
==================

The object QRDecomposition, is a method function.

quotient -- quotient or division
********************************

Ways to use quotient:
=====================

  * "quotient(Ideal)" -- see comodule, -- submodule to quotient
    module
  * "quotient(Module)" -- see comodule, -- submodule to
    quotient module
  * quotient(Matrix,GroebnerBasis),
    -- matrix quotient
  * "quotient(Matrix,Matrix)" -- see quotient(Matrix,GroebnerBasis),
    -- matrix quotient
  * "quotient(Ideal,Ideal)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotient(Ideal,RingElement)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotient(Module,Ideal)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotient(Module,RingElement)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotient(MonomialIdeal,RingElement)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient

For the programmer
==================

The object quotient, is a method function with options.

quotient' -- matrix quotient (opposite)
***************************************

Synopsis
========

  * Usage:
        q = quotient'(f,g)
  * Inputs:
      * f, a matrix,
      * g, a Gröbner basis, or a matrix,
        with the same source as f
  * Outputs:
      * q, the quotient of f upon (opposite) division by g

Description
===========

The equation q*g+r == f will hold, where r is the map provided by
remainder', .  The sources and targets of the maps should be free
modules. This function is obtained from quotient by transposing the inputs and
outputs.
+----------------------------------------------+
|i1 : R = ZZ[x,y]                              |
|                                              |
|o1 = R                                        |
|                                              |
|o1 : PolynomialRing                           |
+----------------------------------------------+
|i2 : f = random(R^{2:1},R^2)                  |
|                                              |
|o2 = {-1} | 8x+y  8x+3y |                     |
|     {-1} | 3x+7y 3x+7y |                     |
|                                              |
|             2      2                         |
|o2 : Matrix R  <-- R                          |
+----------------------------------------------+
|i3 : g = transpose (vars R ++ vars R)         |
|                                              |
|o3 = {-1} | x 0 |                             |
|     {-1} | y 0 |                             |
|     {-1} | 0 x |                             |
|     {-1} | 0 y |                             |
|                                              |
|             4      2                         |
|o3 : Matrix R  <-- R                          |
+----------------------------------------------+
|i4 : quotient'(f,g)                           |
|                                              |
|o4 = {-1} | 8 1 8 3 |                         |
|     {-1} | 3 7 3 7 |                         |
|                                              |
|             2      4                         |
|o4 : Matrix R  <-- R                          |
+----------------------------------------------+
|i5 : f = f + map(target f, source f, id_(R^2))|
|                                              |
|o5 = {-1} | 8x+y+1 8x+3y   |                  |
|     {-1} | 3x+7y  3x+7y+1 |                  |
|                                              |
|             2      2                         |
|o5 : Matrix R  <-- R                          |
+----------------------------------------------+
|i6 : quotient'(f,g)                           |
|                                              |
|o6 = {-1} | 8 1 8 3 |                         |
|     {-1} | 3 7 3 7 |                         |
|                                              |
|             2      4                         |
|o6 : Matrix R  <-- R                          |
+----------------------------------------------+

Code
====

method function quotient':  source code not available

See also
========

  * quotientRemainder -- matrix quotient and
    remainder
  * quotient -- quotient or division

Ways to use quotient':
======================

  * "quotient'(Matrix,Matrix)"

For the programmer
==================

The object quotient', is a method function.

quotient(Matrix,GroebnerBasis) -- matrix quotient
*************************************************

Synopsis
========

  * Function: quotient,
  * Usage:
        q = quotient(f,g)
  * Inputs:
      * f, a matrix,
      * g, a Gröbner basis, or a matrix,
        with the same target as f
  * Optional inputs,:
      * BasisElementLimit (Saturation),
        =>
        ..., default value infinity,
      * DegreeLimit (Saturation),
        => ..., default value {},
      * MinimalGenerators (Saturation), =>
        ..., default value true,
      * PairLimit (Saturation),
        => ..., default value infinity,
      * Strategy (Saturation),
        => ..., default value null,
  * Outputs:
      * q, the quotient of f upon division by g

Description
===========

The equation g*q+r == f will hold, where r is the map provided by
remainder.  The source of f should be a free module.
+----------------------------------------------+
|i1 : R = ZZ[x,y]                              |
|                                              |
|o1 = R                                        |
|                                              |
|o1 : PolynomialRing                           |
+----------------------------------------------+
|i2 : f = random(R^2,R^{2:-1})                 |
|                                              |
|o2 = | 8x+y  8x+3y |                          |
|     | 3x+7y 3x+7y |                          |
|                                              |
|             2      2                         |
|o2 : Matrix R  <-- R                          |
+----------------------------------------------+
|i3 : g = vars R ++ vars R                     |
|                                              |
|o3 = | x y 0 0 |                              |
|     | 0 0 x y |                              |
|                                              |
|             2      4                         |
|o3 : Matrix R  <-- R                          |
+----------------------------------------------+
|i4 : quotient(f,g)                            |
|                                              |
|o4 = {1} | 8 8 |                              |
|     {1} | 1 3 |                              |
|     {1} | 3 3 |                              |
|     {1} | 7 7 |                              |
|                                              |
|             4      2                         |
|o4 : Matrix R  <-- R                          |
+----------------------------------------------+
|i5 : f = f + map(target f, source f, id_(R^2))|
|                                              |
|o5 = | 8x+y+1 8x+3y   |                       |
|     | 3x+7y  3x+7y+1 |                       |
|                                              |
|             2      2                         |
|o5 : Matrix R  <-- R                          |
+----------------------------------------------+
|i6 : quotient(f,g)                            |
|                                              |
|o6 = {1} | 8 8 |                              |
|     {1} | 1 3 |                              |
|     {1} | 3 3 |                              |
|     {1} | 7 7 |                              |
|                                              |
|             4      2                         |
|o6 : Matrix R  <-- R                          |
+----------------------------------------------+

See also
========

  * quotientRemainder -- matrix quotient and
    remainder
  * quotient' -- matrix quotient (opposite)

Ways to use this method:
========================

  * quotient(Matrix,GroebnerBasis),
    -- matrix quotient
  * "quotient(Matrix,Matrix)"

quotientRemainder -- matrix quotient and remainder
**************************************************

Synopsis
========

  * Usage:
        (q,r) = quotientRemainder(f,g)
  * Inputs:
      * f, a matrix,
      * g, a Gröbner basis, or a matrix,
        with the same target as f
  * Outputs:
      * q, the quotient of f upon division by g
      * r, the remainder of f upon division by g

Description
===========

The equation g*q+r == f will hold.  The source of f should be a free module.
+----------------------------------------------+
|i1 : R = ZZ[x,y]                              |
|                                              |
|o1 = R                                        |
|                                              |
|o1 : PolynomialRing                           |
+----------------------------------------------+
|i2 : f = random(R^2,R^{2:-1})                 |
|                                              |
|o2 = | 8x+y  8x+3y |                          |
|     | 3x+7y 3x+7y |                          |
|                                              |
|             2      2                         |
|o2 : Matrix R  <-- R                          |
+----------------------------------------------+
|i3 : g = vars R ++ vars R                     |
|                                              |
|o3 = | x y 0 0 |                              |
|     | 0 0 x y |                              |
|                                              |
|             2      4                         |
|o3 : Matrix R  <-- R                          |
+----------------------------------------------+
|i4 : (q,r) = quotientRemainder(f,g)           |
|                                              |
|o4 = ({1} | 8 8 |, 0)                         |
|      {1} | 1 3 |                             |
|      {1} | 3 3 |                             |
|      {1} | 7 7 |                             |
|                                              |
|o4 : Sequence                                 |
+----------------------------------------------+
|i5 : g*q+r == f                               |
|                                              |
|o5 = true                                     |
+----------------------------------------------+
|i6 : f = f + map(target f, source f, id_(R^2))|
|                                              |
|o6 = | 8x+y+1 8x+3y   |                       |
|     | 3x+7y  3x+7y+1 |                       |
|                                              |
|             2      2                         |
|o6 : Matrix R  <-- R                          |
+----------------------------------------------+
|i7 : (q,r) = quotientRemainder(f,g)           |
|                                              |
|o7 = ({1} | 8 8 |, | 1 0 |)                   |
|      {1} | 1 3 |  | 0 1 |                    |
|      {1} | 3 3 |                             |
|      {1} | 7 7 |                             |
|                                              |
|o7 : Sequence                                 |
+----------------------------------------------+
|i8 : g*q+r == f                               |
|                                              |
|o8 = true                                     |
+----------------------------------------------+

See also
========

  * quotientRemainder' -- matrix quotient and
    remainder (opposite)

Ways to use quotientRemainder:
==============================

  * "quotientRemainder(Matrix,GroebnerBasis)"
  * "quotientRemainder(Matrix,Matrix)"
  * "quotientRemainder(InexactNumber,RingElement)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder
  * "quotientRemainder(Number,RingElement)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder
  * "quotientRemainder(RingElement,InexactNumber)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder
  * "quotientRemainder(RingElement,Number)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder
  * quotientRemainder(RingElement,RingElement)
    -- quotient and remainder
  * "quotientRemainder(ZZ,ZZ)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder

For the programmer
==================

The object quotientRemainder, is a method function.

quotientRemainder' -- matrix quotient and remainder (opposite)
**************************************************************

Synopsis
========

  * Usage:
        (q,r) = quotientRemainder'(f,g)
  * Inputs:
      * f, a matrix,
      * g, a Gröbner basis, or a matrix,
        with the same source as f
  * Outputs:
      * q, the quotient of f upon (opposite) division by g
      * r, the remainder of f upon (opposite) division by g

Description
===========

The equation q*g+r == f will hold.  The sources and targets of the maps should
be free modules. This function is obtained from quotientRemainder by
transposing the inputs and outputs.
+----------------------------------------------+
|i1 : R = ZZ[x,y]                              |
|                                              |
|o1 = R                                        |
|                                              |
|o1 : PolynomialRing                           |
+----------------------------------------------+
|i2 : f = random(R^{2:1},R^2)                  |
|                                              |
|o2 = {-1} | 8x+y  8x+3y |                     |
|     {-1} | 3x+7y 3x+7y |                     |
|                                              |
|             2      2                         |
|o2 : Matrix R  <-- R                          |
+----------------------------------------------+
|i3 : g = transpose (vars R ++ vars R)         |
|                                              |
|o3 = {-1} | x 0 |                             |
|     {-1} | y 0 |                             |
|     {-1} | 0 x |                             |
|     {-1} | 0 y |                             |
|                                              |
|             4      2                         |
|o3 : Matrix R  <-- R                          |
+----------------------------------------------+
|i4 : (q,r) = quotientRemainder'(f,g)          |
|                                              |
|o4 = ({-1} | 8 1 8 3 |, 0)                    |
|      {-1} | 3 7 3 7 |                        |
|                                              |
|o4 : Sequence                                 |
+----------------------------------------------+
|i5 : q*g+r == f                               |
|                                              |
|o5 = true                                     |
+----------------------------------------------+
|i6 : f = f + map(target f, source f, id_(R^2))|
|                                              |
|o6 = {-1} | 8x+y+1 8x+3y   |                  |
|     {-1} | 3x+7y  3x+7y+1 |                  |
|                                              |
|             2      2                         |
|o6 : Matrix R  <-- R                          |
+----------------------------------------------+
|i7 : (q,r) = quotientRemainder'(f,g)          |
|                                              |
|o7 = ({-1} | 8 1 8 3 |, {-1} | 1 0 |)         |
|      {-1} | 3 7 3 7 |  {-1} | 0 1 |          |
|                                              |
|o7 : Sequence                                 |
+----------------------------------------------+
|i8 : q*g+r == f                               |
|                                              |
|o8 = true                                     |
+----------------------------------------------+

Code
====

method function quotientRemainder':  source code not available

See also
========

  * quotientRemainder -- matrix quotient and
    remainder

Ways to use quotientRemainder':
===============================

  * "quotientRemainder'(Matrix,Matrix)"

For the programmer
==================

The object quotientRemainder', is a method function.

quotientRemainder(RingElement,RingElement) -- quotient and remainder
********************************************************************

Synopsis
========

  * Function: quotientRemainder,
  * Usage:
        (q,r) = quotientRemainder(f,g)
  * Inputs:
      * f
      * g
  * Outputs:
      * q, a ring element, the quotient for the division of
        f by g
      * r, a ring element, the remainder for the division
        of f by g

Description
===========

+-------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                  |
+-------------------------------------------------------------------+
|i2 : (q,r) = quotientRemainder(x^10+5,x-2);                        |
+-------------------------------------------------------------------+
|i3 : q                                                             |
|                                                                   |
|      9     8     7     6      5      4      3       2             |
|o3 = x  + 2x  + 4x  + 8x  + 16x  + 32x  + 64x  + 128x  + 256x + 512|
|                                                                   |
|o3 : R                                                             |
+-------------------------------------------------------------------+
|i4 : r                                                             |
|                                                                   |
|o4 = 1029                                                          |
|                                                                   |
|o4 : R                                                             |
+-------------------------------------------------------------------+
|i5 : q*(x-2)+r                                                     |
|                                                                   |
|      10                                                           |
|o5 = x   + 5                                                       |
|                                                                   |
|o5 : R                                                             |
+-------------------------------------------------------------------+

Ways to use this method:
========================

  * "quotientRemainder(InexactNumber,RingElement)"
  * "quotientRemainder(Number,RingElement)"
  * "quotientRemainder(RingElement,InexactNumber)"
  * "quotientRemainder(RingElement,Number)"
  * quotientRemainder(RingElement,RingElement)
    -- quotient and remainder
  * "quotientRemainder(ZZ,ZZ)"

QuotientRing -- the class of all quotient rings
***********************************************

Functions and methods returning a quotient ring:
================================================

  * "coimage(RingMap)" -- see coimage, -- coimage of a map
  * graphRing(RingMap) -- the coordinate ring of
    the graph of the regular map corresponding to a ring map
  * Ring / Ideal -- make a quotient ring
  * "Ring / List" -- see Ring / Ideal, -- make a quotient
    ring
  * "Ring / Module" -- see Ring / Ideal, -- make a quotient
    ring
  * "Ring / RingElement" -- see Ring / Ideal, -- make a
    quotient ring
  * "Ring / Sequence" -- see Ring / Ideal, -- make a
    quotient ring
  * "singularLocus(Ideal)" -- see singularLocus, --
    singular locus
  * "singularLocus(Ring)" -- see singularLocus, --
    singular locus

Methods that use a quotient ring:
=================================

  * "ambient(QuotientRing)" -- see ambient(Ring), --
    ambient polynomial ring
  * codim(QuotientRing) -- compute the
    codimension
  * degreeGroup(QuotientRing) (missing documentation)
  * "degrees(QuotientRing)" -- see degrees(Ring), --
    degrees of generators
  * "describe(QuotientRing)" -- see describe, -- real
    description
  * "dim(QuotientRing)" -- see dim(Ring), -- compute the
    Krull dimension
  * "flattenRing(QuotientRing)" -- see flattenRing, -- write
    a ring as a (quotient of a) polynomial ring
  * "heft(QuotientRing)" -- see heft, -- heft vector of ring or
    monoid
  * "hilbertSeries(QuotientRing)" -- see hilbertSeries(PolynomialRing),
    -- compute the Hilbert series of a ring
  * "ideal(QuotientRing)" -- see ideal(Ring), -- returns
    the defining ideal
  * "isAffineRing(QuotientRing)" -- see isAffineRing, --
    whether something is an affine ring
  * isHomogeneous(QuotientRing) (missing documentation)
  * "isQuotientOf(Ring,QuotientRing)" -- see isQuotientOf(Ring,Ring),
    -- whether one ring is a quotient of another
  * "isQuotientOf(Type,QuotientRing)" -- see isQuotientOf(Type,Ring),
    -- whether one ring is a quotient of a ring
    of a given type
  * "isQuotientRing(QuotientRing)" -- see isQuotientRing,
    -- whether something is a quotient ring
  * "isSkewCommutative(QuotientRing)" -- see isSkewCommutative,
    -- whether a ring has skew commuting variables
  * isWeylAlgebra(QuotientRing) (missing documentation)
  * "newRing(QuotientRing)" -- see newRing, -- make a copy of a
    ring, with some features changed
  * "numgens(QuotientRing)" -- see numgens(Ring), --
    number of generators of a polynomial ring
  * "options(QuotientRing)" -- see options(Monoid),
    -- get values used for optional arguments
  * "precision(QuotientRing)" -- see precision,
  * presentation(PolynomialRing,QuotientRing)
    -- presentation of a
    quotient ring
  * "presentation(QuotientRing)" -- see
    presentation(PolynomialRing,QuotientRing),
    -- presentation of a
    quotient ring
  * "trim(QuotientRing)" -- see trim, -- minimize generators and
    relations

For the programmer
==================

The object QuotientRing, is a type, with
ancestor classes EngineRing, < Ring <
Type < MutableHashTable < HashTable
< Thing.

RaiseError -- whether to raise an error
***************************************

Functions with optional argument named RaiseError:
==================================================

  * "findProgram(...,RaiseError=>...)" -- see findProgram,
    -- load external program
  * "runProgram(...,RaiseError=>...)" -- see runProgram, --
    run an external program

For the programmer
==================

The object RaiseError, is a symbol.

random -- get a random object
*****************************

Description
===========

This function can be used to get randomized objects of various sorts.

See also
========

  * setRandomSeed -- set starting point for random number
    generator

Ways to use random:
===================

  * random(List) -- shuffle a list randomly
  * random(Module) -- get a random vector in the
    module
  * random(Module,Module) -- get a random
    map of module
  * random(Type) -- get a random object of a type
  * "random(List,Ideal)" -- see random(ZZ,Ideal),
    -- get a random homogeneous element from a graded ideal
  * random(ZZ,Ideal) -- get a random homogeneous
    element from a graded ideal
  * "random(List,Ring)" -- see random(ZZ,Ring), --
    get a random homogeneous element from a graded ring
  * random(ZZ,Ring) -- get a random homogeneous
    element from a graded ring
  * "random(RR)" -- see random(ZZ,ZZ), -- get a
    random integer or real number
  * "random(RR,RR)" -- see random(ZZ,ZZ), -- get a
    random integer or real number
  * "random(ZZ)" -- see random(ZZ,ZZ), -- get a
    random integer or real number
  * random(ZZ,ZZ) -- get a random integer or real
    number

For the programmer
==================

The object random, is a method function with options.

random(ZZ,ZZ) -- get a random integer or real number
****************************************************

Synopsis
========

  * Function: random,

Description
===========

Synopsis
========

  * Usage:
        random(low, high)
        random high
  * Inputs:
      * low, an integer, or a real number,
      * high, an integer, or a real number,
  * Outputs:
      * an integer, a random integer or real number of the same
        precision,

If only high is given, the output will be in the range [0, high).

+-------------------------------------------------------------------+
|i1 : random 57                                                     |
|                                                                   |
|o1 = 43                                                            |
+-------------------------------------------------------------------+
|i2 : random 10^50                                                  |
|                                                                   |
|o2 = 27966429632588001730589592232989755722230769700437            |
+-------------------------------------------------------------------+
|i3 : tally apply(100, i -> random 7)                               |
|                                                                   |
|o3 = Tally{0 => 9 }                                                |
|           1 => 16                                                 |
|           2 => 11                                                 |
|           3 => 15                                                 |
|           4 => 14                                                 |
|           5 => 11                                                 |
|           6 => 24                                                 |
|                                                                   |
|o3 : Tally                                                         |
+-------------------------------------------------------------------+
|i4 : random 3.14                                                   |
|                                                                   |
|o4 = 2.00442043654275                                              |
|                                                                   |
|o4 : RR (of precision 53)                                          |
+-------------------------------------------------------------------+
|i5 : random 3p200                                                  |
|                                                                   |
|o5 = 2.362050531245025823152580356155207457761196081817725396837539|
|                                                                   |
|o5 : RR (of precision 200)                                         |
+-------------------------------------------------------------------+

If, in addition, low is given, the output will be in the range [low, high]

+------------------------------------------------------------+
|i6 : for i to 10 list random(100,200)                       |
|                                                            |
|o6 = {195, 135, 192, 166, 106, 140, 103, 170, 125, 199, 160}|
|                                                            |
|o6 : List                                                   |
+------------------------------------------------------------+
|i7 : tally apply(100, i -> random(10,15))                   |
|                                                            |
|o7 = Tally{10 => 20}                                        |
|           11 => 17                                         |
|           12 => 14                                         |
|           13 => 12                                         |
|           14 => 21                                         |
|           15 => 16                                         |
|                                                            |
|o7 : Tally                                                  |
+------------------------------------------------------------+
|i8 : random(10.,20.)                                        |
|                                                            |
|o8 = 10.75106240004187                                      |
|                                                            |
|o8 : RR (of precision 53)                                   |
+------------------------------------------------------------+
|i9 : random(10p100,20p100)                                  |
|                                                            |
|o9 = 17.03319064630373207472512821212                       |
|                                                            |
|o9 : RR (of precision 100)                                  |
+------------------------------------------------------------+

See also
========

  * setRandomSeed -- set starting point for random number
    generator

Ways to use this method:
========================

  * "random(RR)"
  * "random(RR,RR)"
  * "random(ZZ)"
  * random(ZZ,ZZ) -- get a random integer or real
    number

random(Type) -- get a random object of a type
*********************************************

Synopsis
========

  * Function: random,
  * Usage:
        random T
  * Inputs:
      * T, a type,
  * Optional inputs,:
      * Height, => an integer, default
        value 10, get a random homogeneous element from a graded ring
      * Density, => ..., default value 1,
        get a random map of module
      * MaximalRank, => ..., default value
        false, get a random map of module
      * UpperTriangular, => ..., default
        value false, get a random map of module
  * Outputs:
      * a thing, a random instance of the type T

Description
===========

If the Height option specifies a number h and T is ZZ, then the
integers returned are in the range [0, h); for QQ, the numerator and
denominator are in the range [1, h].

+-----------------------------------------------------------------------------+
|i1 : random RR                                                               |
|                                                                             |
|o1 = .8927118418469154                                                       |
|                                                                             |
|o1 : RR (of precision 53)                                                    |
+-----------------------------------------------------------------------------+
|i2 : random CC_100                                                           |
|                                                                             |
|o2 = .5619898392945591566756001377063+.2468606270337661566124209458785*ii    |
|                                                                             |
|o2 : CC (of precision 100)                                                   |
+-----------------------------------------------------------------------------+
|i3 : tally for i to 100 list random GF 11                                    |
|                                                                             |
|o3 = Tally{-1 => 1}                                                          |
|           -1 => 1                                                           |
|           -1 => 1                                                           |
|           -1 => 1                                                           |
|           -2 => 1                                                           |
|           -2 => 1                                                           |
|           -2 => 1                                                           |
|           -2 => 1                                                           |
|           -2 => 1                                                           |
|           -2 => 1                                                           |
|           -2 => 1                                                           |
|           -2 => 1                                                           |
|           -2 => 1                                                           |
|           -2 => 1                                                           |
|           -2 => 1                                                           |
|           -3 => 1                                                           |
|           -3 => 1                                                           |
|           -3 => 1                                                           |
|           -3 => 1                                                           |
|           -3 => 1                                                           |
|           -3 => 1                                                           |
|           -3 => 1                                                           |
|           -3 => 1                                                           |
|           -4 => 1                                                           |
|           -4 => 1                                                           |
|           -4 => 1                                                           |
|           -4 => 1                                                           |
|           -4 => 1                                                           |
|           -4 => 1                                                           |
|           -4 => 1                                                           |
|           -4 => 1                                                           |
|           -4 => 1                                                           |
|           -4 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           -5 => 1                                                           |
|           0 => 1                                                            |
|           0 => 1                                                            |
|           0 => 1                                                            |
|           0 => 1                                                            |
|           0 => 1                                                            |
|           0 => 1                                                            |
|           1 => 1                                                            |
|           1 => 1                                                            |
|           1 => 1                                                            |
|           1 => 1                                                            |
|           1 => 1                                                            |
|           1 => 1                                                            |
|           1 => 1                                                            |
|           2 => 1                                                            |
|           2 => 1                                                            |
|           2 => 1                                                            |
|           2 => 1                                                            |
|           2 => 1                                                            |
|           2 => 1                                                            |
|           2 => 1                                                            |
|           2 => 1                                                            |
|           2 => 1                                                            |
|           2 => 1                                                            |
|           2 => 1                                                            |
|           3 => 1                                                            |
|           3 => 1                                                            |
|           3 => 1                                                            |
|           3 => 1                                                            |
|           3 => 1                                                            |
|           3 => 1                                                            |
|           3 => 1                                                            |
|           3 => 1                                                            |
|           4 => 1                                                            |
|           4 => 1                                                            |
|           4 => 1                                                            |
|           4 => 1                                                            |
|           4 => 1                                                            |
|           4 => 1                                                            |
|           4 => 1                                                            |
|           4 => 1                                                            |
|           4 => 1                                                            |
|           4 => 1                                                            |
|           4 => 1                                                            |
|           4 => 1                                                            |
|           5 => 1                                                            |
|           5 => 1                                                            |
|           5 => 1                                                            |
|           5 => 1                                                            |
|           5 => 1                                                            |
|           5 => 1                                                            |
|           5 => 1                                                            |
|           5 => 1                                                            |
|           5 => 1                                                            |
|                                                                             |
|o3 : Tally                                                                   |
+-----------------------------------------------------------------------------+
|i4 : random GF(2,40)                                                         |
|                                                                             |
|      37    35    33    31    29    27    24    22    17    16    15    12   |
|o4 = a   + a   + a   + a   + a   + a   + a   + a   + a   + a   + a   + a   + |
|     ------------------------------------------------------------------------|
|      5    4    2                                                            |
|     a  + a  + a  + a                                                        |
|                                                                             |
|o4 : GF 1099511627776                                                        |
+-----------------------------------------------------------------------------+

See also
========

  * setRandomSeed -- set starting point for random number
    generator

Ways to use this method:
========================

  * random(Type) -- get a random object of a type

random(List) -- shuffle a list randomly
***************************************

Synopsis
========

  * Function: random,
  * Usage:
        random L
  * Inputs:
      * L, a list,
  * Optional inputs,:
      * Density, => ..., default value 1,
        get a random map of module
      * Height, => ..., default value 10, get a
        random homogeneous element from a graded ring
      * MaximalRank, => ..., default value
        false, get a random map of module
      * UpperTriangular, => ..., default
        value false, get a random map of module
  * Outputs:
      * a list, a new list containing the elements of L in a
        shuffled random order

Description
===========

+-----------------------------------------------+
|i1 : random toList (0 .. 12)                   |
|                                               |
|o1 = {5, 3, 6, 8, 1, 2, 0, 9, 11, 4, 7, 12, 10}|
|                                               |
|o1 : List                                      |
+-----------------------------------------------+

See also
========

  * setRandomSeed -- set starting point for random number
    generator

Ways to use this method:
========================

  * random(List) -- shuffle a list randomly

random(ZZ,Ideal) -- get a random homogeneous element from a graded ideal
************************************************************************

Synopsis
========

  * Function: random,
  * Usage:
        random(d, I)
        random(L, I)
  * Inputs:
      * d, an integer, or a list, the degree,
        multi-degree, or a list of degrees;
      * I, an ideal, in a graded ring;
  * Optional inputs,:
      * Density, => ..., default value 1,
        get a random map of module
      * Height, => ..., default value 10, get a
        random homogeneous element from a graded ring
      * MaximalRank, => ..., default value
        false, get a random map of module
      * UpperTriangular, => ..., default
        value false, get a random map of module
  * Outputs:
      * a ring element, or a list, homogeneous
        element(s) with prescribed degrees;

Description
===========

This function produces one or more homogeneous elements of an ideal.

+-----------------------------------------------------------+
|i1 : S = ZZ/101[x, y]                                      |
|                                                           |
|o1 = S                                                     |
|                                                           |
|o1 : PolynomialRing                                        |
+-----------------------------------------------------------+
|i2 : I = ideal"x2, y2"                                     |
|                                                           |
|             2   2                                         |
|o2 = ideal (x , y )                                        |
|                                                           |
|o2 : Ideal of S                                            |
+-----------------------------------------------------------+
|i3 : random(2, I)                                          |
|                                                           |
|        2      2                                           |
|o3 = 24x  - 36y                                            |
|                                                           |
|o3 : S                                                     |
+-----------------------------------------------------------+
|i4 : random({2}, I)                                        |
|                                                           |
|          2      2                                         |
|o4 = - 30x  - 29y                                          |
|                                                           |
|o4 : S                                                     |
+-----------------------------------------------------------+
|i5 : random({2, 3}, I)                                     |
|                                                           |
|         2      2       3     2         2      3           |
|o5 = {19x  + 19y , - 10x  - 8x y - 29x*y  - 22y }          |
|                                                           |
|o5 : List                                                  |
+-----------------------------------------------------------+
|i6 : random({{2}, {3}}, I)                                 |
|                                                           |
|           2      2       3      2         2      3        |
|o6 = {- 29x  - 24y , - 38x  + 39x y - 16x*y  + 21y }       |
|                                                           |
|o6 : List                                                  |
+-----------------------------------------------------------+
|i7 : R = ZZ/101[x, y, z, Degrees => {{1,0}, {-1,1}, {0,1}}]|
|                                                           |
|o7 = R                                                     |
|                                                           |
|o7 : PolynomialRing                                        |
+-----------------------------------------------------------+
|i8 : J = ideal"x2, y2, z2"                                 |
|                                                           |
|             2   2   2                                     |
|o8 = ideal (x , y , z )                                    |
|                                                           |
|o8 : Ideal of R                                            |
+-----------------------------------------------------------+
|i9 : random({2, 2}, J)                                     |
|                                                           |
|         4 2      3         2 2                            |
|o9 = - 5x y  + 19x y*z + 36x z                             |
|                                                           |
|o9 : R                                                     |
+-----------------------------------------------------------+
|i10 : random({{2, 2}}, J)                                  |
|                                                           |
|            4 2      3         2 2                         |
|o10 = {- 41x y  - 43x y*z + 39x z }                        |
|                                                           |
|o10 : List                                                 |
+-----------------------------------------------------------+
|i11 : random(toList(3:{1, 1}), J)                          |
|                                                           |
|          2     2      2                                   |
|o11 = {38x y, 2x y, 16x y}                                 |
|                                                           |
|o11 : List                                                 |
+-----------------------------------------------------------+

Caveat
======

Note that in the single graded case, the input {d} is treated as a multidegree
of length one rather than a list of length one, hence the output is one
polynomial, while {{d}} is treated as a list containing a single multidegree of
length one and therefore the output is a list containing a single polynomial.

See also
========

  * random(ZZ,Ring) -- get a random homogeneous
    element from a graded ring
  * random(List,Ring) -- get a random homogeneous
    element from a graded ring

Ways to use this method:
========================

  * "random(List,Ideal)"
  * random(ZZ,Ideal) -- get a random homogeneous
    element from a graded ideal

random(ZZ,Ring) -- get a random homogeneous element from a graded ring
**********************************************************************

Synopsis
========

  * Function: random,
  * Usage:
        random(d, R)
  * Inputs:
      * d, an integer, or a list, the degree or
        multi-degree to use;
      * R, a ring,
  * Optional inputs,:
      * Density, => ..., default value 1,
        get a random map of module
      * Height => ..., default value 10
      * MaximalRank, => ..., default value
        false, get a random map of module
      * UpperTriangular, => ..., default
        value false, get a random map of module
  * Outputs:
      * a ring element, a random homogeneous element of the
        ring R of degree d

Description
===========

+----------------------------------------------------------+
|i1 : R = ZZ[x,y]                                          |
|                                                          |
|o1 = R                                                    |
|                                                          |
|o1 : PolynomialRing                                       |
+----------------------------------------------------------+
|i2 : random(5, R)                                         |
|                                                          |
|       5    4      3 2     2 3       4     5              |
|o2 = 8x  + x y + 3x y  + 7x y  + 8x*y  + 3y               |
|                                                          |
|o2 : R                                                    |
+----------------------------------------------------------+
|i3 : R = GF(25, Variable => a)[x, y];                     |
+----------------------------------------------------------+
|i4 : VerticalList for i to 6 list random(3, R)            |
|                                                          |
|     {           3     2          2       3              }|
|o4 = {(- 2a - 1)x  - 2x y - 2a*x*y  + 2a*y               }|
|     {           3       2                 2            3}|
|     {(- 2a - 2)x  + 2a*x y + (- 2a + 1)x*y  + (2a + 1)y }|
|     {    3              2              2             3  }|
|     {2a*x  + (- 2a + 1)x y + (a - 2)x*y  + (- a - 2)y   }|
|     {  3              2              2       3          }|
|     {2x  + (- 2a - 1)x y + (a - 2)x*y  - 2a*y           }|
|     {        3            2               2    3        }|
|     {(a + 1)x  + (2a + 2)x y + (2a + 1)x*y  - y         }|
|     { 3              2                 2    3           }|
|     {x  + (- 2a - 2)x y + (- 2a - 2)x*y  + y            }|
|     {        3       2              2             3     }|
|     {(a - 1)x  + 2a*x y + (a + 2)x*y  + (- a - 1)y      }|
|                                                          |
|o4 : VerticalList                                         |
+----------------------------------------------------------+

The length of d, if it's a list, should be the same as degree rank,
of $R$.

See also
========

  * setRandomSeed -- set starting point for random number
    generator

Ways to use this method:
========================

  * "random(List,Ring)"
  * random(ZZ,Ring) -- get a random homogeneous
    element from a graded ring

random(Module) -- get a random vector in the module
***************************************************

Synopsis
========

  * Function: random,
  * Usage:
        v = random M
  * Inputs:
      * M, a module,
  * Optional inputs,:
      * Density, => ..., default value 1,
        get a random map of module
      * Height, => ..., default value 10, get a
        random homogeneous element from a graded ring
      * MaximalRank, => ..., default value
        false, get a random map of module
      * UpperTriangular, => ..., default
        value false, get a random map of module
  * Outputs:
      * v, a vector,

Description
===========

+------------------------------------------+
|i1 : R = ZZ/7[x,y]                        |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : E = End R^{-1,1}                     |
|                                          |
|      4                                   |
|o2 = R                                    |
|                                          |
|o2 : R-module, free, degrees {0, -2, 2, 0}|
+------------------------------------------+
|i3 : h = homomorphism random E            |
|                                          |
|o3 = {1}  | 3      0 |                    |
|     {-1} | x2+3xy 0 |                    |
|                                          |
|             2      2                     |
|o3 : Matrix R  <-- R                      |
+------------------------------------------+

See also
========

  * Hom(Module,Module) -- module of homomorphisms
  * random(Module,Module) -- get a random
    map of module
  * setRandomSeed -- set starting point for random number
    generator

Ways to use this method:
========================

  * random(Module) -- get a random vector in the
    module

random(Module,Module) -- get a random map of module
***************************************************

Synopsis
========

  * Function: random,
  * Usage:
        f = random(F, G)
  * Inputs:
      * F, a module,
      * G, a module,
  * Optional inputs,:
      * Density => a real number, default value 1, the proportion of
        entries to set
      * MaximalRank => a Boolean value, default value false,
        whether to ensure that the resulting map has maximal rank: designed
        mostly for use with matrices of numbers: for polynomial rings, returns
        inhomogeneous results
      * UpperTriangular => a Boolean value, default value
        false, whether to set just entries strictly above the diagonal
      * Height, => ..., default value 10, get a
        random homogeneous element from a graded ring
  * Outputs:
      * f, a matrix, a random, graded, degree 0 map $f: G \to F$

Description
===========

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[x,y];                                                        |
+-----------------------------------------------------------------------------+
|i2 : random(R^{1,2,3}, R^{1,2,3})                                            |
|                                                                             |
|o2 = {-1} | 24             0       0   |                                     |
|     {-2} | -29x+19y       -36     0   |                                     |
|     {-3} | -29x2-8xy-22y2 19x-10y -30 |                                     |
|                                                                             |
|             3      3                                                        |
|o2 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i3 : random(ZZ^3, ZZ^10, Density => .3)                                      |
|                                                                             |
|o3 = | 8 0 0 0 2 3 0 0 8 0 |                                                 |
|     | 0 5 7 5 0 6 0 3 6 0 |                                                 |
|     | 0 0 8 0 0 0 0 6 9 0 |                                                 |
|                                                                             |
|              3       10                                                     |
|o3 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i4 : random(ZZ^3, ZZ^6, MaximalRank => true)                                 |
|                                                                             |
|o4 = | 35047412   3247979   11405872  504891598   50976553853   5614985894   |
|     | 1157543751 107274048 376712434 16675528353 1683650456951 185451405627 |
|     | 389888849  36132505  126885897 5616722964  567094366108  62464537627  |
|     ------------------------------------------------------------------------|
|     |                                                                       |
|     |                                                                       |
|     |                                                                       |
|                                                                             |
|              3       6                                                      |
|o4 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i5 : random(ZZ^6, ZZ^6, UpperTriangular => true)                             |
|                                                                             |
|o5 = | 0 2 5 3 7 5 |                                                         |
|     | 0 0 7 0 0 8 |                                                         |
|     | 0 0 0 1 2 9 |                                                         |
|     | 0 0 0 0 7 4 |                                                         |
|     | 0 0 0 0 0 3 |                                                         |
|     | 0 0 0 0 0 0 |                                                         |
|                                                                             |
|              6       6                                                      |
|o5 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+

Caveat
======

Over a polynomial ring, specifying MaximalRank=>true will yield a
non-homogeneous matrix.

See also
========

  * random(Module) -- get a random vector in the
    module
  * setRandomSeed -- set starting point for random number
    generator

Ways to use this method:
========================

  * random(Module,Module) -- get a random
    map of module

randomKRationalPoint -- Pick a random K rational point on the scheme X defined by I
***********************************************************************************

Synopsis
========

  * Usage:
        randomKRationalPoint I
  * Inputs:
      * I, an ideal, in a polynomial ring over a finite ground
        field K
  * Outputs:
      * an ideal, of a K-rational point on V(I)

Description
===========

If X has codimension 1, then we intersect X with a randomly chosen line, and
hope that the decomposition of the intersection contains a K-rational point. If
n=degree X then the probability P that this happens, is the proportion  of
permutations in $S_n$ with a fix point on $\{1,\ldots,n \}$, i.e.
$$P=\sum_{j=1}^n (-1)^{j-1} binomial(n,j)(n-j)!/n! = 1-1/2+1/3! + \ldots $$
which approaches $1-exp(-1) = 0.63\ldots$. Thus a probabilistic approach works.

For higher codimension we first project X birationally onto a hypersurface Y,
and find a point on Y. Then we take the preimage of this point.

+------------------------------------------------------------------+
|i1 : p=nextPrime(random(2*10^4))                                  |
|                                                                  |
|o1 = 107                                                          |
+------------------------------------------------------------------+
|i2 : kk=ZZ/p;R=kk[x_0..x_3];                                      |
+------------------------------------------------------------------+
|i4 : I=minors(4,random(R^5,R^{4:-1}));                            |
|                                                                  |
|o4 : Ideal of R                                                   |
+------------------------------------------------------------------+
|i5 : codim I, degree I                                            |
|                                                                  |
|o5 = (2, 10)                                                      |
|                                                                  |
|o5 : Sequence                                                     |
+------------------------------------------------------------------+
|i6 : time randomKRationalPoint(I)                                 |
| -- used 0.071122s (cpu); 0.0662149s (thread); 0s (gc)            |
|                                                                  |
|o6 = ideal (x  - 53x , x  + 8x , x  - 4x )                        |
|             2      3   1     3   0     3                         |
|                                                                  |
|o6 : Ideal of R                                                   |
+------------------------------------------------------------------+
|i7 : R=kk[x_0..x_5];                                              |
+------------------------------------------------------------------+
|i8 : I=minors(3,random(R^5,R^{3:-1}));                            |
|                                                                  |
|o8 : Ideal of R                                                   |
+------------------------------------------------------------------+
|i9 : codim I, degree I                                            |
|                                                                  |
|o9 = (3, 10)                                                      |
|                                                                  |
|o9 : Sequence                                                     |
+------------------------------------------------------------------+
|i10 : time randomKRationalPoint(I)                                |
| -- used 0.197168s (cpu); 0.189793s (thread); 0s (gc)             |
|                                                                  |
|o10 = ideal (x  - 27x , x  - 16x , x  - 9x , x  + 44x , x  - 52x )|
|              4      5   3      5   2     5   1      5   0      5 |
|                                                                  |
|o10 : Ideal of R                                                  |
+------------------------------------------------------------------+

The claim that $63 \%$ of the intersections contain a K-rational point can be
experimentally tested:

+-----------------------------------------------------------------------------+
|i11 : p=10007,kk=ZZ/p,R=kk[x_0..x_2]                                         |
|                                                                             |
|o11 = (10007, kk, R)                                                         |
|                                                                             |
|o11 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i12 : n=5; sum(1..n,j->(-1)^(j-1)*binomial(n,j)*(n-j)!/n!)+0.0               |
|                                                                             |
|o13 = .6333333333333333                                                      |
|                                                                             |
|o13 : RR (of precision 53)                                                   |
+-----------------------------------------------------------------------------+
|i14 : I=ideal random(n,R);                                                   |
|                                                                             |
|o14 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i15 : time (#select(apply(100,i->(degs=apply(decompose(I+ideal               |
|                     #select(degs,d->d==1))),f->f>0))                        |
| -- used 2.22777s (cpu); 1.43226s (thread); 0s (gc)                          |
|                                                                             |
|o15 = 58                                                                     |
|-----------------------------------------------------------------------------|
|random(1,R)),c->degree c);                                                   |
+-----------------------------------------------------------------------------+

Ways to use randomKRationalPoint:
=================================

  * "randomKRationalPoint(Ideal)"

For the programmer
==================

The object randomKRationalPoint, is a method function.

randomMutableMatrix(ZZ,ZZ,RR,ZZ) -- a random mutable matrix of integers
***********************************************************************

Synopsis
========

  * Function: randomMutableMatrix,
  * Usage:
        randomMutableMatrix(nrows,ncols,zerof,max)
  * Inputs:
      * nrows
      * ncols
      * zerof, between 0 and 1
      * max
  * Optional inputs,:
      * Dense => ..., default value false, whether the encoding of the matrix
        should be dense or not: see MutableMatrix,
  * Outputs:
      * a random mutable nrows by ncols matrix of integers. The absolute value
        of the entries is less than max, and the frequency of entries equal to
        zero is given by zerof.

Description
===========

This function has been superseded by fillMatrix, which works
over more rings, is much faster for large matrices, and is more flexible.
+-------------------------------------------------------+
|i1 : randomMutableMatrix(10,15,.9,100)                 |
|                                                       |
|o1 = | 0 0   0  0   0  0 0   0 0  0 49  0   0   0  0  ||
|     | 0 0   0  0   14 0 0   0 0  0 0   0   0   0  0  ||
|     | 0 0   0  0   0  0 0   0 0  0 0   -12 -17 0  0  ||
|     | 0 0   0  0   0  0 1   0 0  0 0   0   0   0  0  ||
|     | 0 -87 80 0   0  0 0   0 0  0 -34 0   0   88 0  ||
|     | 1 0   0  0   0  0 -70 0 0  0 0   0   0   0  0  ||
|     | 0 0   0  100 0  0 0   0 0  0 0   0   0   0  0  ||
|     | 0 0   0  0   0  0 82  0 0  0 0   0   0   0  72 ||
|     | 0 0   0  0   0  0 0   0 48 0 0   0   0   99 0  ||
|     | 0 0   0  0   0  0 0   0 0  0 0   0   0   0  0  ||
|                                                       |
|o1 : MutableMatrix                                     |
+-------------------------------------------------------+

See also
========

  * mutableMatrix -- make a mutable matrix
  * fillMatrix -- fill a mutable matrix with random numbers
  * setRandomSeed -- set starting point for random number
    generator
  * random -- get a random object

Ways to use this method:
========================

  * randomMutableMatrix(ZZ,ZZ,RR,ZZ)
    -- a random mutable matrix of
    integers

Range -- can be assigned a integral interval
********************************************

Synopsis
========

  * Usage:
        getPrimeWithRootOfUnity(p,r,Range=>(a,b))
  * Inputs:
      * a, an integer,
      * b, an integer,

Description
===========

Specifies an integral interval in which we search for a prime number with
desired properties. If $b< a+2*log a$ an error message will be returned. The
default value is $(10^4,3*10^4)$

See also
========

  * nextPrime -- compute the smallest prime greater than or
    equal to a given number
  * getPrimeWithRootOfUnity -- find a prime p
    with a primitive n-th root of unity r in ZZ/p

Functions with optional argument named Range:
=============================================

  * "getPrimeWithRootOfUnity(...,Range=>...)" -- see
    getPrimeWithRootOfUnity, -- find a prime p with a
    primitive n-th root of unity r in ZZ/p

For the programmer
==================

The object Range, is a symbol.

rank -- compute the rank
************************

Synopsis
========

  * Usage:
        rank M
  * Inputs:
      * M, a module, a graded module, a
        chain complex, or a matrix,
  * Outputs:
      * the rank of M

Description
===========

+----------------------------------+
|i1 : R = ZZ/101[x,y,z]            |
|                                  |
|o1 = R                            |
|                                  |
|o1 : PolynomialRing               |
+----------------------------------+
|i2 : p = vars R;                  |
|                                  |
|             1      3             |
|o2 : Matrix R  <-- R              |
+----------------------------------+
|i3 : rank kernel p                |
|                                  |
|o3 = 2                            |
+----------------------------------+
|i4 : rank cokernel p              |
|                                  |
|o4 = 0                            |
+----------------------------------+
|i5 : C = res cokernel p           |
|                                  |
|      1      3      3      1      |
|o5 = R  <-- R  <-- R  <-- R  <-- 0|
|                                  |
|     0      1      2      3      4|
|                                  |
|o5 : ChainComplex                 |
+----------------------------------+
|i6 : rank C                       |
|                                  |
|o6 = 0                            |
+----------------------------------+

Ways to use rank:
=================

  * "rank(GradedModule)"
  * "rank(Matrix)"
  * "rank(Module)"
  * "rank(MutableMatrix)"
  * rank(CoherentSheaf) (missing documentation)

For the programmer
==================

The object rank, is a method function.

rays -- 1-dimensional cones of a fan or polyhedral object
*********************************************************

See also
========

  * rays(Matrix) (FourTiTwo) -- calculates the extreme
    rays of the cone; invokes "rays" from 4ti2
  * rays(NormalToricVariety) (NormalToricVarieties)
    -- get the rays of the
    associated fan
  * rays(PolyhedralObject) (Polyhedra), --
    displays all rays of a Cone, a Fan, or a Polyhedron
  * null -- the unique member of the empty class

Ways to use rays:
=================

  * rays(Matrix) (missing documentation)
  * rays(PolyhedralObject) (Polyhedra), --
    displays all rays of a Cone, a Fan, or a Polyhedron

For the programmer
==================

The object rays, is a method function with options.

read -- read from a file
************************

Ways to use read:
=================

  * read(File) -- read from a file
  * read(File,ZZ) -- read from a file
  * read(Sequence) -- read from a file
  * read(String) -- read from a file

For the programmer
==================

The object read, is a compiled function.

read(File) -- read from a file
******************************

Synopsis
========

  * Function: read,
  * Usage:
        read f
  * Inputs:
      * f, an input file
  * Outputs:
      * a string obtained by reading from f.

Description
===========

+------------------------------+
|i1 : f = openInOut "!cat"     |
|                              |
|o1 = !cat                     |
|                              |
|o1 : File                     |
+------------------------------+
|i2 : isReady f                |
|                              |
|o2 = false                    |
+------------------------------+
|i3 : f << "hi there" << flush;|
+------------------------------+
|i4 : isReady f                |
|                              |
|o4 = false                    |
+------------------------------+
|i5 : read f                   |
|                              |
|o5 = hi there                 |
+------------------------------+
|i6 : isReady f                |
|                              |
|o6 = false                    |
+------------------------------+

See also
========

  * openIn -- open an input file
  * get -- get the contents of a file
  * isReady -- whether a file has data available for
    reading

Ways to use this method:
========================

  * read(File) -- read from a file

read(File,ZZ) -- read from a file
*********************************

Synopsis
========

  * Function: read,
  * Usage:
        read(f,n)
  * Inputs:
      * f, a file
      * n, an integer specifying the maximum number of bytes to read
  * Outputs:
      * a string obtained by reading from f

Description
===========

Input files are buffered, so the current contents of the buffer are returned if
the buffer is not empty, otherwise reading from the file is attempted first.

See also
========

  * openIn -- open an input file
  * get -- get the contents of a file
  * isReady -- whether a file has data available for
    reading

Ways to use this method:
========================

  * read(File,ZZ) -- read from a file

read(Sequence) -- read from a file
**********************************

Synopsis
========

  * Function: read,
  * Usage:
        read()
  * Inputs:
      * ()
  * Outputs:
      * a string obtained by reading a line from the standard input file, see
        stdio.

Ways to use this method:
========================

  * read(Sequence) -- read from a file

read(String) -- read from a file
********************************

Synopsis
========

  * Function: read,
  * Usage:
        read p
  * Inputs:
      * p, a string containing a prompt to be displayed for the user
  * Outputs:
      * a string obtained by reading from the standard input file stdio,

Ways to use this method:
========================

  * read(String) -- read from a file

RealField -- the class of all real fields
*****************************************

Description
===========

A real number ring is a ring whose elements are real numbers of variable
precision.

For the programmer
==================

The object RealField, is a type, with ancestor
classes InexactField, < EngineRing <
Ring < Type < MutableHashTable
< HashTable < Thing.

realPart -- real part
*********************

Synopsis
========

  * Usage:
        realPart z
  * Inputs:
      * z, an integer, rational, real or complex number
  * Outputs:
      * the real part of the complex number z.

Description
===========

+-------------------------+
|i1 : realPart(3/4)       |
|                         |
|     3                   |
|o1 = -                   |
|     4                   |
|                         |
|o1 : QQ                  |
+-------------------------+
|i2 : realPart(1.5+2*ii)  |
|                         |
|o2 = 1.5                 |
|                         |
|o2 : RR (of precision 53)|
+-------------------------+

See also
========

  * CC -- the class of all complex numbers
  * imaginaryPart -- imaginary part

Ways to use realPart:
=====================

  * "realPart(InexactNumber)"
  * "realPart(Number)"
  * "realPart(QQ)"
  * "realPart(ZZ)"

For the programmer
==================

The object realPart, is a method function.

recursionDepth -- the current recursion depth
*********************************************

Synopsis
========

  * Usage:
        recursionDepth()
  * Outputs:
      * an integer, the current depth of recursion in the
        interpreter

Description
===========

+------------------------------+
|i1 : recursionDepth()         |
|                              |
|o1 = 14                       |
+------------------------------+
|i2 : f = x -> recursionDepth()|
|                              |
|o2 = f                        |
|                              |
|o2 : FunctionClosure          |
+------------------------------+
|i3 : f()                      |
|                              |
|o3 = 15                       |
+------------------------------+
|i4 : g = x -> f()             |
|                              |
|o4 = g                        |
|                              |
|o4 : FunctionClosure          |
+------------------------------+
|i5 : g()                      |
|                              |
|o5 = 16                       |
+------------------------------+
Tail recursion optimization may be in effect, so there the answer may not
always be what you expect.
+-----------------------------------------------------------+
|i6 : r = i -> if i == 100 then recursionDepth() else r(i+1)|
|                                                           |
|o6 = r                                                     |
|                                                           |
|o6 : FunctionClosure                                       |
+-----------------------------------------------------------+
|i7 : r 0                                                   |
|                                                           |
|o7 = 15                                                    |
+-----------------------------------------------------------+

See also
========

  * recursionLimit -- set the limit on recursion

For the programmer
==================

The object recursionDepth, is a compiled function.

recursionLimit -- set the limit on recursion
********************************************

Synopsis
========

  * Usage:
        recursionLimit = n
  * Inputs:
      * n, an integer,
  * Consequences:
      * The recursion depth limit for the interpreter is set to n.

Description
===========

Each time a function is called, the recursion depth is incremented by 1, and
each time a function returns, the recursion depth is decremented. This limit on
recursion depth is a way to detect infinite loops.

For the programmer
==================

The object recursionLimit, is an integer.

reducedRowEchelonForm -- compute the reduced row echelon form of a matrix or mutable matrix over a field
********************************************************************************************************

Synopsis
========

  * Usage:
        R = reducedRowEchelonForm A
  * Inputs:
      * A, a matrix, or a mutable matrix,
        a matrix over either a finite field or the rationals
  * Outputs:
      * R, a matrix, or a mutable matrix,
        the same type as A, the reduced row echelon form of A

Description
===========

A matrix over a field is in reduced row echelon form if (1) all rows consisting
only of zeros are at the bottom, (2) the leading coefficient  (called the
pivot) of a nonzero row is always strictly to the right of the leading
coefficient of the row above it, and (3) the leading coefficient of each
nonzero row is 1.  See Row echelon form (see
https://en.wikipedia.org/wiki/Row_echelon_form ) for more discussion.

Given a matrix A (over a field), there is a unique matrix R such that (1) the
row spans of A and R are the same, and (2) R is in reduced row echelon form.

If the matrix A is over either a finite field, or the rationals, then this
returns the unique reduced row echelon form for the matrix, which is unique.

+------------------------------------------------------------+
|i1 : R0 = matrix(QQ, {{1,0,3,0,5},{0,1,-2,0,2},{0,0,0,1,7}})|
|                                                            |
|o1 = | 1 0 3  0 5 |                                         |
|     | 0 1 -2 0 2 |                                         |
|     | 0 0 0  1 7 |                                         |
|                                                            |
|              3       5                                     |
|o1 : Matrix QQ  <-- QQ                                      |
+------------------------------------------------------------+
|i2 : B = matrix(QQ, {{1,2,3},{0,3,-1},{1,2,0}})             |
|                                                            |
|o2 = | 1 2 3  |                                             |
|     | 0 3 -1 |                                             |
|     | 1 2 0  |                                             |
|                                                            |
|              3       3                                     |
|o2 : Matrix QQ  <-- QQ                                      |
+------------------------------------------------------------+
|i3 : A = B * R0                                             |
|                                                            |
|o3 = | 1 2 -1 3  30 |                                       |
|     | 0 3 -6 -1 -1 |                                       |
|     | 1 2 -1 0  9  |                                       |
|                                                            |
|              3       5                                     |
|o3 : Matrix QQ  <-- QQ                                      |
+------------------------------------------------------------+
|i4 : R = reducedRowEchelonForm A                            |
|                                                            |
|o4 = | 1 0 3  0 5 |                                         |
|     | 0 1 -2 0 2 |                                         |
|     | 0 0 0  1 7 |                                         |
|                                                            |
|              3       5                                     |
|o4 : Matrix QQ  <-- QQ                                      |
+------------------------------------------------------------+
|i5 : assert(R == R0)                                        |
+------------------------------------------------------------+
|i6 : LUdecomposition A                                      |
|                                                            |
|o6 = ({0, 1, 2}, | 1 0 0 |, | -1/9 -2/9 1/9 -1/3 -10/3 |)   |
|                 | 0 1 0 |  | 0    -1/3 2/3 1/9  1/9   |    |
|                 | 1 0 1 |  | 0    0    0   1    7     |    |
|                                                            |
|o6 : Sequence                                               |
+------------------------------------------------------------+
+-----------------------------+
|i7 : A5 = sub(A, ZZ/5)       |
|                             |
|o7 = | 1 2  -1 -2 0  |       |
|     | 0 -2 -1 -1 -1 |       |
|     | 1 2  -1 0  -1 |       |
|                             |
|             ZZ 3      ZZ 5  |
|o7 : Matrix (--)  <-- (--)   |
|              5         5    |
+-----------------------------+
|i8 : reducedRowEchelonForm A5|
|                             |
|o8 = | 1 0 -2 0 0 |          |
|     | 0 1 -2 0 2 |          |
|     | 0 0 0  1 2 |          |
|                             |
|             ZZ 3      ZZ 5  |
|o8 : Matrix (--)  <-- (--)   |
|              5         5    |
+-----------------------------+
|i9 : rank A5                 |
|                             |
|o9 = 3                       |
+-----------------------------+

This function is useful while learning the concepts and algorithms of linear
algebra.  In practice though, one tends to use LU decompositions rather than
reduced row echelon forms.

In fact, this function doesn't work over the reals or complexes (due to often
poor numerical stability), as an LU decomposition is better for solving systems
over the real numbers.  If numerical stability is an issue, using a singular
value decomposition (SVD) is also a good idea.

+-----------------------------------------------------------------------------+
|i10 : AR = sub(A, RR)                                                        |
|                                                                             |
|o10 = | 1 2 -1 3  30 |                                                       |
|      | 0 3 -6 -1 -1 |                                                       |
|      | 1 2 -1 0  9  |                                                       |
|                                                                             |
|                 3         5                                                 |
|o10 : Matrix RR    <-- RR                                                    |
|               53        53                                                  |
+-----------------------------------------------------------------------------+
|i11 : LUdecomposition AR                                                     |
|                                                                             |
|o11 = ({0, 1, 2}, | 1 0 0 |, | 1 2 -1 3  30  |)                              |
|                  | 0 1 0 |  | 0 3 -6 -1 -1  |                               |
|                  | 1 0 1 |  | 0 0 0  -3 -21 |                               |
|                                                                             |
|o11 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i12 : SVD AR                                                                 |
|                                                                             |
|o12 = ({31.6062}, | -.956949 .0376118 -.287807 |, | -.0394384 -.0769597      |
|       {6.95666}  | .0201977 -.980536 -.195297 |  | -.0222938 -.467435       |
|       {1.28466}  | -.289551 -.192702 .937564  |  | .505782   .555496        |
|                                                  | .0471081  .572207        |
|                                                  | -.860182  .373609        |
|      -----------------------------------------------------------------------|
|      .0356042 -.0914707 -.991407   |)                                       |
|      .86799   .157169   .0538433   |                                        |
|      .406354  -.520081  -.00066372 |                                        |
|      .172926  .792242   -.113177   |                                        |
|      .224276  -.262297  .037471    |                                        |
|                                                                             |
|o12 : Sequence                                                               |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i13 : AC = sub(A, CC)                                                        |
|                                                                             |
|o13 = | 1 2 -1 3  30 |                                                       |
|      | 0 3 -6 -1 -1 |                                                       |
|      | 1 2 -1 0  9  |                                                       |
|                                                                             |
|                 3         5                                                 |
|o13 : Matrix CC    <-- CC                                                    |
|               53        53                                                  |
+-----------------------------------------------------------------------------+
|i14 : LUdecomposition AC                                                     |
|                                                                             |
|o14 = ({0, 1, 2}, | 1 0 0 |, | 1 2 -1 3  30  |)                              |
|                  | 0 1 0 |  | 0 3 -6 -1 -1  |                               |
|                  | 1 0 1 |  | 0 0 0  -3 -21 |                               |
|                                                                             |
|o14 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i15 : SVD AC                                                                 |
|                                                                             |
|o15 = ({31.6062}, | -.956949 .0376118 -.287807 |, | -.0394384 -.0769597      |
|       {6.95666}  | .0201977 -.980536 -.195297 |  | -.0222938 -.467435       |
|       {1.28466}  | -.289551 -.192702 .937564  |  | .505782   .555496        |
|                                                  | .0471081  .572207        |
|                                                  | -.860182  .373609        |
|      -----------------------------------------------------------------------|
|      .0356042 -.0914707 -.991407   |)                                       |
|      .86799   .157169   .0538433   |                                        |
|      .406354  -.520081  -.00066372 |                                        |
|      .172926  .792242   -.113177   |                                        |
|      .224276  -.262297  .037471    |                                        |
|                                                                             |
|o15 : Sequence                                                               |
+-----------------------------------------------------------------------------+

This function also works over finite fields.

+-----------------------------------+
|i16 : A9 = sub(A, GF 9)            |
|                                   |
|o16 = | 1 -1 -1 0  0  |            |
|      | 0 0  0  -1 -1 |            |
|      | 1 -1 -1 0  0  |            |
|                                   |
|                   3           5   |
|o16 : Matrix (GF 9)  <-- (GF 9)    |
+-----------------------------------+
|i17 : R9 = reducedRowEchelonForm A9|
|                                   |
|o17 = | 1 -1 -1 0 0 |              |
|      | 0 0  0  1 1 |              |
|      | 0 0  0  0 0 |              |
|                                   |
|                   3           5   |
|o17 : Matrix (GF 9)  <-- (GF 9)    |
+-----------------------------------+

It is not yet implemented over fraction fields and extension fields. Use
LUdecomposition, instead.

+-----------------------------------------------------------------------------+
|i18 : S = frac(QQ[x])                                                        |
|                                                                             |
|o18 = S                                                                      |
|                                                                             |
|o18 : FractionField                                                          |
+-----------------------------------------------------------------------------+
|i19 : R = matrix(S, {{1,0,x,0,x^2+1},{0,1,-1/x,0,2*x},{0,0,0,1,7*x}})        |
|                                                                             |
|o19 = | 1 0 x      0 x2+1 |                                                  |
|      | 0 1 (-1)/x 0 2x   |                                                  |
|      | 0 0 0      1 7x   |                                                  |
|                                                                             |
|              3      5                                                       |
|o19 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+
|i20 : B = matrix(S, {{1,2*x,3},{0,3,-x},{1,2*x^2,0}})                        |
|                                                                             |
|o20 = | 1 2x  3  |                                                           |
|      | 0 3   -x |                                                           |
|      | 1 2x2 0  |                                                           |
|                                                                             |
|              3      3                                                       |
|o20 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+
|i21 : A = B * R                                                              |
|                                                                             |
|o21 = | 1 2x  x-2    3  5x2+21x+1 |                                          |
|      | 0 3   (-3)/x -x -7x2+6x   |                                          |
|      | 1 2x2 -x     0  4x3+x2+1  |                                          |
|                                                                             |
|              3      5                                                       |
|o21 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+
|i22 : LUdecomposition A                                                      |
|                                                                             |
|o22 = ({0, 1, 2}, | 1 0          0 |, | 1 2x x-2    3                        |
|                  | 0 1          0 |  | 0 3  (-3)/x -x                       |
|                  | 1 (2x2-2x)/3 1 |  | 0 0  0      (2x3-2x2-9)/3            |
|      -----------------------------------------------------------------------|
|      5x2+21x+1         |)                                                   |
|      -7x2+6x           |                                                    |
|      (14x4-14x3-63x)/3 |                                                    |
|                                                                             |
|o22 : Sequence                                                               |
+-----------------------------------------------------------------------------+

Even though it is not implemented currently as a canned routine, we can put A
into reduced row echelon form using elementary row operations.  Recall that
rows and columns in Macaulay2 are indexed starting with 0.

+-----------------------------------------------------+
|i23 : M = mutableMatrix A                            |
|                                                     |
|o23 = | 1 2x  x-2    3  5x2+21x+1 |                  |
|      | 0 3   (-3)/x -x -7x2+6x   |                  |
|      | 1 2x2 -x     0  4x3+x2+1  |                  |
|                                                     |
|o23 : MutableMatrix                                  |
+-----------------------------------------------------+
|i24 : rowAdd(M, 2, -1, 0)                            |
|                                                     |
|o24 = | 1 2x     x-2    3  5x2+21x+1   |             |
|      | 0 3      (-3)/x -x -7x2+6x     |             |
|      | 0 2x2-2x -2x+2  -3 4x3-4x2-21x |             |
|                                                     |
|o24 : MutableMatrix                                  |
+-----------------------------------------------------+
|i25 : rowMult(M, 1, 1/M_(1,1))                       |
|                                                     |
|o25 = | 1 2x     x-2    3      5x2+21x+1   |         |
|      | 0 1      (-1)/x (-x)/3 (-7x2+6x)/3 |         |
|      | 0 2x2-2x -2x+2  -3     4x3-4x2-21x |         |
|                                                     |
|o25 : MutableMatrix                                  |
+-----------------------------------------------------+
|i26 : rowAdd(M, 2, -M_(2,1), 1)                      |
|                                                     |
|o26 = | 1 2x x-2    3             5x2+21x+1         ||
|      | 0 1  (-1)/x (-x)/3        (-7x2+6x)/3       ||
|      | 0 0  0      (2x3-2x2-9)/3 (14x4-14x3-63x)/3 ||
|                                                     |
|o26 : MutableMatrix                                  |
+-----------------------------------------------------+
|i27 : rowMult(M, 2, 1/M_(2,3))                       |
|                                                     |
|o27 = | 1 2x x-2    3      5x2+21x+1   |             |
|      | 0 1  (-1)/x (-x)/3 (-7x2+6x)/3 |             |
|      | 0 0  0      1      7x          |             |
|                                                     |
|o27 : MutableMatrix                                  |
+-----------------------------------------------------+

At this point the matrix is in row echelon form. We clear out the entries above
the pivots to place it into reduced row echelon form.

+-------------------------------------------------+
|i28 : rowAdd(M, 0, -M_(0,1), 1)                  |
|                                                 |
|o28 = | 1 0 x      (2x2+9)/3 (14x3+3x2+63x+3)/3 ||
|      | 0 1 (-1)/x (-x)/3    (-7x2+6x)/3        ||
|      | 0 0 0      1         7x                 ||
|                                                 |
|o28 : MutableMatrix                              |
+-------------------------------------------------+
|i29 : rowAdd(M, 0, -M_(0,3), 2)                  |
|                                                 |
|o29 = | 1 0 x      0      x2+1        |          |
|      | 0 1 (-1)/x (-x)/3 (-7x2+6x)/3 |          |
|      | 0 0 0      1      7x          |          |
|                                                 |
|o29 : MutableMatrix                              |
+-------------------------------------------------+
|i30 : rowAdd(M, 1, -M_(1,3), 2)                  |
|                                                 |
|o30 = | 1 0 x      0 x2+1 |                      |
|      | 0 1 (-1)/x 0 2x   |                      |
|      | 0 0 0      1 7x   |                      |
|                                                 |
|o30 : MutableMatrix                              |
+-------------------------------------------------+
|i31 : assert(R == matrix M)                      |
+-------------------------------------------------+

See also
========

  * rowAdd -- add a multiple of one row to another
  * rowMult -- multiply a row by a ring element
  * rowPermute -- permute some rows
  * rowSwap -- interchange rows
  * LUdecomposition -- LU decomposition
  * SVD -- singular value decomposition of a matrix
  * rank(Matrix) -- compute the rank

Ways to use reducedRowEchelonForm:
==================================

  * "reducedRowEchelonForm(Matrix)"
  * "reducedRowEchelonForm(MutableMatrix)"

For the programmer
==================

The object reducedRowEchelonForm, is a
method function.

regularity -- compute the Castelnuovo-Mumford regularity
********************************************************

Synopsis
========

  * Usage:
        r = regularity C
        r = regularity(C, Weights => w)
  * Inputs:
      * C, a chain complex, an ideal, or a
        module,
  * Optional inputs,:
      * Weights => a list, default value null, a weight vector w,
        see betti(...,Weights=>...),;
  * Outputs:
      * r, an integer,

Description
===========

For a free chain complex C, the regularity r is the smallest number so that
each basis element of C_i has degree at most i+r. For an ideal I, regularity is
one plus the regularity of the minimal free resolution of the quotient of the
ambient ring by I. For a module M, regularity is the regularity of a minimal
free resolution of M.

+--------------------------------------------+
|i1 : R = ZZ/32003[a..d];                    |
+--------------------------------------------+
|i2 : I = ideal(a^20, b^20, a*c^19-b*d^19);  |
|                                            |
|o2 : Ideal of R                             |
+--------------------------------------------+
|i3 : C = resolution I                       |
|                                            |
|      1      3      23      40      19      |
|o3 = R  <-- R  <-- R   <-- R   <-- R   <-- 0|
|                                            |
|     0      1      2       3       4       5|
|                                            |
|o3 : ChainComplex                           |
+--------------------------------------------+
|i4 : regularity C                           |
|                                            |
|o4 = 398                                    |
+--------------------------------------------+
|i5 : regularity comodule I                  |
|                                            |
|o5 = 398                                    |
+--------------------------------------------+
|i6 : regularity I                           |
|                                            |
|o6 = 399                                    |
+--------------------------------------------+
|i7 : regularity module I                    |
|                                            |
|o7 = 399                                    |
+--------------------------------------------+

The regularity is the label of the last row in the Betti diagram,
of a chain complex. However, this depends on the total degree weights in the
Betti tally, which are computed based on the heft vector,
of the underlying ring. To adjust this vector, a vector w whose length is the
same as the degree length, of the ring can be provided
using the option Weights. The dot products of w with the multidegrees in the
tally will be used in the resulting computation.

+----------------------------------------------------+
|i8 : C = resolution ideal(a^3, a^2*b, a*b^6, a^2*c);|
+----------------------------------------------------+
|i9 : betti C                                        |
|                                                    |
|            0 1 2 3                                 |
|o9 = total: 1 4 4 1                                 |
|         0: 1 . . .                                 |
|         1: . . . .                                 |
|         2: . 3 3 1                                 |
|         3: . . . .                                 |
|         4: . . . .                                 |
|         5: . . . .                                 |
|         6: . 1 1 .                                 |
|                                                    |
|o9 : BettiTally                                     |
+----------------------------------------------------+
|i10 : regularity C                                  |
|                                                    |
|o10 = 6                                             |
+----------------------------------------------------+
|i11 : betti(C, Weights => {2})                      |
|                                                    |
|             0 1 2 3                                |
|o11 = total: 1 4 4 1                                |
|          0: 1 . . .                                |
|          1: . . . .                                |
|          2: . . . .                                |
|          3: . . . .                                |
|          4: . . . .                                |
|          5: . 3 . .                                |
|          6: . . 3 .                                |
|          7: . . . 1                                |
|          8: . . . .                                |
|          9: . . . .                                |
|         10: . . . .                                |
|         11: . . . .                                |
|         12: . . . .                                |
|         13: . 1 . .                                |
|         14: . . 1 .                                |
|                                                    |
|o11 : BettiTally                                    |
+----------------------------------------------------+
|i12 : regularity(C, Weights => {2})                 |
|                                                    |
|o12 = 14                                            |
+----------------------------------------------------+

See also
========

  * resolution -- projective resolution
  * betti -- display or modify a Betti diagram
  * comodule -- submodule to quotient module
  * multigradedRegularity (VirtualResolutions), --
    computes the minimal elements of the multigraded regularity of a module
    over a multigraded ring

Ways to use regularity:
=======================

  * "regularity(BettiTally)" -- see BettiTally, -- the class
    of all Betti tallies
  * "regularity(ChainComplex)"
  * "regularity(Ideal)"
  * "regularity(Module)"

For the programmer
==================

The object regularity, is a method function with options.

regularizedBeta -- regularized beta function
********************************************

Synopsis
========

  * Usage:
        regularizedBeta(x, a, b)
  * Inputs:
      * x, a real number,
      * a, a real number,
      * b, a real number,
  * Outputs:
      * a real number,

Description
===========

This is the regularized (incomplete) beta function (see
https://en.wikipedia.org/wiki/beta_function ) \(I_x(a, b) = \frac{1}{B(a,
b)}\int_0^x t^{a - 1} (1 - t)^{b - 1}\,dt\).

+----------------------------------------------------------+
|i1 : regularizedBeta(1/2, 3, 4)                           |
|                                                          |
|o1 = .6562499999999997                                    |
|                                                          |
|o1 : RR (of precision 53)                                 |
+----------------------------------------------------------+
|i2 : 1/Beta(3,4) * integrate(t -> t^2 * (1 - t)^3, 0, 1/2)|
|                                                          |
|o2 = .65625                                               |
|                                                          |
|o2 : RR (of precision 53)                                 |
+----------------------------------------------------------+

See also
========

  * Beta -- Beta function
  * inverseRegularizedBeta -- inverse of the
    regularized beta function

Ways to use regularizedBeta:
============================

  * "regularizedBeta(CC,CC,CC)"
  * "regularizedBeta(CC,CC,RR)"
  * "regularizedBeta(CC,RR,CC)"
  * "regularizedBeta(CC,RR,RR)"
  * "regularizedBeta(RR,CC,CC)"
  * "regularizedBeta(RR,CC,RR)"
  * "regularizedBeta(RR,RR,CC)"
  * "regularizedBeta(RR,RR,RR)"
  * "regularizedBeta(RR,RR,RRi)"
  * "regularizedBeta(RR,RRi,RR)"
  * "regularizedBeta(RR,RRi,RRi)"
  * "regularizedBeta(RRi,RR,RR)"
  * "regularizedBeta(RRi,RR,RRi)"
  * "regularizedBeta(RRi,RRi,RR)"
  * "regularizedBeta(RRi,RRi,RRi)"

For the programmer
==================

The object regularizedBeta, is a method function.

regularizedGamma -- upper regularized gamma function
****************************************************

Synopsis
========

  * Usage:
        regularizedGamma(s, x)
  * Inputs:
      * s, a real number,
      * x, a real number,
  * Outputs:
      * a real number,

Description
===========

This is the (upper) regularized gamma function \(Q(s, x) =
\frac{\Gamma(s,x)}{\Gamma(s)}\).

+---------------------------+
|i1 : regularizedGamma(3, 7)|
|                           |
|o1 = .02963616388052177    |
|                           |
|o1 : RR (of precision 53)  |
+---------------------------+
|i2 : Gamma(3, 7) / Gamma 3 |
|                           |
|o2 = .02963616388052178    |
|                           |
|o2 : RR (of precision 53)  |
+---------------------------+

See also
========

  * Gamma -- Gamma function
  * inverseRegularizedGamma -- inverse of the
    upper regularized gamma function

Ways to use regularizedGamma:
=============================

  * "regularizedGamma(CC,CC)"
  * "regularizedGamma(CC,RR)"
  * "regularizedGamma(RR,CC)"
  * "regularizedGamma(RR,RR)"
  * "regularizedGamma(RR,RRi)"
  * "regularizedGamma(RRi,RR)"
  * "regularizedGamma(RRi,RRi)"

For the programmer
==================

The object regularizedGamma, is a method function.

relations -- the defining relations
***********************************

Description
===========

relations M -- produce the relations defining a module M.

The relations are represented as a matrix, and if not stored in the module
under M.relations, the matrix is understood to be empty.

See also
========

  * generators -- provide matrix or list of generators
  * subquotient -- make a subquotient module

Ways to use relations:
======================

  * "relations(Module)"

For the programmer
==================

The object relations, is a method function.

relativizeFilename -- relativize a file name
********************************************

Synopsis
========

  * Usage:
        relativizeFilename(dir,fn)
  * Inputs:
      * dir, a path to a directory
      * fn, a path to a file
  * Outputs:
      * a relativized path, equivalent to fn when starting from dir

Description
===========

+--------------------------------------------+
|i1 : relativizeFilename("a/b/","a/b/c/d")   |
|                                            |
|o1 = c/d                                    |
+--------------------------------------------+
|i2 : relativizeFilename("a/b/c/d","a/b/")   |
|                                            |
|o2 = ../../                                 |
+--------------------------------------------+
|i3 : relativizeFilename("a/b/c/d","a/b/e/f")|
|                                            |
|o3 = ../../e/f                              |
+--------------------------------------------+

Paths of the form foo/x/../bar, are shortened to foo/bar without checking the
file system to see whether x is a symbolic link.  For the other behavior, see
realpath.

See also
========

  * File -- the class of all files
  * minimizeFilename -- minimize a file name
  * baseFilename -- the base part of a filename or path
  * toAbsolutePath -- the absolute path version of a
    file name
  * searchPath -- search a path for a
    file
  * path -- list of directories to look in

For the programmer
==================

The object relativizeFilename, is a compiled function.

remainder -- matrix remainder
*****************************

Synopsis
========

  * Usage:
        r = remainder(f,g)
  * Inputs:
      * f, a matrix,
      * g, a Gröbner basis, or a matrix,
        with the same target as f
  * Outputs:
      * r, the remainder of f upon division by g

Description
===========

This operation is the same as Matrix % GroebnerBasis.

The equation g*q+r == f will hold, where q is the map provided by
quotient.  The source of f should be a free module.

+----------------------------------------------+
|i1 : R = ZZ[x,y]                              |
|                                              |
|o1 = R                                        |
|                                              |
|o1 : PolynomialRing                           |
+----------------------------------------------+
|i2 : f = random(R^2,R^{2:-1})                 |
|                                              |
|o2 = | 8x+y  8x+3y |                          |
|     | 3x+7y 3x+7y |                          |
|                                              |
|             2      2                         |
|o2 : Matrix R  <-- R                          |
+----------------------------------------------+
|i3 : g = vars R ++ vars R                     |
|                                              |
|o3 = | x y 0 0 |                              |
|     | 0 0 x y |                              |
|                                              |
|             2      4                         |
|o3 : Matrix R  <-- R                          |
+----------------------------------------------+
|i4 : remainder(f,g)                           |
|                                              |
|o4 = 0                                        |
|                                              |
|             2      2                         |
|o4 : Matrix R  <-- R                          |
+----------------------------------------------+
|i5 : f = f + map(target f, source f, id_(R^2))|
|                                              |
|o5 = | 8x+y+1 8x+3y   |                       |
|     | 3x+7y  3x+7y+1 |                       |
|                                              |
|             2      2                         |
|o5 : Matrix R  <-- R                          |
+----------------------------------------------+
|i6 : remainder(f,g)                           |
|                                              |
|o6 = | 1 0 |                                  |
|     | 0 1 |                                  |
|                                              |
|             2      2                         |
|o6 : Matrix R  <-- R                          |
+----------------------------------------------+

See also
========

  * quotientRemainder -- matrix quotient and
    remainder
  * remainder' -- matrix quotient and remainder (opposite)

Ways to use remainder:
======================

  * "remainder(Matrix,GroebnerBasis)"
  * "remainder(Matrix,Matrix)"

For the programmer
==================

The object remainder, is a method function.

remainder' -- matrix quotient and remainder (opposite)
******************************************************

Synopsis
========

  * Usage:
        r = remainder'(f,g)
  * Inputs:
      * f, a matrix,
      * g, a Gröbner basis, or a matrix,
        with the same source as f
  * Outputs:
      * r, the remainder of f upon (opposite) division by g

Description
===========

The equation q*g+r == f will hold, where q is the map provided by
quotient'.  The sources and targets of the maps should be free
modules. This function is obtained from remainder by transposing the inputs and
outputs.
+----------------------------------------------+
|i1 : R = ZZ[x,y]                              |
|                                              |
|o1 = R                                        |
|                                              |
|o1 : PolynomialRing                           |
+----------------------------------------------+
|i2 : f = random(R^{2:1},R^2)                  |
|                                              |
|o2 = {-1} | 8x+y  8x+3y |                     |
|     {-1} | 3x+7y 3x+7y |                     |
|                                              |
|             2      2                         |
|o2 : Matrix R  <-- R                          |
+----------------------------------------------+
|i3 : g = transpose (vars R ++ vars R)         |
|                                              |
|o3 = {-1} | x 0 |                             |
|     {-1} | y 0 |                             |
|     {-1} | 0 x |                             |
|     {-1} | 0 y |                             |
|                                              |
|             4      2                         |
|o3 : Matrix R  <-- R                          |
+----------------------------------------------+
|i4 : remainder'(f,g)                          |
|                                              |
|o4 = 0                                        |
|                                              |
|             2      2                         |
|o4 : Matrix R  <-- R                          |
+----------------------------------------------+
|i5 : f = f + map(target f, source f, id_(R^2))|
|                                              |
|o5 = {-1} | 8x+y+1 8x+3y   |                  |
|     {-1} | 3x+7y  3x+7y+1 |                  |
|                                              |
|             2      2                         |
|o5 : Matrix R  <-- R                          |
+----------------------------------------------+
|i6 : remainder'(f,g)                          |
|                                              |
|o6 = {-1} | 1 0 |                             |
|     {-1} | 0 1 |                             |
|                                              |
|             2      2                         |
|o6 : Matrix R  <-- R                          |
+----------------------------------------------+

Code
====

method function remainder':  source code not available

See also
========

  * quotientRemainder -- matrix quotient and
    remainder
  * remainder -- matrix remainder

Ways to use remainder':
=======================

  * "remainder'(Matrix,Matrix)"

For the programmer
==================

The object remainder', is a method function.

reorganize -- reorganize a database file
****************************************

Description
===========

reorganize x -- reorganize the database file x, compactifying it.

See also
========

  * Database -- the class of all database files

For the programmer
==================

The object reorganize, is a compiled function.

replace -- replacement in strings and lists
*******************************************

Ways to use replace:
====================

  * replace(String,String,String),
    -- replace substrings matching a regular expression
  * replace(ZZ,Thing,BasicList), --
    copy a list, replacing an element

For the programmer
==================

The object replace, is a method function with options.

replace(ZZ,Thing,BasicList) -- copy a list, replacing an element
****************************************************************

Synopsis
========

  * Function: replace,
  * Usage:
        s = replace(i, t, l)
  * Inputs:
      * i, an integer,
      * t, a thing,
      * l, a basic list,
  * Outputs:
      * s, a basic list, a copy of the list l in which t has
        replaced the element at position i.

Description
===========

A negative value of i is taken relative to the end of the list.

+---------------------------------------+
|i1 : replace(4,   t, 0..10)            |
|                                       |
|o1 = (0, 1, 2, 3, t, 5, 6, 7, 8, 9, 10)|
|                                       |
|o1 : Sequence                          |
+---------------------------------------+
|i2 : replace(0,   t, 0..10)            |
|                                       |
|o2 = (t, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10)|
|                                       |
|o2 : Sequence                          |
+---------------------------------------+
|i3 : replace(10,  t, 0..10)            |
|                                       |
|o3 = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, t) |
|                                       |
|o3 : Sequence                          |
+---------------------------------------+
|i4 : replace(-1,  t, 0..10)            |
|                                       |
|o4 = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, t) |
|                                       |
|o4 : Sequence                          |
+---------------------------------------+
|i5 : replace(-11, t, 0..10)            |
|                                       |
|o5 = (t, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10)|
|                                       |
|o5 : Sequence                          |
+---------------------------------------+

Ways to use this method:
========================

  * replace(ZZ,Thing,BasicList), --
    copy a list, replacing an element

reshape -- reshape a matrix
***************************

Synopsis
========

  * Usage:
        reshape(F, G, f)
  * Inputs:
      * F, a module, a free module;
      * G, a module, a free module;
      * f, a matrix,
  * Outputs:
      * a matrix, F <-- G obtained from f by taking elements
        from the first column of f, then the second, and so on, filling them
        into the result column by column.

Description
===========

Currently, it is assumed that f and the result both have the same number of
entries. The resulting map has the same degree that f has, but it is easy to
spoil homogeneity by giving incorrect free modules.

+-----------------------------------------------+
|i1 : f = matrix{{1,3,5,7,9,11},{2,4,6,8,10,12}}|
|                                               |
|o1 = | 1 3 5 7 9  11 |                         |
|     | 2 4 6 8 10 12 |                         |
|                                               |
|              2       6                        |
|o1 : Matrix ZZ  <-- ZZ                         |
+-----------------------------------------------+
|i2 : reshape(ZZ^3,ZZ^4,f)                      |
|                                               |
|o2 = | 1 4 7 10 |                              |
|     | 2 5 8 11 |                              |
|     | 3 6 9 12 |                              |
|                                               |
|              3       4                        |
|o2 : Matrix ZZ  <-- ZZ                         |
+-----------------------------------------------+

Ways to use reshape:
====================

  * "reshape(Module,Module,Matrix)"

For the programmer
==================

The object reshape, is a method function.

Resolution -- the class of all resolution computations
******************************************************

Description
===========

These resolutions are internal engine objects not meant to be examined by the
user.

The symbol Resolution is also used in a ChainComplex, to
store the resolution it comes from.

Methods that use a resolution:
==============================

  * new ChainComplex from Resolution (missing documentation)
  * "ring(Resolution)" -- see ring, -- get the associated ring of
    an object
  * "status(Resolution)" -- see status, -- status of a resolution
    computation

For the programmer
==================

The object Resolution, is a type, with ancestor
classes MutableHashTable, < HashTable
< Thing.

resolution -- projective resolution
***********************************

Ways to use resolution:
=======================

  * resolution(Ideal) -- compute a projective
    resolution of (the quotient ring corresponding to) an ideal
  * resolution(Matrix) -- given a module map
    represented by a matrix, produce a comparison map between resolutions of
    its source and target
  * resolution(Module) -- compute a free
    resolution of a module

For the programmer
==================

The object resolution, is a method function with options.

resolution(...,DegreeLimit=>...) -- compute only up to this degree
******************************************************************

Description
===========

DegreeLimit => n -- keyword for an optional argument used with
resolution, which specifies that the computation should halt after
dealing with degree n.

This option is relevant only for homogeneous modules.

+--------------------------------------------+
|i1 : R = ZZ/101[x,y,z,w];                   |
+--------------------------------------------+
|i2 : M = cokernel matrix {{x*y-z^2,y^2-w^2}}|
|                                            |
|o2 = cokernel | xy-z2 y2-w2 |               |
|                                            |
|                            1               |
|o2 : R-module, quotient of R                |
+--------------------------------------------+
|i3 : res(M,DegreeLimit => 1)                |
|                                            |
|      1      2                              |
|o3 = R  <-- R  <-- 0                        |
|                                            |
|     0      1      2                        |
|                                            |
|o3 : ChainComplex                           |
+--------------------------------------------+
|i4 : res(M,DegreeLimit => 2)                |
|                                            |
|      1      2      1                       |
|o4 = R  <-- R  <-- R  <-- 0                 |
|                                            |
|     0      1      2      3                 |
|                                            |
|o4 : ChainComplex                           |
+--------------------------------------------+

Further information
===================

  * Default value: null
  * Function: resolution, -- projective resolution
  * Option key: DegreeLimit, -- an optional argument

Caveat
======

One might get some matrix entries of slightly higher degree than requested.

Functions with optional argument named DegreeLimit:
===================================================

  * adjoint(...,DegreeLimit=>...) (missing documentation)
  * "compose(Module,Module,Module,DegreeLimit=>...)" -- see compose,
    -- composition as a pairing on Hom-modules
  * dual(ChainComplex,DegreeLimit=>...) (missing documentation)
  * dual(Matrix,DegreeLimit=>...) (missing documentation)
  * dual(SheafMap,DegreeLimit=>...) (missing documentation)
  * "End(...,DegreeLimit=>...)" -- see End, -- module of
    endomorphisms
  * "gb(...,DegreeLimit=>...)" -- see gb, -- compute a Gröbner basis
  * "Hom(...,DegreeLimit=>...)" -- see Hom, -- module of
    homomorphisms
  * "homomorphism'(...,DegreeLimit=>...)" -- see homomorphism',
    -- get the element of Hom from a homomorphism
  * "intersectInP(...,DegreeLimit=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "minimalBetti(...,DegreeLimit=>...)" -- see minimalBetti,
    -- minimal betti numbers of (the minimal free resolution of)
    a homogeneous ideal or module
  * "pushForward(...,DegreeLimit=>...)" -- see
    pushForward(RingMap,Module),
  * quotient(...,DegreeLimit=>...) (Saturation)
  * "saturate(...,DegreeLimit=>...)" -- see
    quotient(...,DegreeLimit=>...) (Saturation),
  * "analyticSpread(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "associatedGradedRing(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "distinguished(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "isLinearType(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "isReduction(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "minimalReduction(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "multiplicity(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "normalCone(Ideal,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "normalCone(Ideal,RingElement,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "reesAlgebra(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * reesIdeal(...,DegreeLimit=>...) (ReesAlgebra)
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "specialFiber(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "specialFiberIdeal(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * resolution(...,DegreeLimit=>...)
    -- compute only up to
    this degree
  * sheafHom(...,DegreeLimit=>...) (missing documentation)
  * "syz(...,DegreeLimit=>...)" -- see syz(Matrix), --
    compute the syzygy matrix

resolution(...,HardDegreeLimit=>...)
************************************

Description
===========

HardDegreeLimit -- keyword for an optional argument used with resolution.

The default value is {}.

Information above the specified degree is discarded.

Further information
===================

  * Default value: {}
  * Function: resolution, -- projective resolution
  * Option key: HardDegreeLimit, -- compute only up to
    this degree

Functions with optional argument named HardDegreeLimit:
=======================================================

  * "gb(...,HardDegreeLimit=>...)" -- see gb, -- compute a Gröbner
    basis
  * resolution(...,HardDegreeLimit=>...)
  * "syz(...,HardDegreeLimit=>...)" -- see syz(Matrix),
    -- compute the syzygy matrix

resolution(...,LengthLimit=>...) -- stop when the resolution reaches this length
********************************************************************************

Description
===========

LengthLimit -- keyword for an optional argument used with resolution,
which indicates how long a resolution to make.

For polynomial rings over a field or over the integers, the length is taken to
be the dimension of the ring, so the complete resolution will be obtained.  For
quotient rings of such rings, the same number is used, so the complete
resolution may not be obtained.

In the current version, asking for a second and longer resolution of the same
module involves recomputing the resolution from scratch.  Eventually the
previous work will be used and the recomputation will go quicker.

The resolution returned may actually be one step longer than requested. The
extra differential is not guaranteed to be minimal.

Further information
===================

  * Default value: infinity,
  * Function: resolution, -- projective resolution
  * Option key: LengthLimit, -- stop when the resolution
    reaches this length

Functions with optional argument named LengthLimit:
===================================================

  * "minimalBetti(...,LengthLimit=>...)" -- see minimalBetti,
    -- minimal betti numbers of (the minimal free resolution of)
    a homogeneous ideal or module
  * resolution(...,LengthLimit=>...)
    -- stop when the
    resolution reaches this length

resolution(...,PairLimit=>...) -- stop when this number of pairs has been handled
*********************************************************************************

Description
===========

PairLimit -- keyword for an optional argument used with resolution,
which specifies that the computation should be stopped after a
certain number of S-pairs have been reduced.
+------------------------------------------------+
|i1 : R = QQ[x,y,z,w]                            |
|                                                |
|o1 = R                                          |
|                                                |
|o1 : PolynomialRing                             |
+------------------------------------------------+
|i2 : M = cokernel matrix {{x*y-z,y^2-w-1,w^4-3}}|
|                                                |
|o2 = cokernel | xy-z y2-w-1 w4-3 |              |
|                                                |
|                            1                   |
|o2 : R-module, quotient of R                    |
+------------------------------------------------+
|i3 : res(M, PairLimit => 1)                     |
|                                                |
|      1      1                                  |
|o3 = R  <-- R  <-- 0                            |
|                                                |
|     0      1      2                            |
|                                                |
|o3 : ChainComplex                               |
+------------------------------------------------+
|i4 : res(M, PairLimit => 10)                    |
|                                                |
|      1      1                                  |
|o4 = R  <-- R  <-- 0                            |
|                                                |
|     0      1      2                            |
|                                                |
|o4 : ChainComplex                               |
+------------------------------------------------+
|i5 : res(M, PairLimit => 20)                    |
|                                                |
|      1      1                                  |
|o5 = R  <-- R  <-- 0                            |
|                                                |
|     0      1      2                            |
|                                                |
|o5 : ChainComplex                               |
+------------------------------------------------+

Further information
===================

  * Default value: infinity,
  * Function: resolution, -- projective resolution
  * Option key: PairLimit, -- an optional argument

Functions with optional argument named PairLimit:
=================================================

  * "gb(...,PairLimit=>...)" -- see gb, -- compute a Gröbner basis
  * "intersectInP(...,PairLimit=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "pushForward(...,PairLimit=>...)" -- see pushForward(RingMap,Module),
  * quotient(...,PairLimit=>...) (Saturation)
  * "saturate(...,PairLimit=>...)" -- see quotient(...,PairLimit=>...) (Saturation),
  * "analyticSpread(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "associatedGradedRing(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "distinguished(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "isLinearType(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "isReduction(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "minimalReduction(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "multiplicity(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "normalCone(Ideal,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "normalCone(Ideal,RingElement,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "reesAlgebra(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * reesIdeal(...,PairLimit=>...) (ReesAlgebra)
    -- Bound the
    number of s-pairs considered in the saturation step
  * "specialFiber(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "specialFiberIdeal(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * resolution(...,PairLimit=>...)
    -- stop when this number
    of pairs has been handled
  * "syz(...,PairLimit=>...)" -- see syz(Matrix), --
    compute the syzygy matrix

resolution(...,SortStrategy=>...)
*********************************

Description
===========

SortStrategy => n -- an option for resolution, which
specifies the strategy to be used for sorting S-pairs.

Not implemented yet.

Further information
===================

  * Default value: 0
  * Function: resolution, -- projective resolution
  * Option key: SortStrategy, -- specify a strategy for
    sorting S-pairs

Functions with optional argument named SortStrategy:
====================================================

  * resolution(...,SortStrategy=>...)

resolution(...,StopBeforeComputation=>...) -- whether to stop the computation immediately
*****************************************************************************************

Description
===========

StopBeforeComputation -- keyword for an optional argument used with
resolution.

Tells whether to start the computation, with the default value being true.
This can be useful when you want to obtain the partially computed resolution
contained in an interrupted computation.

Further information
===================

  * Default value: false,
  * Function: resolution, -- projective resolution
  * Option key: StopBeforeComputation, -- an
    optional argument

Functions with optional argument named StopBeforeComputation:
=============================================================

  * "gb(...,StopBeforeComputation=>...)" -- see gb, -- compute a
    Gröbner basis
  * "pushForward(...,StopBeforeComputation=>...)" -- see
    pushForward(RingMap,Module),
  * resolution(...,StopBeforeComputation=>...)
    -- whether to
    stop the computation immediately
  * "syz(...,StopBeforeComputation=>...)" -- see syz(Matrix),
    -- compute the syzygy matrix

resolution(...,Strategy=>...)
*****************************

Description
===========

Strategy => n -- an option for resolution, which specifies
which algorithm to use.  Strategies are specified by number and the algorithms
available are
  * Strategy => 0 -- Compute syzygies on the Gröbner bases of each syzygy
    module.  The algorithm uses important speedups due to R. La Scala. This
    algorithm appears to be on the average the fastest.
  * Strategy => 1 -- An older version of algorithm 0, which doesn't allow as
    much experimentation, but can sometimes be marginally faster.
  * Strategy => 2 -- Compute syzygies on the minimal generators of each matrix
    in the resolution.  Over quotient rings, it's preferred.
  * Strategy => 3 -- Same as algorithm 2, but compute those Hilbert functions
    which allow removal of S-pairs (a la Robbiano, et al.). Sometimes this
    improvement can be very dramatic.
All algorithms use induced monomial orders (Schreyer orders), since this makes
an enormous improvement to the efficiency of the algorithm.

Further information
===================

  * Default value: null
  * Function: resolution, -- projective resolution
  * Option key: Strategy, -- an optional argument

Functions with optional argument named Strategy:
================================================

  * "addHook(...,Strategy=>...)" -- see addHook, -- add a hook
    function to an object for later processing
  * adjoint(...,Strategy=>...) (missing documentation)
  * "annihilator(...,Strategy=>...)" -- see annihilator (Saturation),
    -- the annihilator ideal
  * "associatedPrimes(...,Strategy=>...)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "basis(...,Strategy=>...)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * canonicalBundle(...,Strategy=>...) (missing documentation)
  * "mingens(...,Strategy=>...)" -- see Complement, -- a
    Strategy option value
  * "trim(...,Strategy=>...)" -- see Complement, -- a
    Strategy option value
  * "compose(Module,Module,Module,Strategy=>...)" -- see compose,
    -- composition as a pairing on Hom-modules
  * cotangentSheaf(...,Strategy=>...) (missing documentation)
  * determinant(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * dual(ChainComplex,Strategy=>...) (missing documentation)
  * dual(Matrix,Strategy=>...) (missing documentation)
  * "dual(MonomialIdeal,List,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...),
  * "dual(MonomialIdeal,RingElement,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...),
  * dual(MonomialIdeal,Strategy=>...)
  * dual(SheafMap,Strategy=>...) (missing documentation)
  * "End(...,Strategy=>...)" -- see End, -- module of endomorphisms
  * exteriorPower(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * "gb(...,Strategy=>...)" -- see gb, -- compute a Gröbner basis
  * gcdLLL(...,Strategy=>...) (missing documentation)
  * "GF(...,Strategy=>...)" -- see GF, -- make a finite field
  * "groebnerBasis(...,Strategy=>...)" -- see groebnerBasis,
    -- Gröbner basis, as a matrix
  * hermite(...,Strategy=>...) (missing documentation)
  * "Hom(...,Strategy=>...)" -- see Hom, -- module of homomorphisms
  * "homomorphism'(...,Strategy=>...)" -- see homomorphism',
    -- get the element of Hom from a homomorphism
  * "hooks(...,Strategy=>...)" -- see hooks, -- list hooks
    attached to a key
  * "idealizer(...,Strategy=>...)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * integralClosure(...,Strategy=>...) (IntegralClosure),
    --
    control the algorithm used
  * "intersect(Ideal,Ideal,Strategy=>...)" -- see intersect(Ideal,Ideal),
    -- compute an intersection of a sequence of
    ideals or modules
  * "intersect(Module,Module,Strategy=>...)" -- see
    intersect(Ideal,Ideal), -- compute an
    intersection of a sequence of ideals or modules
  * "intersectInP(...,Strategy=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "isPrimary(...,Strategy=>...)" -- see isPrimary (PrimaryDecomposition),
    -- determine whether a submodule is
    primary
  * "isPrime(Ideal,Strategy=>...)" -- see isPrime(Ideal) (MinimalPrimes),
    -- whether an ideal is prime
  * LLL(...,Strategy=>...) (LLLBases)
    -- choose among
    different algorithms
  * "localize(...,Strategy=>...)" -- see localize (PrimaryDecomposition),
    -- localize an ideal at a prime ideal
  * "match(...,Strategy=>...)" -- see match, -- regular expression
    matching
  * "decompose(Ideal,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * minors(...,Strategy=>...)
    -- choose between Bareiss,
    Cofactor and Dynamic algorithms
  * "parallelApply(...,Strategy=>...)" -- see parallelApply,
    -- apply a function to each element in parallel
  * "primaryComponent(...,Strategy=>...)" -- see primaryComponent (PrimaryDecomposition),
    -- find a primary component
    corresponding to an associated prime
  * pushForward(...,Strategy=>...) (missing documentation)
  * quotient(...,Strategy=>...) (Saturation)
  * "radical(...,Strategy=>...)" -- see radical (MinimalPrimes),
    -- the radical of an ideal
  * "radicalContainment(...,Strategy=>...)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * "analyticSpread(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "associatedGradedRing(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "distinguished(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isLinearType(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isReduction(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "minimalReduction(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "multiplicity(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(Ideal,RingElement,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(Ideal,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "reesAlgebra(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * reesIdeal(...,Strategy=>...) (ReesAlgebra)
    -- Choose a
    strategy for the saturation step
  * "specialFiber(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "specialFiberIdeal(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "regSeqInIdeal(...,Strategy=>...)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * resolution(...,Strategy=>...)
  * saturate(...,Strategy=>...) (Saturation)
  * sheafHom(...,Strategy=>...) (missing documentation)
  * "primaryDecomposition(...,Strategy=>...)" -- see strategies for computing primary decomposition (PrimaryDecomposition),
  * "syz(...,Strategy=>...)" -- see syz(Matrix), --
    compute the syzygy matrix
  * "tangentCone(...,Strategy=>...)" -- see tangentCone(Ideal) (TangentCone),
  * tangentSheaf(...,Strategy=>...) (missing documentation)

resolution(...,SyzygyLimit=>...) -- stop when this number of syzygies is reached
********************************************************************************

Description
===========

SyzygyLimit -- keyword for an optional argument used with resolution,
which specifies that the computation should stop after a certain
number of syzygies have computed.

+------------------------------------------------+
|i1 : R = ZZ/101[x,y,z,w];                       |
+------------------------------------------------+
|i2 : M = cokernel matrix {{x*y-z^2,y^2-w^2,w^4}}|
|                                                |
|o2 = cokernel | xy-z2 y2-w2 w4 |                |
|                                                |
|                            1                   |
|o2 : R-module, quotient of R                    |
+------------------------------------------------+
|i3 : res(M,SyzygyLimit => 1)                    |
|                                                |
|      1      1                                  |
|o3 = R  <-- R  <-- 0                            |
|                                                |
|     0      1      2                            |
|                                                |
|o3 : ChainComplex                               |
+------------------------------------------------+
|i4 : res(M,SyzygyLimit => 2)                    |
|                                                |
|      1      2                                  |
|o4 = R  <-- R  <-- 0                            |
|                                                |
|     0      1      2                            |
|                                                |
|o4 : ChainComplex                               |
+------------------------------------------------+
|i5 : res(M,SyzygyLimit => infinity)             |
|                                                |
|      1      3      3      1                    |
|o5 = R  <-- R  <-- R  <-- R  <-- 0              |
|                                                |
|     0      1      2      3      4              |
|                                                |
|o5 : ChainComplex                               |
+------------------------------------------------+

Further information
===================

  * Default value: infinity,
  * Function: resolution, -- projective resolution
  * Option key: SyzygyLimit, -- an optional argument

Functions with optional argument named SyzygyLimit:
===================================================

  * "gb(...,SyzygyLimit=>...)" -- see gb, -- compute a Gröbner basis
  * resolution(...,SyzygyLimit=>...)
    -- stop when this
    number of syzygies is reached
  * "syz(...,SyzygyLimit=>...)" -- see syz(Matrix), --
    compute the syzygy matrix

resolution(Ideal) -- compute a projective resolution of (the quotient ring corresponding to) an ideal
*****************************************************************************************************

Synopsis
========

  * Function: resolution,
  * Usage:
        resolution I
  * Inputs:
      * I, an ideal in a ring R, say
  * Optional inputs,:
      * DegreeLimit,
        => ..., default value null, compute only up to this degree
      * FastNonminimal, => ..., default value false,
        compute a non-minimal graded free resolution
      * HardDegreeLimit,
        => ..., default
        value {},
      * LengthLimit,
        => ..., default value infinity, stop when the resolution reaches this
        length
      * PairLimit, =>
        ..., default value infinity, stop when this number of pairs has been
        handled
      * ParallelizeByDegree (missing documentation) => ..., default value
        false,
      * SortStrategy,
        => ..., default value 0,
      * StopBeforeComputation,
        => ...,
        default value false, whether to stop the computation immediately
      * Strategy, =>
        ..., default value null,
      * SyzygyLimit,
        => ..., default value infinity, stop when this number of syzygies is
        reached
  * Outputs:
      * a resolution of R/I by projective R-modules

Description
===========

+-----------------------------------------+
|i1 : R = ZZ[a..d]                        |
|                                         |
|o1 = R                                   |
|                                         |
|o1 : PolynomialRing                      |
+-----------------------------------------+
|i2 : I = ideal(a,b,c,d)                  |
|                                         |
|o2 = ideal (a, b, c, d)                  |
|                                         |
|o2 : Ideal of R                          |
+-----------------------------------------+
|i3 : C = res I                           |
|                                         |
|      1      4      6      4      1      |
|o3 = R  <-- R  <-- R  <-- R  <-- R  <-- 0|
|                                         |
|     0      1      2      3      4      5|
|                                         |
|o3 : ChainComplex                        |
+-----------------------------------------+
|i4 : C_2                                 |
|                                         |
|      6                                  |
|o4 = R                                   |
|                                         |
|o4 : R-module, free, degrees {6:2}       |
+-----------------------------------------+
|i5 : C.dd_2                              |
|                                         |
|o5 = {1} | -b 0  -c 0  0  -d |           |
|     {1} | a  -c 0  0  -d 0  |           |
|     {1} | 0  b  a  -d 0  0  |           |
|     {1} | 0  0  0  c  b  a  |           |
|                                         |
|             4      6                    |
|o5 : Matrix R  <-- R                     |
+-----------------------------------------+

See also
========

  * ChainComplex _ ZZ -- component
  * dd -- differential in a chain complex
  * resolution -- projective resolution
  * ideal -- make an ideal

Ways to use this method:
========================

  * resolution(Ideal) -- compute a projective
    resolution of (the quotient ring corresponding to) an ideal

resolution(Matrix) -- given a module map represented by a matrix, produce a comparison map between resolutions of its source and target
***************************************************************************************************************************************

Synopsis
========

  * Function: resolution,
  * Usage:
        resolution f
  * Inputs:
      * f, a module homomorphism N <--- M
  * Optional inputs,:
      * DegreeLimit,
        => ..., default value null, compute only up to this degree
      * FastNonminimal, => ..., default value false,
        compute a non-minimal graded free resolution
      * HardDegreeLimit,
        => ..., default
        value {},
      * LengthLimit,
        => ..., default value infinity, stop when the resolution reaches this
        length
      * PairLimit, =>
        ..., default value infinity, stop when this number of pairs has been
        handled
      * ParallelizeByDegree (missing documentation) => ..., default value
        false,
      * SortStrategy,
        => ..., default value 0,
      * StopBeforeComputation,
        => ...,
        default value false, whether to stop the computation immediately
      * Strategy, =>
        ..., default value null,
      * SyzygyLimit,
        => ..., default value infinity, stop when this number of syzygies is
        reached
  * Outputs:
      * a chain map from a projective resolution of the source of f to a
        resolution of the target of f

Description
===========

+------------------------------------------------+
|i1 : R = ZZ[x,y,z]                              |
|                                                |
|o1 = R                                          |
|                                                |
|o1 : PolynomialRing                             |
+------------------------------------------------+
|i2 : N = R^1/(x,y,z)                            |
|                                                |
|o2 = cokernel | x y z |                         |
|                                                |
|                            1                   |
|o2 : R-module, quotient of R                    |
+------------------------------------------------+
|i3 : M = R^1/(x^2,y^2,x*y*z,z^2)                |
|                                                |
|o3 = cokernel | x2 y2 xyz z2 |                  |
|                                                |
|                            1                   |
|o3 : R-module, quotient of R                    |
+------------------------------------------------+
|i4 : f = map(N,M,1)                             |
|                                                |
|o4 = | 1 |                                      |
|                                                |
|o4 : Matrix N <-- M                             |
+------------------------------------------------+
|i5 : res f                                      |
|                                                |
|          1             1                       |
|o5 = 0 : R  <--------- R  : 0                   |
|               | 1 |                            |
|                                                |
|          3                        4            |
|     1 : R  <-------------------- R  : 1        |
|               {1} | x 0 yz 0 |                 |
|               {1} | 0 y 0  0 |                 |
|               {1} | 0 0 0  z |                 |
|                                                |
|          3                                6    |
|     2 : R  <---------------------------- R  : 2|
|               {2} | xy yz 0 0  0  0  |         |
|               {2} | 0  0  0 yz 0  0  |         |
|               {2} | 0  0  0 0  yz xz |         |
|                                                |
|          1                      3              |
|     3 : R  <------------------ R  : 3          |
|               {3} | 0 yz 0 |                   |
|                                                |
|     4 : 0 <----- 0 : 4                         |
|              0                                 |
|                                                |
|o5 : ChainComplexMap                            |
+------------------------------------------------+

See also
========

  * free resolutions of modules

Ways to use this method:
========================

  * resolution(Matrix) -- given a module map
    represented by a matrix, produce a comparison map between resolutions of
    its source and target

resolution(Module) -- compute a free resolution of a module
***********************************************************

Synopsis
========

  * Function: resolution,
  * Usage:
        resolution M
        res M
  * Inputs:
      * M
  * Optional inputs,:
      * DegreeLimit,
        => ..., default value null, compute only up to this degree
      * FastNonminimal, => ..., default value false,
        compute a non-minimal graded free resolution
      * HardDegreeLimit,
        => ..., default
        value {},
      * LengthLimit,
        => ..., default value infinity, stop when the resolution reaches this
        length
      * PairLimit, =>
        ..., default value infinity, stop when this number of pairs has been
        handled
      * ParallelizeByDegree (missing documentation) => ..., default value
        false,
      * SortStrategy,
        => ..., default value 0,
      * StopBeforeComputation,
        => ...,
        default value false, whether to stop the computation immediately
      * Strategy, =>
        ..., default value null,
      * SyzygyLimit,
        => ..., default value infinity, stop when this number of syzygies is
        reached
  * Outputs:
      * a free resolution of M

Description
===========

The given generators and relations are used to determine a presentation,
of M to serve as the first matrix of the free resolution; if the
presentation is not minimal, and a minimal resolution is desired, use
resolution minimalPresentation M instead.

Warning: the resolution can have free modules with unexpected ranks when the
module M is not homogeneous.  Here is an example where even the lengths of the
resolutions differ.  We compute a resolution of the kernel of a ring map in two
ways. The ring R is constructed naively, but the ring S is constructed with
variables of the right degrees so the ring map g will turn out to be
homogeneous.

+------------------------------------------------------------------+
|i1 : k = ZZ/101; T = k[v..z];                                     |
+------------------------------------------------------------------+
|i3 : m = matrix {{x,y,z,x^2*v,x*y*v,y^2*v,z*v,x*w,y^3*w,z*w}}     |
|                                                                  |
|o3 = | x y z vx2 vxy vy2 vz wx wy3 wz |                           |
|                                                                  |
|             1      10                                            |
|o3 : Matrix T  <-- T                                              |
+------------------------------------------------------------------+
|i4 : n = rank source m                                            |
|                                                                  |
|o4 = 10                                                           |
+------------------------------------------------------------------+
|i5 : R = k[u_1 .. u_n]                                            |
|                                                                  |
|o5 = R                                                            |
|                                                                  |
|o5 : PolynomialRing                                               |
+------------------------------------------------------------------+
|i6 : S = k[u_1 .. u_n,Degrees => degrees source m]                |
|                                                                  |
|o6 = S                                                            |
|                                                                  |
|o6 : PolynomialRing                                               |
+------------------------------------------------------------------+
|i7 : f = map(T,R,m)                                               |
|                                                                  |
|                             2            2               3       |
|o7 = map (T, R, {x, y, z, v*x , v*x*y, v*y , v*z, w*x, w*y , w*z})|
|                                                                  |
|o7 : RingMap T <-- R                                              |
+------------------------------------------------------------------+
|i8 : g = map(T,S,m)                                               |
|                                                                  |
|                             2            2               3       |
|o8 = map (T, S, {x, y, z, v*x , v*x*y, v*y , v*z, w*x, w*y , w*z})|
|                                                                  |
|o8 : RingMap T <-- S                                              |
+------------------------------------------------------------------+
|i9 : res ker f                                                    |
|                                                                  |
|      1      17      57      76      46      12      1            |
|o9 = R  <-- R   <-- R   <-- R   <-- R   <-- R   <-- R  <-- 0      |
|                                                                  |
|     0      1       2       3       4       5       6      7      |
|                                                                  |
|o9 : ChainComplex                                                 |
+------------------------------------------------------------------+
|i10 : res ker g                                                   |
|                                                                  |
|       1      14      35      35      15      2                   |
|o10 = S  <-- S   <-- S   <-- S   <-- S   <-- S  <-- 0             |
|                                                                  |
|      0      1       2       3       4       5      6             |
|                                                                  |
|o10 : ChainComplex                                                |
+------------------------------------------------------------------+
|i11 : isHomogeneous f                                             |
|                                                                  |
|o11 = false                                                       |
+------------------------------------------------------------------+
|i12 : isHomogeneous g                                             |
|                                                                  |
|o12 = true                                                        |
+------------------------------------------------------------------+
+--------------------------------------------------+
|i13 : R = ZZ/32003[a..d]/(a^2+b^2+c^2+d^2);       |
+--------------------------------------------------+
|i14 : M = coker vars R                            |
|                                                  |
|o14 = cokernel | a b c d |                        |
|                                                  |
|                             1                    |
|o14 : R-module, quotient of R                     |
+--------------------------------------------------+
|i15 : C = resolution(M, LengthLimit=>6)           |
|                                                  |
|       1      4      7      8      8      8      8|
|o15 = R  <-- R  <-- R  <-- R  <-- R  <-- R  <-- R |
|                                                  |
|      0      1      2      3      4      5      6 |
|                                                  |
|o15 : ChainComplex                                |
+--------------------------------------------------+

A manually constructed resolution can be installed as the resolution of a
module, bypassing the call to the engine when a resolution is requested, as
follows.

+-------------------------------------------------------------+
|i16 : A = QQ[x,y]                                            |
|                                                             |
|o16 = A                                                      |
|                                                             |
|o16 : PolynomialRing                                         |
+-------------------------------------------------------------+
|i17 : C = chainComplex(                                      |
|               map(A^1,A^{3:-2},{{x^2,x*y,y^2}}),            |
|               map(A^{3:-2},A^{2:-3},{{y,0},{ -x,y},{0,-x}}),|
|               map(A^{2:-3},0,0))                            |
|                                                             |
|       1      3      2                                       |
|o17 = A  <-- A  <-- A  <-- 0                                 |
|                                                             |
|      0      1      2      3                                 |
|                                                             |
|o17 : ChainComplex                                           |
+-------------------------------------------------------------+
|i18 : M = HH_0 C                                             |
|                                                             |
|o18 = cokernel | x2 xy y2 |                                  |
|                                                             |
|                             1                               |
|o18 : A-module, quotient of A                                |
+-------------------------------------------------------------+
|i19 : res M = C;                                             |
+-------------------------------------------------------------+
|i20 : res M                                                  |
|                                                             |
|       1      3      2                                       |
|o20 = A  <-- A  <-- A  <-- 0                                 |
|                                                             |
|      0      1      2      3                                 |
|                                                             |
|o20 : ChainComplex                                           |
+-------------------------------------------------------------+

For an overview of resolutions, in order of increasing detail, see:

  * Hilbert functions and free resolutions
  * free resolutions of modules
  * computing resolutions -- most detailed
Some useful related functions:
  * betti(GradedModule) -- display or modify a Betti diagram
  * status(Resolution) -- status of a resolution computation

Ways to use this method:
========================

  * resolution(Module) -- compute a free
    resolution of a module

return -- return from a function
********************************

Synopsis
========

  * Usage:
        return x
  * Inputs:
      * x, If x is omitted, then null, is used.
  * Consequences:
      * Returns x as the value of the function currently being evaluated.
      * Alternatively, as a debugger command, returns x as the value of the
        current expression and stops execution at the next possible point,
        entering the debugger again.

Description
===========

+-----------------------------------+
|i1 : f = x -> (                    |
|          if x == 3 then return;   |
|          if x > 3 then return x^2;|
|          5);                      |
+-----------------------------------+
|i2 : f 2                           |
|                                   |
|o2 = 5                             |
+-----------------------------------+
|i3 : f 3                           |
+-----------------------------------+
|i4 : f 4                           |
|                                   |
|o4 = 16                            |
+-----------------------------------+

Here is an example of the use of return, as a debugger command.

+-----------------------------------------------------------------------------+
|i5 : load "Macaulay2Doc/demo1.m2"                                            |
+-----------------------------------------------------------------------------+
|i6 : code g                                                                  |
|                                                                             |
|o6 = /usr/local/share/Macaulay2/Macaulay2Doc/                                |
|     demo1.m2:11:4-14:9: --source code:                                      |
|     g = y -> (                                                              |
|          c := f(y-1);                                                       |
|          d := f(y-2);                                                       |
|          c+d)                                                               |
+-----------------------------------------------------------------------------+
|i7 : g 2                                                                     |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|8:10-8:13: --source code:                                                    |
|     b := 1/x;                                                               |
|-----------------------------------------------------------------------------|
|error: division by zero                                                      |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
|ii8 : code f                                                                 |
|                                                                             |
|oo8 = /usr/local/share/Macaulay2/Macaulay2Doc/                               |
|      demo1.m2:6:5-9:9: --source code:                                       |
|      f := x -> (                                                            |
|           a := "hi there";                                                  |
|           b := 1/x;                                                         |
|           b+1)                                                              |
+-----------------------------------------------------------------------------+
|ii9 : return 1/11                                                            |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:9:6:(3):[2]: --stepping     |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:9:6:(3):[2]: --entering     |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|9:5-9:8: --source code:                                                      |
|     b+1)                                                                    |
|-----------------------------------------------------------------------------|
|limit reached                                                                |
|debugger (type help to see debugger commands)                                |
+-----------------------------------------------------------------------------+
|ii10 : continue                                                              |
|                                                                             |
|      34                                                                     |
|o10 = --                                                                     |
|      11                                                                     |
|                                                                             |
|o10 : QQ                                                                     |
+-----------------------------------------------------------------------------+

See also
========

  * break -- break from a loop

For the programmer
==================

The object return, is a keyword.

returnCode
**********

Description
===========

returnCode --  a key for a GroebnerBasis, under which is
stored the return code from the engine for the computation.

For the programmer
==================

The object returnCode, is a symbol.

reverse -- reverse a list, sequence, or string
**********************************************

Synopsis
========

  * Usage:
        reverse(L)
  * Inputs:
      * L, a basic list, or a string,
  * Outputs:
      * R, a basic list, or a string,
        containing the elements of L in reverse order

Description
===========

The output will be the same type as the input.

+----------------------------+
|i1 : reverse {5, 7, 2, 8}   |
|                            |
|o1 = {8, 2, 7, 5}           |
|                            |
|o1 : List                   |
+----------------------------+
|i2 : reverse (5, 7, 2, 8)   |
|                            |
|o2 = (8, 2, 7, 5)           |
|                            |
|o2 : Sequence               |
+----------------------------+
|i3 : reverse "Hello, world!"|
|                            |
|o3 = !dlrow ,olleH          |
+----------------------------+

See also
========

  * sort -- sort a list or columns of a matrix

Ways to use reverse:
====================

  * "reverse(BasicList)"
  * "reverse(String)"

For the programmer
==================

The object reverse, is a compiled function.

right -- right endpoint of an interval
**************************************

Synopsis
========

  * Usage:
        x = right I
  * Inputs:
      * I, a real interval,
  * Outputs:
      * x, a real number,

Description
===========

Returns the right endpoint of the input interval.

See also
========

  * left -- left endpoint of an interval
  * midpoint -- midpoint of an interval
  * diameter -- diameter of an interval

For the programmer
==================

The object right, is a compiled function.

right shift
***********

Synopsis
========

  * Usage:
        x >> j
        x >> I
  * Inputs:
      * x
      * j
      * I, a real interval,
  * Outputs:
      * the integer obtained from x by shifting its binary representation
        rightward j places
      * a real interval, an interval containing all shifts of the
        binary representations elements of I by j places rightward
+---------------------------+
|i1 : 256 >> 5              |
|                           |
|o1 = 8                     |
+---------------------------+
|i2 : 256. >> 555           |
|                           |
|o2 = 2.170662841294021e-165|
|                           |
|o2 : RR (of precision 53)  |
+---------------------------+

See also
========

  * left shift

Ring -- the class of all rings
******************************

Description
===========

Common ways to make a ring:
  * Ring / Ideal -- make a quotient ring
  * Ring Array -- the standard way to make a polynomial ring
  * GF -- make a finite field
Common functions for accessing the variables or elements in a ring:
  * use(Ring) -- install ring variables and ring
    operations
  * generators(Ring) -- the list of generators of
    a ring
  * numgens(Ring) -- number of generators of a
    polynomial ring
  * Ring _ ZZ -- get a ring variable by index
Common ways to get information about a ring:
  * char(Ring) -- computes the characteristic of the ring or field
  * coefficientRing(Ring) -- get the coefficient ring
  * dim(Ring) -- compute the Krull dimension
Common ways to use a ring:
  * Ring ^ ZZ -- make a free module
  * Ring ^ List -- make a free module
  * vars(Ring) -- row matrix of the variables

See also
========

  * rings

Types of ring:
==============

  * EngineRing -- the class of rings handled by the engine

Functions and methods returning a ring:
=======================================

  * ambient(GaloisField) -- corresponding
    quotient ring
  * "ambient(QuotientRing)" -- see ambient(Ring), --
    ambient polynomial ring
  * ambient(Ring) -- ambient polynomial ring
  * "associatedGradedRing(Ideal)" -- see associatedGradedRing (ReesAlgebra),
    -- The normal cone of a subscheme
  * "associatedGradedRing(Ideal,RingElement)" -- see
    associatedGradedRing (ReesAlgebra), -- The normal cone
    of a subscheme
  * "normalCone(Ideal)" -- see associatedGradedRing (ReesAlgebra),
    -- The normal cone of a subscheme
  * "normalCone(Ideal,RingElement)" -- see associatedGradedRing (ReesAlgebra),
    -- The normal cone of a subscheme
  * coefficientRing -- get the coefficient ring
  * integralClosure(Ring) (IntegralClosure), --
    compute the integral closure (normalization) of an affine domain
  * integralClosure(Ring,Ring) (IntegralClosure)
    -- compute the integral
    closure (normalization) of an affine reduced ring over a base ring
  * minimalPresentation(Ring) -- compute
    a minimal presentation of a quotient ring
  * "prune(Ring)" -- see minimalPresentation(Ring),
    -- compute a minimal presentation of a
    quotient ring
  * newRing -- make a copy of a ring, with some features
    changed
  * reesAlgebra (ReesAlgebra) -- Compute the defining ideal
    of the Rees Algebra
  * ring -- get the associated ring of an object
  * Ring AngleBarList (missing documentation)
  * ring(SheafMap) (missing documentation)
  * specialFiber (ReesAlgebra) -- Special fiber of a blowup
  * "symmetricAlgebra(Module)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "Ring ** Ring" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "Ring ^** ZZ" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "trim(QuotientRing)" -- see trim, -- minimize generators and
    relations
  * "trim(Ring)" -- see trim, -- minimize generators and relations

Methods that use a ring:
========================

  * "Ideal * Ring" -- see *, -- a binary operator, usually used for
    multiplication
  * "MonomialIdeal * Ring" -- see *, -- a binary operator, usually
    used for multiplication
  * "Ring * Ideal" -- see *, -- a binary operator, usually used for
    multiplication
  * "Ring * MonomialIdeal" -- see *, -- a binary operator, usually
    used for multiplication
  * "Ring * RingElement" -- see *, -- a binary operator, usually
    used for multiplication
  * "Ring * Vector" -- see *, -- a binary operator, usually used for
    multiplication
  * AffineVariety ** Ring (Varieties)
  * "associatedPrimes(Ring)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "baseRing(Ring)" -- see baseRing, -- produce the ring from
    which a ring was formed
  * "basis(InfiniteNumber,InfiniteNumber,Ring)" -- see basis, --
    basis or generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,List,Ring)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,ZZ,Ring)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,InfiniteNumber,Ring)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,List,Ring)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,Ring)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(List,ZZ,Ring)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(Ring)" -- see basis, -- basis or generating set of all
    or part of a ring, ideal or module
  * "basis(ZZ,InfiniteNumber,Ring)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(ZZ,List,Ring)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(ZZ,Ring)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(ZZ,ZZ,Ring)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "Ring ^ BettiTally" -- see BettiTally, -- the class of
    all Betti tallies
  * ChainComplex ** Ring -- a binary operator,
    usually used for tensor product or Cartesian product
  * chainComplex(Ring) -- make an empty chain
    complex over a ring
  * "char(Ring)" -- see char, -- computes the characteristic of the
    ring or field
  * "coefficientRing(Ring)" -- see coefficientRing, --
    get the coefficient ring
  * "conductor(Ring)" -- see conductor (IntegralClosure), --
    the conductor of a finite ring map
  * degree(Ring)
  * degreeGroup(Ring) (missing documentation)
  * "degreeLength(Ring)" -- see degreeLength, -- the length
    of the degree vector
  * degrees(Ring) -- degrees of generators
  * "degreesMonoid(Ring)" -- see degreesRing, -- the ring or
    monoid of degrees
  * "degreesRing(Ring)" -- see degreesRing, -- the ring or
    monoid of degrees
  * "diagonalMatrix(Ring,List)" -- see diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a
    list
  * diagonalMatrix(Ring,ZZ,ZZ,List)
    -- make a diagonal matrix from a
    list
  * dim(Ring) -- compute the Krull dimension
  * effCone(Ring) (missing documentation)
  * effGenerators(Ring) (missing documentation)
  * euler(Ring) (Varieties)
  * eulers(Ring) (Varieties)
  * "Ext(Ideal,Ring)" -- see Ext(Module,Module),
    -- total Ext module
  * "Ext(Module,Ring)" -- see Ext(Module,Module),
    -- total Ext module
  * Ext(Ring,Ideal) (missing documentation)
  * Ext(Ring,Module) (missing documentation)
  * Ext(Ring,Ring) (missing documentation)
  * "Ext^ZZ(Matrix,Ring)" -- see Ext^ZZ(Matrix,Module),
    -- map between Ext modules
  * "Ext^ZZ(Ideal,Ring)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * "Ext^ZZ(Module,Ring)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * Ext^ZZ(Ring,Ideal) (missing documentation)
  * Ext^ZZ(Ring,Matrix) (missing documentation)
  * Ext^ZZ(Ring,Module) (missing documentation)
  * Ext^ZZ(Ring,Ring) (missing documentation)
  * Fano(ZZ,Ideal,Ring) -- Fano scheme
  * "flattenRing(Ring)" -- see flattenRing, -- write a ring
    as a (quotient of a) polynomial ring
  * "frac(Ring)" -- see frac, -- construct a fraction field
  * genera(Ring) (Varieties)
  * generators(Ring) -- the list of generators of
    a ring
  * "genericMatrix(Ring,RingElement,ZZ,ZZ)" -- see genericMatrix,
    -- make a generic matrix of variables
  * "genericMatrix(Ring,ZZ,ZZ)" -- see genericMatrix, --
    make a generic matrix of variables
  * "genericSkewMatrix(Ring,RingElement,ZZ)" -- see genericSkewMatrix,
    -- make a generic skew symmetric matrix of variables
  * "genericSkewMatrix(Ring,ZZ)" -- see genericSkewMatrix,
    -- make a generic skew symmetric matrix of variables
  * "genericSymmetricMatrix(Ring,RingElement,ZZ)" -- see
    genericSymmetricMatrix, -- make a generic symmetric
    matrix
  * "genericSymmetricMatrix(Ring,ZZ)" -- see genericSymmetricMatrix,
    -- make a generic symmetric matrix
  * genus(Ring) (Varieties)
  * "GF(Ring)" -- see GF, -- make a finite field
  * "heft(Ring)" -- see heft, -- heft vector of ring or monoid
  * "hilbertFunction(List,Ring)" -- see hilbertFunction,
    -- the Hilbert function
  * "hilbertFunction(Ring)" -- see hilbertFunction, --
    the Hilbert function
  * "hilbertFunction(ZZ,Ring)" -- see hilbertFunction,
    -- the Hilbert function
  * hilbertPolynomial(Ring) -- compute the
    Hilbert polynomial of the ring
  * "Hom(Ideal,Ring)" -- see Hom, -- module of homomorphisms
  * "Hom(Module,Ring)" -- see Hom, -- module of homomorphisms
  * "Hom(Ring,Ideal)" -- see Hom, -- module of homomorphisms
  * "Hom(Ring,Module)" -- see Hom, -- module of homomorphisms
  * "Hom(Ring,Ring)" -- see Hom, -- module of homomorphisms
  * "icFracP(Ring)" -- see icFracP (IntegralClosure), -- compute
    the integral closure in prime characteristic
  * "icFractions(Ring)" -- see icFractions (IntegralClosure),
    -- fractions integral over an affine domain
  * "icMap(Ring)" -- see icMap (IntegralClosure), -- natural map
    from an affine domain into its integral closure
  * Ideal == Ring (missing documentation)
  * ideal(Ring) -- returns the defining ideal
  * IndexedVariable _ Ring -- get a ring
    variable by name
  * "isAffineRing(Ring)" -- see isAffineRing, -- whether
    something is an affine ring
  * "isCommutative(Ring)" -- see isCommutative, -- whether
    a ring is commutative
  * "isField(Ring)" -- see isField, -- whether something is a
    field
  * "isHomogeneous(Ring)" -- see isHomogeneous, -- whether
    something is homogeneous (graded)
  * isNormal(Ring) (IntegralClosure) -- determine if
    a reduced ring is normal
  * "isQuotientOf(Ring,QuotientRing)" -- see isQuotientOf(Ring,Ring),
    -- whether one ring is a quotient of another
  * isQuotientOf(Ring,Ring) -- whether
    one ring is a quotient of another
  * isQuotientOf(Type,Ring) -- whether
    one ring is a quotient of a ring of a given type
  * "isQuotientRing(Ring)" -- see isQuotientRing, --
    whether something is a quotient ring
  * "isRing(Ring)" -- see isRing, -- whether something is a ring
  * "isSkewCommutative(Ring)" -- see isSkewCommutative,
    -- whether a ring has skew commuting variables
  * "isStandardGradedPolynomialRing(Ring)" -- see
    isStandardGradedPolynomialRing (InverseSystems),
    -- Checks whether a ring is
    a polynomial ring over a field with variables of degree 1
  * isWeylAlgebra(Ring) (missing documentation)
  * jacobian(Ring) -- the Jacobian matrix of the
    polynomials defining a quotient ring
  * "Number ^ Ring" -- see lift, -- lift to another ring
  * "makeS2(Ring)" -- see makeS2 (IntegralClosure), -- compute the
    S2ification of a reduced ring
  * map(Ring,Matrix) -- make a ring map
  * map(Ring,Ring) -- make a ring map, using the
    names of the variables
  * map(Ring,Ring,List) -- make a ring map
  * map(Ring,Ring,Matrix) -- make a ring
    map
  * "map(Ring,Ring,RingMap)" -- see map(Ring,Ring,Matrix),
    -- make a ring map
  * Matrix ** Ring -- tensor product
  * "Ring ** Matrix" -- see Matrix ** Ring, -- tensor
    product
  * matrix(Ring,List) -- create a matrix from a
    doubly nested list of ring elements or matrices
  * "Ideal ** Ring" -- see Module ** Ring, -- tensor
    product
  * Module ** Ring -- tensor product
  * "Ring ** Ideal" -- see Module ** Ring, -- tensor
    product
  * "Ring ** Module" -- see Module ** Ring, -- tensor
    product
  * module(Ring) -- make or get a module
  * monoid(Ring) -- make or retrieve a monoid
  * MonoidElement _ Ring (missing documentation)
  * "multidegree(Ring)" -- see multidegree, -- multidegree
  * mutableIdentity(Ring,ZZ) -- make a
    mutable identity matrix
  * mutableMatrix(Ring,ZZ,ZZ) -- make
    a mutable matrix filled with zeroes
  * nefCone(Ring) (missing documentation)
  * nefGenerators(Ring) (missing documentation)
  * numgens(Ring) -- number of generators of a
    polynomial ring
  * "options(Ring)" -- see options(Monoid), -- get
    values used for optional arguments
  * "poincare(Ring)" -- see poincare, -- assemble degrees of a
    ring, module, or ideal into a polynomial
  * "precision(Ring)" -- see precision,
  * "primaryDecomposition(Ring)" -- see primaryDecomposition(Module) (PrimaryDecomposition),
    -- irredundant
    primary decomposition of a module
  * "Proj(Ring)" -- see Proj (Varieties), -- make a projective
    variety
  * "Number _ Ring" -- see promote, -- promote to another ring
  * "RingElement _ Ring" -- see promote, -- promote to another
    ring
  * "random(List,Ring)" -- see random(ZZ,Ring), --
    get a random homogeneous element from a graded ring
  * random(ZZ,Ring) -- get a random homogeneous
    element from a graded ring
  * Ring / Ideal -- make a quotient ring
  * "Ring / List" -- see Ring / Ideal, -- make a quotient
    ring
  * "Ring / Module" -- see Ring / Ideal, -- make a quotient
    ring
  * "Ring / RingElement" -- see Ring / Ideal, -- make a
    quotient ring
  * "Ring / Sequence" -- see Ring / Ideal, -- make a
    quotient ring
  * "Ring / ZZ" -- see Ring / Ideal, -- make a quotient
    ring
  * Ring == Ideal (missing documentation)
  * Ring == ZZ (missing documentation)
  * Ring ^ List -- make a free module
  * Ring ^ ZZ -- make a free module
  * Ring _ List -- make a monomial from a list of
    exponents
  * Ring _ ZZ -- get a ring variable by index
  * Ring _* (missing documentation)
  * Ring Array -- the standard way to make a polynomial ring
  * Ring List -- make a local polynomial ring
  * Ring Monoid -- make a polynomial ring
  * "setupLift(Function,Ring,Ring)" -- see setupLift, -- set
    up lift from one ring to another
  * "Ring ~" -- see sheaf(Ring) (Varieties), -- make a
    coherent sheaf of rings
  * sheaf(Ring) (Varieties) -- make a coherent sheaf of
    rings
  * sheaf(Variety,Ring) (Varieties) -- make a
    coherent sheaf of rings
  * "singularLocus(Ring)" -- see singularLocus, --
    singular locus
  * "Spec(Ring)" -- see Spec (Varieties), -- make an affine variety
  * String _ Ring -- get a ring variable by name
  * "substitute(Ideal,Ring)" -- see substitute, --
    substituting values for variables
  * "substitute(Matrix,Ring)" -- see substitute, --
    substituting values for variables
  * "substitute(Module,Ring)" -- see substitute, --
    substituting values for variables
  * "substitute(Number,Ring)" -- see substitute, --
    substituting values for variables
  * "substitute(RingElement,Ring)" -- see substitute, --
    substituting values for variables
  * "substitute(Vector,Ring)" -- see substitute, --
    substituting values for variables
  * Symbol _ Ring -- get a ring variable by name
  * "symmetricAlgebra(Nothing,Ring,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricAlgebra(Ring,Nothing,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricAlgebra(Ring,Ring,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "terms(Ring,RingElement)" -- see terms, -- provide a list of
    terms of a polynomial
  * toField(Ring) -- declare that a ring is a field
  * Tor_ZZ(Matrix,Ring) (missing documentation)
  * "Tor_ZZ(Ideal,Ring)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * "Tor_ZZ(Module,Ring)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * Tor_ZZ(Ring,Ideal) (missing documentation)
  * Tor_ZZ(Ring,Matrix) (missing documentation)
  * Tor_ZZ(Ring,Module) (missing documentation)
  * Tor_ZZ(Ring,Ring) (missing documentation)
  * "truncate(List,Ring)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * "truncate(ZZ,Ring)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * use(Ring) -- install ring variables and ring
    operations
  * variety(Ring) (Varieties) -- the variety
    previously associated to a given ring
  * vars(Ring) -- row matrix of the variables
  * ZZ == Ring (missing documentation)

Protected objects of class Ring:
================================

  * QQ -- the class of all rational numbers
  * ZZ -- the class of all integers

For the programmer
==================

The object Ring, is a type, with ancestor classes
Type < MutableHashTable <
HashTable < Thing.

ring -- get the associated ring of an object
********************************************

Synopsis
========

  * Usage:
        ring M
  * Inputs:
      * M, an object with a ring associated to it
  * Outputs:
      * a ring, associated to the input object

Description
===========

For example, ring elements, matrices, ideals, modules, chain complexes,
varieties, coherent sheaves, etc., all have a base ring naturally associated to
them.
+----------------------------------------+
|i1 : R = ZZ/101[x,y,z];                 |
+----------------------------------------+
|i2 : ring x                             |
|                                        |
|o2 = R                                  |
|                                        |
|o2 : PolynomialRing                     |
+----------------------------------------+
|i3 : M = matrix {{2*x, x+y},{y^3, z*y}};|
|                                        |
|             2      2                   |
|o3 : Matrix R  <-- R                    |
+----------------------------------------+
|i4 : ring M                             |
|                                        |
|o4 = R                                  |
|                                        |
|o4 : PolynomialRing                     |
+----------------------------------------+
|i5 : S = QQ[x,y,z];                     |
+----------------------------------------+
|i6 : ring x                             |
|                                        |
|o6 = S                                  |
|                                        |
|o6 : PolynomialRing                     |
+----------------------------------------+
|i7 : I = ideal (x*y, y*z);              |
|                                        |
|o7 : Ideal of S                         |
+----------------------------------------+
|i8 : ring I                             |
|                                        |
|o8 = S                                  |
|                                        |
|o8 : PolynomialRing                     |
+----------------------------------------+

See also
========

  * baseRings -- store the list of base rings of a ring
  * coefficientRing -- get the coefficient ring

Ways to use ring:
=================

  * "ring(CC)"
  * "ring(ChainComplex)"
  * "ring(ChainComplexMap)"
  * "ring(GradedModule)"
  * "ring(GradedModuleMap)"
  * "ring(GroebnerBasis)"
  * "ring(Ideal)"
  * "ring(Matrix)"
  * "ring(Module)"
  * "ring(MutableMatrix)"
  * "ring(Number)"
  * "ring(Resolution)"
  * "ring(RingElement)"
  * "ring(RR)"
  * "ring(RRi)"
  * "ring(Vector)"
  * ring(CoherentSheaf) (Varieties) -- the
    coordinate ring of the underlying variety
  * "ring(SheafOfRings)" -- see ring(CoherentSheaf) (Varieties),
    -- the coordinate ring of the
    underlying variety
  * "ring(SumOfTwists)" -- see ring(CoherentSheaf) (Varieties),
    -- the coordinate ring of the
    underlying variety
  * ring(Constant) (missing documentation)
  * ring(SheafMap) (missing documentation)
  * ring(Variety) (Varieties) -- coordinate ring of
    the variety

For the programmer
==================

The object ring, is a method function.

Ring / Ideal -- make a quotient ring
************************************

Synopsis
========

  * Operator: /,
  * Usage:
        S = R/I
  * Inputs:
      * R
      * I, an ideal, or element of Ror a list, or a
        sequence, of elements of R
  * Outputs:
      * S, the quotient ring R/I

Description
===========

If I is a ring element of R or ZZ, or a list or sequence of such elements, then
I is understood to be the ideal generated by these elements.  If I is a module,
then it must be a submodule of a free module of rank 1.
+-----------------------------+
|i1 : ZZ[x]/367236427846278621|
|                             |
|            ZZ[x]            |
|o1 = ------------------      |
|     367236427846278621      |
|                             |
|o1 : QuotientRing            |
+-----------------------------+
+----------------------------------------------------------------+
|i2 : A = QQ[u,v];                                               |
+----------------------------------------------------------------+
|i3 : I = ideal random(A^1, A^{-2,-2,-2})                        |
|                                                                |
|            9 2   1      9 2  1 2         3 2  3 2   3      7 2 |
|o3 = ideal (-u  + -u*v + -v , -u  + u*v + -v , -u  + -u*v + -v )|
|            2     2      4    2           4    2     4      4   |
|                                                                |
|o3 : Ideal of A                                                 |
+----------------------------------------------------------------+
|i4 : B = A/I;                                                   |
+----------------------------------------------------------------+
|i5 : use A;                                                     |
+----------------------------------------------------------------+
|i6 : C = A/(u^2-v^2,u*v);                                       |
+----------------------------------------------------------------+
+-----------------------------------------------------+
|i7 : D = GF(9,Variable=>a)[x,y]/(y^2 - x*(x-1)*(x-a))|
|                                                     |
|o7 = D                                               |
|                                                     |
|o7 : QuotientRing                                    |
+-----------------------------------------------------+
|i8 : ambient D                                       |
|                                                     |
|o8 = GF 9[x..y]                                      |
|                                                     |
|o8 : PolynomialRing                                  |
+-----------------------------------------------------+
The names of the variables are assigned values in the new quotient ring (by
automatically running use R) when the new ring is assigned to a global
variable.

Warning: quotient rings are bulky objects, because they contain a Gröbner basis
for their ideals, so only quotients of ZZ, are remembered forever.
Typically the ring created by R/I will be a brand new ring, and its elements
will be incompatible with the elements of previously created quotient rings for
the same ideal.
+----------------------+
|i9 : ZZ/2 === ZZ/(4,6)|
|                      |
|o9 = true             |
+----------------------+
|i10 : R = ZZ/101[t]   |
|                      |
|o10 = R               |
|                      |
|o10 : PolynomialRing  |
+----------------------+
|i11 : R/t === R/t     |
|                      |
|o11 = false           |
+----------------------+

Ways to use this method:
========================

  * Ring / Ideal -- make a quotient ring
  * "Ring / List"
  * "Ring / Module"
  * "Ring / RingElement"
  * "Ring / Sequence"
  * "Ring / ZZ"

Ring ^ List -- make a free module
*********************************

Synopsis
========

  * Operator: ^,
  * Usage:
        M = R^{i,j,k,...}
  * Inputs:
      * R
      * {i,j,k, ...}, a list, of integers or lists of integers
  * Outputs:
      * a module, , a free module over R whose generators have
        degrees -i, -j, -k, ...

Description
===========

+-----------------------------------------+
|i1 : R = QQ[a..d]                        |
|                                         |
|o1 = R                                   |
|                                         |
|o1 : PolynomialRing                      |
+-----------------------------------------+
|i2 : R^{-1}                              |
|                                         |
|      1                                  |
|o2 = R                                   |
|                                         |
|o2 : R-module, free, degrees {1}         |
+-----------------------------------------+
|i3 : R^{-1,2:-2,-3}                      |
|                                         |
|      4                                  |
|o3 = R                                   |
|                                         |
|o3 : R-module, free, degrees {1..2, 2..3}|
+-----------------------------------------+

If i, j, ... are lists of integers, then they represent multi-degrees, as in
graded and multigraded polynomial rings.
+-------------------------------------------------+
|i4 : R = QQ[x,y,z,Degrees=>{{1,0},{1,-1},{1,-2}}]|
|                                                 |
|o4 = R                                           |
|                                                 |
|o4 : PolynomialRing                              |
+-------------------------------------------------+
|i5 : R^{{1,2}}                                   |
|                                                 |
|      1                                          |
|o5 = R                                           |
|                                                 |
|o5 : R-module, free, degrees {{-1, -2}}          |
+-------------------------------------------------+

See also
========

  * degrees -- degrees of generators
  * free modules
  * graded and multigraded polynomial rings

Ways to use this method:
========================

  * Ring ^ List -- make a free module
  * "RingFamily ^ List"

Ring ^ ZZ -- make a free module
*******************************

Synopsis
========

  * Operator: ^,
  * Usage:
        R^n
  * Inputs:
      * R
      * n
  * Outputs:
      * a new free R-module of rank n.

Description
===========

The new free module has basis elements of degree zero.  To specify the degrees
explicitly, see Ring ^ List.
+----------------------------+
|i1 : R = ZZ[x,y,z]/(x^2-y*x)|
|                            |
|o1 = R                      |
|                            |
|o1 : QuotientRing           |
+----------------------------+
|i2 : F = R^4                |
|                            |
|      4                     |
|o2 = R                      |
|                            |
|o2 : R-module, free         |
+----------------------------+
|i3 : degrees F              |
|                            |
|o3 = {{0}, {0}, {0}, {0}}   |
|                            |
|o3 : List                   |
+----------------------------+

See also
========

  * degrees(Module) -- degrees of generators
  * Ring ^ List -- make a free module
  * graded and multigraded polynomial rings

Ways to use this method:
========================

  * Ring ^ ZZ -- make a free module
  * "RingFamily ^ ZZ"

Ring _ List -- make a monomial from a list of exponents
*******************************************************

Synopsis
========

  * Operator: _,
  * Usage:
        R_w
  * Inputs:
      * R
      * w, of integers
  * Outputs:
      * the monomial of the ring R obtained by using the integers in the list w
        as exponents of the variables.

Description
===========

+-------------------+
|i1 : R = ZZ[a..d]  |
|                   |
|o1 = R             |
|                   |
|o1 : PolynomialRing|
+-------------------+
|i2 : R_{3,1,5}     |
|                   |
|      3   5        |
|o2 = a b*c         |
|                   |
|o2 : R             |
+-------------------+
|i3 : R_{1,1,1,1}   |
|                   |
|o3 = a*b*c*d       |
|                   |
|o3 : R             |
+-------------------+
|i4 : S = R[x,y,z]  |
|                   |
|o4 = S             |
|                   |
|o4 : PolynomialRing|
+-------------------+
|i5 : S_{1,1,1}     |
|                   |
|o5 = x*y*z         |
|                   |
|o5 : S             |
+-------------------+
|i6 : S_{1,1,1,4}   |
|                   |
|      4            |
|o6 = a x*y*z       |
|                   |
|o6 : S             |
+-------------------+

Ways to use this method:
========================

  * Ring _ List -- make a monomial from a list of
    exponents

Ring _ ZZ -- get a ring variable by index
*****************************************

Synopsis
========

  * Operator: _,
  * Usage:
        R_i
  * Inputs:
      * R
      * i
  * Outputs:
      * a ring element, the i-th generator of the ring R

Description
===========

The indexing of generators is based on 0, so R_0 would be the first one, and so
on.
+-------------------+
|i1 : R = ZZ[a..d]  |
|                   |
|o1 = R             |
|                   |
|o1 : PolynomialRing|
+-------------------+
|i2 : R_2           |
|                   |
|o2 = c             |
|                   |
|o2 : R             |
+-------------------+

If the coefficient ring is a polynomial ring, then the numbering matches that
in the list returned by generators.
+--------------------------------------+
|i3 : S = R[x,y,z]                     |
|                                      |
|o3 = S                                |
|                                      |
|o3 : PolynomialRing                   |
+--------------------------------------+
|i4 : generators(S,CoefficientRing=>ZZ)|
|                                      |
|o4 = {x, y, z, a, b, c, d}            |
|                                      |
|o4 : List                             |
+--------------------------------------+
|i5 : S_2                              |
|                                      |
|o5 = z                                |
|                                      |
|o5 : S                                |
+--------------------------------------+
|i6 : S_6                              |
|                                      |
|o6 = d                                |
|                                      |
|o6 : S                                |
+--------------------------------------+

See also
========

  * generators -- provide matrix or list of generators
  * String _ Ring -- get a ring variable by name

Ways to use this method:
========================

  * Ring _ ZZ -- get a ring variable by index

Ring Array -- the standard way to make a polynomial ring
********************************************************

Synopsis
========

  * Operator: SPACE,

Description
===========

R[...] -- produces the monoid ring from a ring R and the ordered monoid
specified by [...].

This is the customary way to make a polynomial ring.

Optional arguments (placed inside the array):
  * DegreeGroup -- an optional argument
  * Variables -- an optional argument
  * DegreeLift -- an optional argument
  * VariableBaseName -- an optional argument
  * DegreeRank -- an optional argument
  * Weights -- assigning weights to the variables
  * Inverses -- an optional argument
  * Global -- monomial ordering
  * MonomialOrder -- monomial ordering
  * WeylAlgebra, --
    specify differential operators in the ring
  * Degrees -- an optional argument
  * Join -- an optional argument
  * MonomialSize -- an optional argument
  * Local -- an optional argument
  * Heft -- an optional argument
  * Constants -- an optional argument
  * SkewCommutative -- an optional argument
  * DegreeMap -- an optional argument

See also
========

  * polynomial rings

Ways to use this method:
========================

  * "InexactFieldFamily Array"
  * Ring Array -- the standard way to make a polynomial ring

Ring List -- make a local polynomial ring
*****************************************

Synopsis
========

  * Operator: SPACE,

Description
===========

R{...} -- produces the monoid ring from a ring R and the ordered monoid
specified by ..., together with the option Local => true.

Optional arguments (placed inside the list):
  * DegreeGroup -- an optional argument
  * Variables -- an optional argument
  * DegreeLift -- an optional argument
  * VariableBaseName -- an optional argument
  * DegreeRank -- an optional argument
  * Weights -- assigning weights to the variables
  * Inverses -- an optional argument
  * Global -- monomial ordering
  * MonomialOrder -- monomial ordering
  * WeylAlgebra, --
    specify differential operators in the ring
  * Degrees -- an optional argument
  * Join -- an optional argument
  * MonomialSize -- an optional argument
  * Local -- an optional argument
  * Heft -- an optional argument
  * Constants -- an optional argument
  * SkewCommutative -- an optional argument
  * DegreeMap -- an optional argument

See also
========

  * polynomial rings

Ways to use this method:
========================

  * "InexactFieldFamily List"
  * Ring List -- make a local polynomial ring

Ring Monoid -- make a polynomial ring
*************************************

Synopsis
========

  * Operator: SPACE,

Description
===========

R M -- produces the monoid ring from a ring R and an ordered monoid M.

See also
========

  * polynomial rings

Ways to use this method:
========================

  * "InexactFieldFamily Monoid"
  * Ring Monoid -- make a polynomial ring

RingElement -- the class of all ring elements handled by the engine
*******************************************************************

See also
========

  * engine

Functions and methods returning a ring element:
===============================================

  * "Number % GroebnerBasis" -- see %, -- a binary operator, usually
    used for remainder and reduction
  * "ZZ % MonomialIdeal" -- see %, -- a binary operator, usually used
    for remainder and reduction
  * "RingElement * RingElement" -- see *, -- a binary operator,
    usually used for multiplication
  * "RingElement + RingElement" -- see +, -- a unary or binary
    operator, usually used for addition
  * "- RingElement" -- see -, -- a unary or binary operator, usually
    used for negation or subtraction
  * "RingElement - RingElement" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "ZZ // MonomialIdeal" -- see //, -- a binary operator, usually
    used for quotient
  * coefficient -- coefficient of a monomial
  * "contract(Number,RingElement)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(RingElement,Number)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(RingElement,RingElement)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "determinant(Matrix)" -- see determinant, -- determinant
    of a matrix
  * diff(RingElement,RingElement),
    -- differentiation
  * discriminant(RingElement,RingElement) (Elimination)
  * ehrhart (Polyhedra) -- calculates the Ehrhart polynomial of
    a polytope
  * "gcd(RingElement,RingElement)" -- see gcd, -- greatest common
    divisor
  * "generator(Ideal)" -- see generator, -- provide a single
    generator
  * "generator(Module)" -- see generator, -- provide a single
    generator
  * "Ideal _ ZZ" -- see generators of ideals and modules,
  * "homogenize(RingElement,RingElement,List)" -- see homogenize,
    -- homogenize with respect to a variable
  * IndexedVariable _ Ring -- get a ring
    variable by name
  * "leadCoefficient(RingElement)" -- see leadCoefficient,
    -- the coefficient of the leading term
  * "leadMonomial(RingElement)" -- see leadMonomial, -- the
    leading monomial of a ring element
  * leadTerm(RingElement) -- get the greatest
    term
  * leadTerm(ZZ,RingElement) -- get the
    lead polynomials using part of the monomial order
  * "RingElement % GroebnerBasis" -- see Matrix % GroebnerBasis,
    -- calculate the normal form of ring elements and matrices
    using a (partially computed) Gröbner basis
  * "RingElement // MonomialIdeal" -- see Matrix // Matrix,
    -- factor a map through another
  * "RingElement // RingElement" -- see Matrix // Matrix,
    -- factor a map through another
  * Matrix _ Sequence -- get entry of matrix
  * "RingElement % MonomialIdeal" -- see methods for normal forms and remainder,
    -- normal form of ring
    elements and matrices
  * "RingElement % RingElement" -- see methods for normal forms and remainder,
    -- normal form of ring
    elements and matrices
  * MonoidElement _ Ring (missing documentation)
  * "part(InfiniteNumber,InfiniteNumber,RingElement)" -- see part,
    -- select terms of a polynomial by degree(s) or weight(s)
  * "part(InfiniteNumber,InfiniteNumber,VisibleList,RingElement)" -- see
    part, -- select terms of a polynomial by degree(s) or weight(s)
  * "part(InfiniteNumber,ZZ,RingElement)" -- see part, -- select
    terms of a polynomial by degree(s) or weight(s)
  * "part(InfiniteNumber,ZZ,VisibleList,RingElement)" -- see part,
    -- select terms of a polynomial by degree(s) or weight(s)
  * "part(List,RingElement)" -- see part, -- select terms of a
    polynomial by degree(s) or weight(s)
  * "part(Nothing,Nothing,RingElement)" -- see part, -- select
    terms of a polynomial by degree(s) or weight(s)
  * "part(Nothing,Nothing,VisibleList,RingElement)" -- see part, --
    select terms of a polynomial by degree(s) or weight(s)
  * "part(Nothing,ZZ,RingElement)" -- see part, -- select terms of
    a polynomial by degree(s) or weight(s)
  * "part(Nothing,ZZ,VisibleList,RingElement)" -- see part, --
    select terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,InfiniteNumber,RingElement)" -- see part, -- select
    terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,InfiniteNumber,VisibleList,RingElement)" -- see part,
    -- select terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,Nothing,RingElement)" -- see part, -- select terms of
    a polynomial by degree(s) or weight(s)
  * "part(ZZ,Nothing,VisibleList,RingElement)" -- see part, --
    select terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,RingElement)" -- see part, -- select terms of a
    polynomial by degree(s) or weight(s)
  * "part(ZZ,VisibleList,RingElement)" -- see part, -- select terms
    of a polynomial by degree(s) or weight(s)
  * "part(ZZ,ZZ,RingElement)" -- see part, -- select terms of a
    polynomial by degree(s) or weight(s)
  * "part(ZZ,ZZ,VisibleList,RingElement)" -- see part, -- select
    terms of a polynomial by degree(s) or weight(s)
  * poincare -- assemble degrees of a ring, module, or ideal
    into a polynomial
  * poincareN -- assemble degrees into polynomial
  * poly(String) (Classic) -- make a polynomial using
    classic Macaulay syntax
  * "RingElement _ Ring" -- see promote, -- promote to another
    ring
  * promote(IndexedVariable,type of RingElement) (missing documentation)
  * "pseudoRemainder(RingElement,RingElement)" -- see pseudoRemainder,
    -- compute the pseudo-remainder
  * random(ZZ,Ideal) -- get a random homogeneous
    element from a graded ideal
  * "random(List,Ring)" -- see random(ZZ,Ring), --
    get a random homogeneous element from a graded ring
  * random(ZZ,Ring) -- get a random homogeneous
    element from a graded ring
  * "resultant" -- see resultant(RingElement,RingElement,RingElement) (Elimination),
  * Ring _ List -- make a monomial from a list of
    exponents
  * Ring _ ZZ -- get a ring variable by index
  * RingElement / RingElement -- fraction
  * RingElement ^ ZZ -- power
  * RingMap RingElement -- apply a ring map
  * "someTerms(RingElement,ZZ,ZZ)" -- see someTerms, -- select
    some terms of a polynomial
  * String _ Ring -- get a ring variable by name
  * "substitute(Number,Ring)" -- see substitute, --
    substituting values for variables
  * "substitute(Number,RingFamily)" -- see substitute, --
    substituting values for variables
  * "substitute(RingElement,List)" -- see substitute, --
    substituting values for variables
  * "substitute(RingElement,Matrix)" -- see substitute, --
    substituting values for variables
  * "substitute(RingElement,Ring)" -- see substitute, --
    substituting values for variables
  * "substitute(RingElement,RingFamily)" -- see substitute,
    -- substituting values for variables
  * Symbol _ Ring -- get a ring variable by name
  * trace(Matrix) -- trace of a matrix

Methods that use a ring element:
================================

  * "Number % RingElement" -- see %, -- a binary operator, usually
    used for remainder and reduction
  * "RingElement % Number" -- see %, -- a binary operator, usually
    used for remainder and reduction
  * "Matrix * RingElement" -- see *, -- a binary operator, usually
    used for multiplication
  * "Ring * RingElement" -- see *, -- a binary operator, usually
    used for multiplication
  * "RingElement * ChainComplexMap" -- see *, -- a binary operator,
    usually used for multiplication
  * "RingElement * GradedModuleMap" -- see *, -- a binary operator,
    usually used for multiplication
  * "RingElement * Ideal" -- see *, -- a binary operator, usually
    used for multiplication
  * "RingElement * Matrix" -- see *, -- a binary operator, usually
    used for multiplication
  * "RingElement * Module" -- see *, -- a binary operator, usually
    used for multiplication
  * "RingElement * MonomialIdeal" -- see *, -- a binary operator,
    usually used for multiplication
  * "RingElement * MutableMatrix" -- see *, -- a binary operator,
    usually used for multiplication
  * "RingElement * Vector" -- see *, -- a binary operator, usually
    used for multiplication
  * "Vector * RingElement" -- see *, -- a binary operator, usually
    used for multiplication
  * "ChainComplexMap + RingElement" -- see +, -- a unary or binary
    operator, usually used for addition
  * "GradedModuleMap + RingElement" -- see +, -- a unary or binary
    operator, usually used for addition
  * "Ideal + RingElement" -- see +, -- a unary or binary operator,
    usually used for addition
  * "Matrix + RingElement" -- see +, -- a unary or binary operator,
    usually used for addition
  * "RingElement + ChainComplexMap" -- see +, -- a unary or binary
    operator, usually used for addition
  * "RingElement + GradedModuleMap" -- see +, -- a unary or binary
    operator, usually used for addition
  * "RingElement + Matrix" -- see +, -- a unary or binary operator,
    usually used for addition
  * + RingElement (missing documentation)
  * "ChainComplexMap - RingElement" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "GradedModuleMap - RingElement" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "Matrix - RingElement" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "RingElement - ChainComplexMap" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "RingElement - GradedModuleMap" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "RingElement - Matrix" -- see -, -- a unary or binary operator,
    usually used for negation or subtraction
  * "Number // RingElement" -- see //, -- a binary operator, usually
    used for quotient
  * "RingElement // Number" -- see //, -- a binary operator, usually
    used for quotient
  * "analyticSpread(Ideal,RingElement)" -- see analyticSpread (ReesAlgebra),
    -- Compute the analytic spread of a module or
    ideal
  * "analyticSpread(Module,RingElement)" -- see analyticSpread (ReesAlgebra),
    -- Compute the analytic spread of a module or
    ideal
  * "annihilator(RingElement)" -- see annihilator (Saturation),
    -- the annihilator ideal
  * "antipode(RingElement)" -- see antipode, -- antipode for
    skew commuting polynomial rings
  * asin(RingElement) (missing documentation)
  * "associatedGradedRing(Ideal,RingElement)" -- see
    associatedGradedRing (ReesAlgebra), -- The normal cone
    of a subscheme
  * "normalCone(Ideal,RingElement)" -- see associatedGradedRing (ReesAlgebra),
    -- The normal cone of a subscheme
  * atan(RingElement) (missing documentation)
  * "baseName(RingElement)" -- see baseName, -- the base name
    of a generator
  * "binomial(RingElement,ZZ)" -- see binomial, -- binomial
    coefficient
  * ChainComplexMap == RingElement (missing documentation)
  * "clean(RR,RingElement)" -- see clean, -- Set to zero elements
    that are approximately zero
  * "coefficients(RingElement)" -- see coefficients, --
    monomials and their coefficients
  * "cokernel(RingElement)" -- see cokernel, -- cokernel of a
    map of modules, graded modules, or chaincomplexes
  * "columnAdd(MutableMatrix,ZZ,RingElement,ZZ)" -- see columnAdd,
    -- add a multiple of one column to another
  * "columnMult(MutableMatrix,ZZ,RingElement)" -- see columnMult,
    -- multiply a column by a ring element
  * "Constant * RingElement" -- see Constant,
  * "Constant + RingElement" -- see Constant,
  * "Constant - RingElement" -- see Constant,
  * "Constant / RingElement" -- see Constant,
  * "RingElement * Constant" -- see Constant,
  * "RingElement + Constant" -- see Constant,
  * "RingElement - Constant" -- see Constant,
  * "RingElement / Constant" -- see Constant,
  * Constant == RingElement (missing documentation)
  * "content(RingElement)" -- see content, -- the content of a
    polynomial
  * "content(RingElement,RingElement)" -- see content, -- the
    content of a polynomial
  * "contract(Matrix,RingElement)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(RingElement,Matrix)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(RingElement,Vector)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Vector,RingElement)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * cos(RingElement) (missing documentation)
  * cosh(RingElement) (missing documentation)
  * degree(RingElement)
  * degree(RingElement,RingElement)
    -- degree with respect to a variable
  * "diff(RingElement,Vector)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * "diff(Vector,RingElement)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * diff(Matrix,RingElement), --
    differentiation
  * diff(RingElement,Matrix), --
    differentiate each entry of a matrix
  * "divideByVariable(Matrix,RingElement)" -- see divideByVariable,
    -- divide all columns by a (power of a) variable
  * "divideByVariable(Matrix,RingElement,ZZ)" -- see divideByVariable,
    -- divide all columns by a (power of a) variable
  * dual(MonomialIdeal,RingElement)
    -- the Alexander dual
  * "eliminate(RingElement,Ideal)" -- see eliminate (Elimination),
  * exp(RingElement)
  * expm1(RingElement) (missing documentation)
  * "exponents(RingElement)" -- see exponents, -- the
    exponents of a polynomial
  * factor(RingElement) -- factor a ring
    element
  * "fraction(RingElement,RingElement)" -- see fraction,
  * "fromDividedPowers(RingElement)" -- see fromDividedPowers (InverseSystems),
    -- Translates from divided power
    monomial basis to ordinary monomial basis
  * "fromDual(RingElement)" -- see fromDual (InverseSystems), --
    Ideal from inverse system
  * "gcd(RingElement,ZZ)" -- see gcd, -- greatest common divisor
  * "gcd(ZZ,RingElement)" -- see gcd, -- greatest common divisor
  * "gcdCoefficients(RingElement,RingElement)" -- see gcdCoefficients,
    -- gcd with coefficients
  * "genericMatrix(Ring,RingElement,ZZ,ZZ)" -- see genericMatrix,
    -- make a generic matrix of variables
  * "genericSkewMatrix(Ring,RingElement,ZZ)" -- see genericSkewMatrix,
    -- make a generic skew symmetric matrix of variables
  * "genericSymmetricMatrix(Ring,RingElement,ZZ)" -- see
    genericSymmetricMatrix, -- make a generic symmetric
    matrix
  * GradedModuleMap == RingElement (missing documentation)
  * "homogenize(Ideal,RingElement)" -- see homogenize, --
    homogenize with respect to a variable
  * "homogenize(Matrix,RingElement)" -- see homogenize, --
    homogenize with respect to a variable
  * "homogenize(Matrix,RingElement,List)" -- see homogenize,
    -- homogenize with respect to a variable
  * "homogenize(Module,RingElement)" -- see homogenize, --
    homogenize with respect to a variable
  * "homogenize(Module,RingElement,List)" -- see homogenize,
    -- homogenize with respect to a variable
  * "homogenize(RingElement,RingElement)" -- see homogenize,
    -- homogenize with respect to a variable
  * "homogenize(Vector,RingElement)" -- see homogenize, --
    homogenize with respect to a variable
  * "homogenize(Vector,RingElement,List)" -- see homogenize,
    -- homogenize with respect to a variable
  * "icPIdeal(RingElement,RingElement,ZZ)" -- see icPIdeal (IntegralClosure),
    -- compute the integral closure in prime
    characteristic of a principal ideal
  * Ideal * RingElement (missing documentation)
  * ideal(RingElement) -- make an ideal
  * "idealizer(Ideal,RingElement)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * "image(RingElement)" -- see image, -- image of a map
  * "index(RingElement)" -- see index, -- numeric index of a ring
    variable
  * indices(RingElement) -- indices of
    variables occurring in a polynomial
  * InexactNumber % RingElement (missing documentation)
  * InexactNumber * RingElement (missing documentation)
  * InexactNumber + RingElement (missing documentation)
  * InexactNumber - RingElement (missing documentation)
  * InexactNumber / RingElement (missing documentation)
  * InexactNumber // RingElement (missing documentation)
  * InexactNumber == RingElement (missing documentation)
  * installHilbertFunction(Ideal,RingElement) (missing documentation)
  * installHilbertFunction(Matrix,RingElement) (missing documentation)
  * installHilbertFunction(Module,RingElement) (missing documentation)
  * "integralClosure(Ideal,RingElement)" -- see
    integralClosure(Ideal,RingElement,ZZ) (IntegralClosure),
    -- integral
    closure of an ideal in an affine domain
  * integralClosure(Ideal,RingElement,ZZ) (IntegralClosure)
    -- integral
    closure of an ideal in an affine domain
  * "inverseSystem(RingElement)" -- see inverseSystem (InverseSystems),
    -- Inverse systems with equivariance
  * "isConstant(RingElement)" -- see isConstant, -- whether a
    ring element is constant
  * "isHomogeneous(RingElement)" -- see isHomogeneous, --
    whether something is homogeneous (graded)
  * "isLinearType(Ideal,RingElement)" -- see isLinearType (ReesAlgebra),
    -- Determine whether module has linear type
  * "isLinearType(Module,RingElement)" -- see isLinearType (ReesAlgebra),
    -- Determine whether module has linear type
  * isMember(RingElement,Ideal), --
    test membership in an ideal
  * isNormal(RingElement) (missing documentation)
  * isPrime(RingElement) (missing documentation)
  * "isReduction(Ideal,Ideal,RingElement)" -- see isReduction (ReesAlgebra),
    -- Determine whether an ideal is a reduction
  * "isReduction(Module,Module,RingElement)" -- see isReduction (ReesAlgebra),
    -- Determine whether an ideal is a reduction
  * "isUnit(RingElement)" -- see isUnit, -- whether a ring
    element is a unit
  * jacobian(RingElement) (missing documentation)
  * "kernel(RingElement)" -- see kernel(Matrix), --
    kernel of a matrix
  * "lcm(RingElement,RingElement)" -- see lcm, -- least common
    multiple
  * "lcm(RingElement,ZZ)" -- see lcm, -- least common multiple
  * "lcm(ZZ,RingElement)" -- see lcm, -- least common multiple
  * "lift(Ideal,type of RingElement)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of RingElement)" -- see lift, -- lift to
    another ring
  * lift(Module,type of RingElement) (missing documentation)
  * lift(MutableMatrix,type of RingElement) (missing documentation)
  * lift(RingElement,type of MonoidElement) (missing documentation)
  * lift(Vector,type of RingElement) (missing documentation)
  * List % RingElement (missing documentation)
  * List / RingElement -- vector division
  * List // RingElement (missing documentation)
  * "listForm(RingElement)" -- see listForm, -- convert to list
    form
  * log1p(RingElement) (missing documentation)
  * map(Module,Module,RingElement)
    -- construct the map induced by
    multiplication by a ring element on the generators
  * Matrix ** RingElement -- a binary
    operator, usually used for tensor product or Cartesian product
  * "Matrix ++ RingElement" -- see Matrix ++ Matrix, --
    direct sum of maps
  * "RingElement ++ Matrix" -- see Matrix ++ Matrix, --
    direct sum of maps
  * "RingElement ++ RingElement" -- see Matrix ++ Matrix,
    -- direct sum of maps
  * "Matrix / RingElement" -- see Matrix / Number, --
    scalar division
  * "Vector / RingElement" -- see Matrix / Number, --
    scalar division
  * "Matrix // RingElement" -- see Matrix // Matrix, --
    factor a map through another
  * "RingElement // GroebnerBasis" -- see Matrix // Matrix,
    -- factor a map through another
  * "RingElement // Matrix" -- see Matrix // Matrix, --
    factor a map through another
  * Matrix == RingElement (missing documentation)
  * Matrix \\ RingElement (missing documentation)
  * "Matrix | RingElement" -- see Matrix | Matrix, --
    join matrices horizontally
  * "RingElement | Matrix" -- see Matrix | Matrix, --
    join matrices horizontally
  * "RingElement | RingElement" -- see Matrix | Matrix,
    -- join matrices horizontally
  * "Matrix || RingElement" -- see Matrix || Matrix, --
    join matrices vertically
  * "RingElement || Matrix" -- see Matrix || Matrix, --
    join matrices vertically
  * "RingElement || RingElement" -- see Matrix || Matrix,
    -- join matrices vertically
  * matrix(RingElement) -- make a matrix from a
    ring element
  * "Matrix % RingElement" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "RingElement % Ideal" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * "RingElement % Matrix" -- see methods for normal forms and remainder,
    -- normal form of ring elements and
    matrices
  * Module * RingElement (missing documentation)
  * "Module / RingElement" -- see Module / Module, --
    quotient module
  * "monomialIdeal(RingElement)" -- see monomialIdeal(Matrix),
    -- monomial ideal of lead monomials
  * "monomials(RingElement)" -- see monomials, -- matrix of
    monomials in a ring element or matrix
  * "multiplicity(Ideal,RingElement)" -- see multiplicity (ReesAlgebra),
    -- Compute the Hilbert-Samuel multiplicity of an
    ideal
  * MutableMatrix * RingElement (missing documentation)
  * "newtonPolytope(RingElement)" -- see newtonPolytope (Polyhedra),
    -- computes the Newton polytope of a polynomial
  * "norm(InfiniteNumber,RingElement)" -- see norm,
  * "norm(RingElement)" -- see norm,
  * "norm(RR,RingElement)" -- see norm,
  * Number == RingElement (missing documentation)
  * "parts(RingElement)" -- see parts, -- display terms of a
    polynomial degree by degree
  * "precision(RingElement)" -- see precision,
  * promote(Constant,type of RingElement) (missing documentation)
  * "Ideal : RingElement" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "Module : RingElement" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "MonomialIdeal : RingElement" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotient(Ideal,RingElement)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotient(Module,RingElement)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotient(MonomialIdeal,RingElement)" -- see quotient(Module,Module) (Saturation),
    -- ideal or submodule quotient
  * "quotientRemainder(InexactNumber,RingElement)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder
  * "quotientRemainder(Number,RingElement)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder
  * "quotientRemainder(RingElement,InexactNumber)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder
  * "quotientRemainder(RingElement,Number)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder
  * quotientRemainder(RingElement,RingElement)
    -- quotient and remainder
  * "radicalContainment(RingElement,Ideal)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * "reesAlgebra(Ideal,RingElement)" -- see reesAlgebra (ReesAlgebra),
    -- Compute the defining ideal of the Rees Algebra
  * "reesAlgebra(Module,RingElement)" -- see reesAlgebra (ReesAlgebra),
    -- Compute the defining ideal of the Rees Algebra
  * "reesIdeal(Ideal,RingElement)" -- see reesIdeal (ReesAlgebra),
    -- Compute the defining ideal of the Rees Algebra
  * "reesIdeal(Module,RingElement)" -- see reesIdeal (ReesAlgebra),
    -- Compute the defining ideal of the Rees Algebra
  * resultant(RingElement,RingElement,RingElement) (Elimination)
  * "ring(RingElement)" -- see ring, -- get the associated ring of
    an object
  * "Ring / RingElement" -- see Ring / Ideal, -- make a
    quotient ring
  * RingElement % InexactNumber (missing documentation)
  * RingElement * InexactNumber (missing documentation)
  * RingElement * Tally (missing documentation)
  * RingElement * VirtualTally (missing documentation)
  * RingElement + Ideal (missing documentation)
  * RingElement + InexactNumber (missing documentation)
  * RingElement - InexactNumber (missing documentation)
  * RingElement .. RingElement -- a
    sequence of consecutive generators of a polynomial ring
  * RingElement .. Thing (missing documentation)
  * RingElement ..< RingElement -- a
    sequence of consecutive generators of a polynomial ring
  * RingElement ..< Thing (missing documentation)
  * RingElement / InexactNumber (missing documentation)
  * RingElement // InexactNumber (missing documentation)
  * RingElement == ChainComplexMap (missing documentation)
  * RingElement == Constant (missing documentation)
  * RingElement == GradedModuleMap (missing documentation)
  * RingElement == InexactNumber (missing documentation)
  * RingElement == Matrix (missing documentation)
  * RingElement == Number (missing documentation)
  * RingElement == RingElement (missing documentation)
  * RingElement == ZZ (missing documentation)
  * RingElement \\ Matrix (missing documentation)
  * RingElement _ Monoid (missing documentation)
  * RingElement _ Thing (missing documentation)
  * "RingElement Number" -- see RingElement Sequence,
    -- evaluation of polynomials
  * "RingElement RingElement" -- see RingElement Sequence,
    -- evaluation of polynomials
  * RingElement Sequence -- evaluation of
    polynomials
  * "ringFromFractions(Matrix,RingElement)" -- see ringFromFractions (IntegralClosure),
    -- find presentation for f.g. ring
  * roots(RingElement) -- compute the roots of a
    polynomial
  * "rowAdd(MutableMatrix,ZZ,RingElement,ZZ)" -- see rowAdd, --
    add a multiple of one row to another
  * "rowMult(MutableMatrix,ZZ,RingElement)" -- see rowMult, --
    multiply a row by a ring element
  * "saturate(Ideal,RingElement)" -- see saturate (Saturation),
    -- saturation of ideal or submodule
  * "saturate(Module,RingElement)" -- see saturate (Saturation),
    -- saturation of ideal or submodule
  * "saturate(MonomialIdeal,RingElement)" -- see saturate (Saturation),
    -- saturation of ideal or submodule
  * "saturate(Vector,RingElement)" -- see saturate (Saturation),
    -- saturation of ideal or submodule
  * sec(RingElement) (missing documentation)
  * sech(RingElement) (missing documentation)
  * sin(RingElement) (missing documentation)
  * sinh(RingElement) (missing documentation)
  * "size(RingElement)" -- see size, -- the size of an object
  * "specialFiber(Ideal,RingElement)" -- see specialFiber (ReesAlgebra),
    -- Special fiber of a blowup
  * "specialFiber(Module,RingElement)" -- see specialFiber (ReesAlgebra),
    -- Special fiber of a blowup
  * "specialFiberIdeal(Ideal,RingElement)" -- see specialFiberIdeal (ReesAlgebra),
    -- Special fiber of a blowup
  * "specialFiberIdeal(Module,RingElement)" -- see specialFiberIdeal (ReesAlgebra),
    -- Special fiber of a blowup
  * "standardForm(RingElement)" -- see standardForm, --
    convert to standard form
  * "substitute(RingElement,Option)" -- see substitute, --
    substituting values for variables
  * "support(RingElement)" -- see support, -- list of variables
    occurring in a polynomial or matrix
  * sylvesterMatrix(RingElement,RingElement,RingElement) (Elimination)
  * tan(RingElement) (missing documentation)
  * tanh(RingElement) (missing documentation)
  * "terms(Ring,RingElement)" -- see terms, -- provide a list of
    terms of a polynomial
  * "terms(RingElement)" -- see terms, -- provide a list of terms
    of a polynomial
  * "testHunekeQuestion(RingElement)" -- see testHunekeQuestion (IntegralClosure),
    -- tests a conjecture on integral
    closures strengthening the Eisenbud-Mazur conjecture
  * Thing .. RingElement (missing documentation)
  * Thing ..< RingElement (missing documentation)
  * "toDividedPowers(RingElement)" -- see toDividedPowers (InverseSystems),
    -- Translates to divided power monomial
    basis from ordinary monomial basis
  * "topCoefficients(RingElement)" -- see topCoefficients,
    -- first variable and its coefficient of a polynomial or
    matrix
  * "vector(Module,RingElement)" -- see vector, -- make a vector
  * "vector(RingElement)" -- see vector, -- make a vector
  * "weightRange(List,RingElement)" -- see weightRange, --
    the pair of lowest and highest weights of the monomials
  * "weightRange(RingElement)" -- see weightRange, -- the
    pair of lowest and highest weights of the monomials
  * ZZ == RingElement (missing documentation)

For the programmer
==================

The object RingElement, is a type, with
ancestor classes BasicList, < Thing.

RingElement .. RingElement -- a sequence of consecutive generators of a polynomial ring
***************************************************************************************

Synopsis
========

  * Operator: ..,
  * Usage:
        s .. t
  * Inputs:
      * s
      * t
  * Outputs:
      * the sequence of consecutive generators of a polynomial ring, from s to
        t, inclusive

Description
===========

+----------------------------------+
|i1 : R = QQ[a..z]                 |
|                                  |
|o1 = R                            |
|                                  |
|o1 : PolynomialRing               |
+----------------------------------+
|i2 : b .. i                       |
|                                  |
|o2 = (b, c, d, e, f, g, h, i)     |
|                                  |
|o2 : Sequence                     |
+----------------------------------+
|i3 : plus oo                      |
|                                  |
|o3 = b + c + d + e + f + g + h + i|
|                                  |
|o3 : R                            |
+----------------------------------+

Warning: former behavior involved making the names of the generators
consecutive, so the results in the next example differ from those given before.

+--------------------------------+
|i4 : R = QQ[e,d,c,b,a,X_1,y,X_2]|
|                                |
|o4 = R                          |
|                                |
|o4 : PolynomialRing             |
+--------------------------------+
|i5 : e .. a                     |
|                                |
|o5 = ()                         |
|                                |
|o5 : Sequence                   |
+--------------------------------+
|i6 : X_1 .. X_2                 |
|                                |
|o6 = (X , X )                   |
|       1   2                    |
|                                |
|o6 : Sequence                   |
+--------------------------------+

Warning: since former behavior involved only the names of the generators, there
was no requirement that s and t be in the same ring, whereas now there is.

Ways to use this method:
========================

  * RingElement .. RingElement -- a
    sequence of consecutive generators of a polynomial ring

RingElement ..< RingElement -- a sequence of consecutive generators of a polynomial ring
****************************************************************************************

Synopsis
========

  * Operator: ..<,
  * Usage:
        s ..< t
  * Inputs:
      * s
      * t
  * Outputs:
      * the sequence of consecutive generators of a polynomial ring, from s to
        t, not including the endpoint

Description
===========

+------------------------------+
|i1 : R = QQ[a..z]             |
|                              |
|o1 = R                        |
|                              |
|o1 : PolynomialRing           |
+------------------------------+
|i2 : b ..< i                  |
|                              |
|o2 = (b, c, d, e, f, g, h)    |
|                              |
|o2 : Sequence                 |
+------------------------------+
|i3 : plus oo                  |
|                              |
|o3 = b + c + d + e + f + g + h|
|                              |
|o3 : R                        |
+------------------------------+

Ways to use this method:
========================

  * RingElement ..< RingElement -- a
    sequence of consecutive generators of a polynomial ring

RingElement / RingElement -- fraction
*************************************

Synopsis
========

  * Operator: /,
  * Usage:
        f/g
  * Inputs:
      * f
      * g
  * Outputs:
      * a ring element, the fraction f/g

Description
===========

If either f or g is in a base ring of the other, then that one is promoted so
that both are elements in the same ring R.

The fraction will be an element of the fraction field, frac R, of R. If R is
already a field, then this means that the fraction will be an element of R.
+--------+
|i1 : 4/2|
|        |
|o1 = 2  |
|        |
|o1 : QQ |
+--------+
+---------------------------+
|i2 : R = GF(9,Variable=>a);|
+---------------------------+
|i3 : (a/a^3) * a^2 == 1    |
|                           |
|o3 = true                  |
+---------------------------+
+------------------------+
|i4 : S = ZZ[a,b]        |
|                        |
|o4 = S                  |
|                        |
|o4 : PolynomialRing     |
+------------------------+
|i5 : (a^6-b^6)/(a^9-b^9)|
|                        |
|          3    3        |
|         a  + b         |
|o5 = --------------     |
|      6    3 3    6     |
|     a  + a b  + b      |
|                        |
|o5 : frac S             |
+------------------------+
If the ring contains zero divisors, the fraction field is not defined.
Macaulay2 will not inform you of this right away.  However, if computation
finds a zero-divisor, an error message is generated.
+--------------------------+
|i6 : A = ZZ/101[a,b]/(a*b)|
|                          |
|o6 = A                    |
|                          |
|o6 : QuotientRing         |
+--------------------------+
|i7 : (a+b)/(a-b)          |
|                          |
|     -b                   |
|o7 = --                   |
|      b                   |
|                          |
|o7 : frac A               |
+--------------------------+
At this point, if one types a/b, then Macaulay2 would give an error saying that
a zero divisor was found in the denominator.

See also
========

  * // -- a binary operator, usually used for quotient

Ways to use this method:
========================

  * RingElement / RingElement -- fraction

RingElement ^ ZZ -- power
*************************

Synopsis
========

  * Operator: ^,
  * Usage:
        f^n
  * Inputs:
      * f
      * n
  * Outputs:
      * a ring element, f^n

Description
===========

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/7[x]/(x^46-x-1);                                                 |
+-----------------------------------------------------------------------------+
|i2 : (x+4)^(7^100)                                                           |
|                                                                             |
|        45    43    42     41     38     37     36     35    34     33     32|
|o2 = - x   - x   - x   + 3x   + 3x   - 2x   + 2x   + 3x   + x   - 3x   + 3x  |
|     ------------------------------------------------------------------------|
|         31     30    29    28    27     26     25    23     22    21     20 |
|     - 2x   + 2x   + x   - x   + x   - 3x   + 2x   + x   + 3x   - x   - 2x   |
|     ------------------------------------------------------------------------|
|         19    18     17     16     15     14    13     12     11    10     9|
|     - 2x   - x   + 3x   - 3x   - 3x   + 2x   + x   + 2x   - 3x   - x   - 3x |
|     ------------------------------------------------------------------------|
|         8     7     6     5    4     2                                      |
|     - 2x  + 3x  - 2x  + 3x  - x  + 2x  - 3x + 3                             |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+

If the ring allows inverses, negative values may be used.
+----------------------------------------------------+
|i3 : S = ZZ[t,Inverses=>true,MonomialOrder=>RevLex];|
+----------------------------------------------------+
|i4 : t^-1                                           |
|                                                    |
|      -1                                            |
|o4 = t                                              |
|                                                    |
|o4 : S                                              |
+----------------------------------------------------+
|i5 : T = frac(ZZ[a,b,c]);                           |
+----------------------------------------------------+
|i6 : (a+b+c)^-1                                     |
|                                                    |
|         1                                          |
|o6 = ---------                                      |
|     a + b + c                                      |
|                                                    |
|o6 : T                                              |
+----------------------------------------------------+

See also
========

  * frac -- construct a fraction field
  * polynomial rings

Ways to use this method:
========================

  * RingElement ^ ZZ -- power

RingFamily
**********

Description
===========

This family is used to contain classes that correspond to a family of similar
rings with a default member.

Types of RingFamily:
====================

  * InexactFieldFamily -- the class of all families
    of inexact fields

Methods that use an object of class RingFamily:
===============================================

  * Constant ^ RingFamily (missing documentation)
  * "diagonalMatrix(RingFamily,List)" -- see
    diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a list
  * "diagonalMatrix(RingFamily,ZZ,ZZ,List)" -- see
    diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a list
  * "Number ^ RingFamily" -- see lift, -- lift to another ring
  * "matrix(RingFamily,List)" -- see matrix(Ring,List),
    -- create a matrix from a doubly nested list of
    ring elements or matrices
  * "mutableIdentity(RingFamily,ZZ)" -- see mutableIdentity(Ring,ZZ),
    -- make a mutable identity matrix
  * "mutableMatrix(RingFamily,ZZ,ZZ)" -- see mutableMatrix(Ring,ZZ,ZZ),
    -- make a mutable matrix filled with
    zeroes
  * "RingFamily ^ List" -- see Ring ^ List, -- make a free
    module
  * "RingFamily ^ ZZ" -- see Ring ^ ZZ, -- make a free module
  * RingFamily _* -- a unary postfix operator, used
    for indicating pushforward maps
  * "substitute(Ideal,RingFamily)" -- see substitute, --
    substituting values for variables
  * "substitute(Matrix,RingFamily)" -- see substitute, --
    substituting values for variables
  * "substitute(Module,RingFamily)" -- see substitute, --
    substituting values for variables
  * "substitute(Number,RingFamily)" -- see substitute, --
    substituting values for variables
  * "substitute(RingElement,RingFamily)" -- see substitute,
    -- substituting values for variables
  * "substitute(Vector,RingFamily)" -- see substitute, --
    substituting values for variables

For the programmer
==================

The object RingFamily, is a type, with ancestor
classes Type, < MutableHashTable <
HashTable < Thing.

RingFamily _* -- a unary postfix operator, used for indicating pushforward maps
*******************************************************************************

Synopsis
========

  * Operator: _*,
  * Usage:
        R_*
  * Inputs:
      * R
  * Outputs:
      * the common parent for the rings in the family R

Description
===========

+-------------------------+
|i1 : 4.                  |
|                         |
|o1 = 4                   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+
|i2 : ring 4.             |
|                         |
|o2 = RR                  |
|       53                |
|                         |
|o2 : RealField           |
+-------------------------+
|i3 : parent ring 4.      |
|                         |
|o3 = RR                  |
|       *                 |
|                         |
|o3 : Type                |
+-------------------------+
|i4 : RR_*                |
|                         |
|o4 = RR                  |
|       *                 |
|                         |
|o4 : Type                |
+-------------------------+

Ways to use this method:
========================

  * RingFamily _* -- a unary postfix operator, used
    for indicating pushforward maps

RingMap -- the class of all ring maps
*************************************

Description
===========

For an overview of ring maps, substitution of variables, and finding implicit
equations of a set of polynomial or rational functions, see substitution and maps between rings.

A ring map $F : R \rightarrow{} S$, where $R$ is a polynomial ring, is
specified by giving the images in $S$ of the variables of $R$.  For a simple
example, consider the following map.  Notice that, as is usual in Macaulay2,
the target ring is given before the source.
+-----------------------------------------+
|i1 : R = QQ[a,b,c]; S = QQ[s,t];         |
+-----------------------------------------+
|i3 : F = map(S,R,{s^3-t^2, s^3-t, s-t})  |
|                                         |
|                  3    2   3             |
|o3 = map (S, R, {s  - t , s  - t, s - t})|
|                                         |
|o3 : RingMap S <-- R                     |
+-----------------------------------------+
|i4 : target F                            |
|                                         |
|o4 = S                                   |
|                                         |
|o4 : PolynomialRing                      |
+-----------------------------------------+
|i5 : source F                            |
|                                         |
|o5 = R                                   |
|                                         |
|o5 : PolynomialRing                      |
+-----------------------------------------+
|i6 : F.matrix                            |
|                                         |
|o6 = | s3-t2 s3-t s-t |                  |
|                                         |
|             1      3                    |
|o6 : Matrix S  <-- S                     |
+-----------------------------------------+
There are other ways to define ring maps.  See below.

Apply matrices to ring elements, vectors, matrices, and ideals using usual
function notation.
+-----------------+
|i7 : F (a+b)     |
|                 |
|       3    2    |
|o7 = 2s  - t  - t|
|                 |
|o7 : S           |
+-----------------+
The kernel of such ring maps are constructed with the aid of Gröbner bases.
Preimages of ideals are constructed using the same method.
+-----------------------------------------------------------------------------+
|i8 : I = kernel F                                                            |
|                                                                             |
|            6       4       4     5     2 2         2     2 2       3       3|
|o8 = ideal(c  + 3a*c  - 3b*c  + 3c  + 3a c  - 6a*b*c  + 3b c  + 6a*c  - 8b*c |
|     ------------------------------------------------------------------------|
|         4    3     2        2    3     2      2        2     2              |
|     + 3c  + a  - 3a b + 3a*b  - b  + 3a c - 3b c - 3a*c  + 2a  - a*b - 3a*c)|
|                                                                             |
|o8 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i9 : F I                                                                     |
|                                                                             |
|o9 = ideal 0                                                                 |
|                                                                             |
|o9 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i10 : J = preimage(F, ideal(s-3))                                            |
|                                                                             |
|                          2                                                  |
|o10 = ideal (b - c - 24, c  + a - 6c - 18)                                   |
|                                                                             |
|o10 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i11 : isSubset(F J, ideal(s-3))                                              |
|                                                                             |
|o11 = true                                                                   |
+-----------------------------------------------------------------------------+
Geometrically, the inverse image of this line is a conic.

Consider the Cremona transform, and its square:
+-----------------------------------------+
|i12 : G = map(R,R,{a=>b*c,b=>a*c,c=>a*b})|
|                                         |
|o12 = map (R, R, {b*c, a*c, a*b})        |
|                                         |
|o12 : RingMap R <-- R                    |
+-----------------------------------------+
|i13 : G*G                                |
|                                         |
|                   2        2        2   |
|o13 = map (R, R, {a b*c, a*b c, a*b*c }) |
|                                         |
|o13 : RingMap R <-- R                    |
+-----------------------------------------+
These are injective ring maps
+--------------------+
|i14 : ker G == 0    |
|                    |
|o14 = true          |
+--------------------+
|i15 : isInjective G |
|                    |
|o15 = true          |
+--------------------+
|i16 : coimage G     |
|                    |
|o16 = R             |
|                    |
|o16 : PolynomialRing|
+--------------------+

Common ways to make a ring map:
  * map(Ring,Ring) -- make a ring map, using the
    names of the variables
  * map(Ring,Ring,List) -- make a ring map
  * map(Ring,Matrix) -- make a ring map
  * map(Ring,Ring,Matrix) -- make a ring
    map
Common ways to get information about ring maps:
  * isHomogeneous(RingMap) -- whether something is
    homogeneous (graded)
  * isInjective(RingMap) -- whether a map is injective
Common operations on ring maps:
  * kernel(RingMap) -- kernel of a ringmap
  * coimage(RingMap) -- coimage of a map
  * preimage(RingMap,Ideal) -- preimage of a map
Applying ring maps, and composing ring maps:
  * RingMap RingElement -- apply a ring map
  * RingMap Matrix -- apply a ring map
  * RingMap Ideal -- apply a ring map
  * RingMap Module -- apply a ring map
  * RingMap * RingMap -- a binary operator, usually used for
    multiplication
Operations involving modules
  * pushForward
  * RingMap ** Module -- tensor product
    via a ring map

Functions and methods returning a ring map:
===========================================

  * "RingMap * RingMap" -- see *, -- a binary operator, usually used
    for multiplication
  * "icMap(Ring)" -- see icMap (IntegralClosure), -- natural map
    from an affine domain into its integral closure
  * map(GaloisField,GaloisField) (missing documentation)
  * map(Ring,Matrix) -- make a ring map
  * map(Ring,Ring) -- make a ring map, using the
    names of the variables
  * map(Ring,Ring,List) -- make a ring map
  * map(Ring,Ring,Matrix) -- make a ring
    map
  * "map(Ring,Ring,RingMap)" -- see map(Ring,Ring,Matrix),
    -- make a ring map
  * "RingMap ^ ZZ" -- see powers,
  * "symmetricAlgebra(Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricAlgebra(Nothing,Nothing,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricAlgebra(Nothing,Ring,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricAlgebra(Ring,Nothing,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "symmetricAlgebra(Ring,Ring,Matrix)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module

Methods that use a ring map:
============================

  * "basis(List,RingMap)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(RingMap)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(Sequence,RingMap)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(ZZ,RingMap)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "coimage(RingMap)" -- see coimage, -- coimage of a map
  * "conductor(RingMap)" -- see conductor (IntegralClosure), --
    the conductor of a finite ring map
  * "describe(RingMap)" -- see describe, -- real description
  * "distinguished(RingMap,Ideal)" -- see distinguished (ReesAlgebra),
    -- Compute the distinguished subvarieties of a
    pullback, intersection or cone
  * graphIdeal(RingMap) -- the ideal of the
    graph of the regular map corresponding to a ring map
  * graphRing(RingMap) -- the coordinate ring of
    the graph of the regular map corresponding to a ring map
  * "inverse(RingMap)" -- see inverse(Matrix), --
    compute the inverse
  * "isHomogeneous(RingMap)" -- see isHomogeneous, --
    whether something is homogeneous (graded)
  * "isInjective(RingMap)" -- see isInjective, -- whether a
    map is injective
  * "isWellDefined(RingMap)" -- see isWellDefined, --
    whether a map is well defined
  * kernel(RingMap) -- kernel of a ringmap
  * "map(Module,Module,RingMap,List)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * map(Module,Module,RingMap,Matrix)
    -- homomorphism of modules
    over different rings
  * "map(Module,Nothing,RingMap,List)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * "map(Module,Nothing,RingMap,Matrix)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * "map(Module,RingMap)" -- see map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * matrix(RingMap) -- the matrix associated to a
    ring map
  * "preimage(RingMap,Ideal)" -- see preimage, -- preimage of a
    map
  * pushForward(RingMap,Module)
  * RingMap == ZZ (missing documentation)
  * RingMap ChainComplexMap (missing documentation)
  * RingMap MutableMatrix (missing documentation)
  * RingMap Power (missing documentation)
  * RingMap Product (missing documentation)
  * "RingMap ChainComplex" -- see RingMap RingElement,
    -- apply a ring map
  * "RingMap Ideal" -- see RingMap RingElement, --
    apply a ring map
  * "RingMap Matrix" -- see RingMap RingElement, --
    apply a ring map
  * "RingMap Module" -- see RingMap RingElement, --
    apply a ring map
  * RingMap RingElement -- apply a ring map
  * "RingMap Vector" -- see RingMap RingElement, --
    apply a ring map
  * RingMap Sum (missing documentation)
  * "setupLift(RingMap)" -- see setupLift, -- set up lift from
    one ring to another
  * "setupPromote(RingMap)" -- see setupPromote, -- set up
    promote from one ring to another
  * source(RingMap) -- find the source ring for a
    map of rings
  * target(RingMap) -- find the target ring for a
    map of rings
  * "RingMap ** Matrix" -- see tensor(RingMap,Matrix),
    -- tensor product via a ring map
  * "RingMap ** Module" -- see tensor(RingMap,Matrix),
    -- tensor product via a ring map
  * tensor(RingMap,Matrix) -- tensor
    product via a ring map
  * "tensor(RingMap,Module)" -- see tensor(RingMap,Matrix),
    -- tensor product via a ring map
  * /// RingMap \ VisibleList /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "VisibleList / RingMap" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * ZZ == RingMap (missing documentation)

For the programmer
==================

The object RingMap, is a type, with ancestor
classes HashTable, < Thing.

RingMap RingElement -- apply a ring map
***************************************

Synopsis
========

  * Operator: SPACE,
  * Usage:
        f X
  * Inputs:
      * f, a ring map from R to S.
      * X, an ideal, a matrix, a vector,
        a module, or a chain complex,
  * Outputs:
      * the image of X under the ring map f.  The result has the same type as
        X, except that its ring will be S.

Description
===========

If X is a module then it must be either free or a submodule of a free module.
If X is a chain complex, then every module of X must be free or a submodule of
a free module.
+------------------------------+
|i1 : R = QQ[x,y];             |
+------------------------------+
|i2 : S = QQ[t];               |
+------------------------------+
|i3 : f = map(S,R,{t^2,t^3})   |
|                              |
|                  2   3       |
|o3 = map (S, R, {t , t })     |
|                              |
|o3 : RingMap S <-- R          |
+------------------------------+
|i4 : f (x+y^2)                |
|                              |
|      6    2                  |
|o4 = t  + t                   |
|                              |
|o4 : S                        |
+------------------------------+
|i5 : f image vars R           |
|                              |
|o5 = image | t2 t3 |          |
|                              |
|                             1|
|o5 : S-module, submodule of S |
+------------------------------+
|i6 : f ideal (x^2,y^2)        |
|                              |
|             4   6            |
|o6 = ideal (t , t )           |
|                              |
|o6 : Ideal of S               |
+------------------------------+
|i7 : f resolution coker vars R|
|                              |
|      1      2      1         |
|o7 = S  <-- S  <-- S  <-- 0   |
|                              |
|     0      1      2      3   |
|                              |
|o7 : ChainComplex             |
+------------------------------+

Caveat
======

If the rings R and S have different degree monoids, then the degrees of the
image might need to be changed, since Macaulay2 sometimes doesn't have enough
information to determine the image degrees of elements of a free module.

See also
========

  * RingElement Sequence -- evaluation of
    polynomials

Ways to use this method:
========================

  * "RingMap ChainComplex"
  * "RingMap Ideal"
  * "RingMap Matrix"
  * "RingMap Module"
  * RingMap RingElement -- apply a ring map
  * "RingMap Vector"

rootPath
********

Synopsis
========

  * Usage:
        rootPath
  * Outputs:
      * a string, the path, as seen by external programs, to the
        root of the file system seen by Macaulay2

Description
===========

This string may be concatenated with an absolute path to get one understandable
by external programs. Currently, this makes a difference only under Microsoft
Windows with Cygwin, but there it's crucial for those external programs that
are not part of Cygwin.  Fortunately, programs compiled under Cygwin know were
to look for files whose paths start with something like C:/, so it is safe
always to concatenate with the value of rootPath, even when it
is unknown whether the external program has been compiled under Cygwin.

+-----------------------------+
|i1 : fn = temporaryFileName()|
|                             |
|o1 = /tmp/M2-2531962-0/0     |
+-----------------------------+
|i2 : rootPath | fn           |
|                             |
|o2 = /tmp/M2-2531962-0/0     |
+-----------------------------+

See also
========

  * rootURI

For the programmer
==================

The object rootPath, is a string.

roots(RingElement) -- compute the roots of a polynomial
*******************************************************

Synopsis
========

  * Function: roots,
  * Usage:
        roots p
  * Inputs:
      * p, a univariate polynomial over ZZ, QQ, RR or CC.
  * Optional inputs,:
      * Precision => ..., default value -1, the number of precision bits used
        to compute the roots.The default precision, is 53 bits
        for polynomials over ZZ, or QQ, and the same as the
        coefficient ring for RR[x] or CC[x].
      * Unique => a Boolean value, default value false, whether
        to return multiple roots one or multiple times.
  * Outputs:
      * a list, The roots of p each one represented as an elements
        of CC.

Description
===========

+-----------------------------------------------------------------------------+
|i1 : RR_100[x]                                                               |
|                                                                             |
|o1 = RR   [x]                                                                |
|       100                                                                   |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : p = x^13 + 5*x^9 + 7*x^4 + x +1                                         |
|                                                                             |
|      13     9     4                                                         |
|o2 = x   + 5x  + 7x  + x + 1                                                 |
|                                                                             |
|o2 : RR   [x]                                                                |
|       100                                                                   |
+-----------------------------------------------------------------------------+
|i3 : roots p                                                                 |
|                                                                             |
|o3 = {-.436092+.332356*ii, -.436092-.332356*ii, .425684-.538177*ii,          |
|     ------------------------------------------------------------------------|
|     .425684+.538177*ii, -.285748-1.02908*ii, .937486-.552608*ii,            |
|     ------------------------------------------------------------------------|
|     .937486+.552608*ii, -.285748+1.02908*ii, -1.02681, .98591+1.08117*ii,   |
|     ------------------------------------------------------------------------|
|     -1.11384+1.06693*ii, -1.11384-1.06693*ii, .98591-1.08117*ii}            |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : o3#0                                                                    |
|                                                                             |
|o4 = -.4360923159618268082323404067424+.3323556439311467670518210894025*ii   |
|                                                                             |
|o4 : CC (of precision 100)                                                   |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i5 : ZZ[x]                                                                   |
|                                                                             |
|o5 = ZZ[x]                                                                   |
|                                                                             |
|o5 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i6 : p = x^13 + 5*x^9 + 7*x^4 + x +1                                         |
|                                                                             |
|      13     9     4                                                         |
|o6 = x   + 5x  + 7x  + x + 1                                                 |
|                                                                             |
|o6 : ZZ[x]                                                                   |
+-----------------------------------------------------------------------------+
|i7 : roots(p^2, Precision=>150, Unique=>true)                                |
|                                                                             |
|o7 = {.425684+.538177*ii, -.436092+.332356*ii, -.436092-.332356*ii,          |
|     ------------------------------------------------------------------------|
|     .425684-.538177*ii, -1.02681, -.436092-.332356*ii, -.285748-1.02908*ii, |
|     ------------------------------------------------------------------------|
|     .425684-.538177*ii, .937486-.552608*ii, .937486+.552608*ii,             |
|     ------------------------------------------------------------------------|
|     .425684+.538177*ii, -.285748+1.02908*ii, -.436092+.332356*ii,           |
|     ------------------------------------------------------------------------|
|     .98591-1.08117*ii, .937486-.552608*ii, .937486+.552608*ii,              |
|     ------------------------------------------------------------------------|
|     .98591+1.08117*ii, -.285748+1.02908*ii, -1.11384+1.06693*ii, -1.02681,  |
|     ------------------------------------------------------------------------|
|     -1.11384-1.06693*ii, -.285748-1.02908*ii, .98591+1.08117*ii,            |
|     ------------------------------------------------------------------------|
|     -1.11384+1.06693*ii, -1.11384-1.06693*ii, .98591-1.08117*ii}            |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : o7#0                                                                    |
|                                                                             |
|o8 = .4256840467819734696313872933276829953560196884                         |
|     +.5381769726065943865846380163632216996196807437*ii                     |
|                                                                             |
|o8 : CC (of precision 150)                                                   |
+-----------------------------------------------------------------------------+

The roots are computed using MPSolve.

Ways to use this method:
========================

  * roots(RingElement) -- compute the roots of a
    polynomial

rootURI
*******

Synopsis
========

  * Usage:
        rootURI
  * Outputs:
      * a string, the path, as seen by an external browser, to
        the root of the file system seen by Macaulay2

Description
===========

This string may be concatenated with an absolute path to get one understandable
by an external browser. Currently, this makes a difference only under Microsoft
Windows with Cygwin, but there it's crucial for those external programs that
are not part of Cygwin.  Fortunately, programs compiled under Cygwin know were
to look for files whose paths start with something like C:/, so it is safe
always to concatenate with the value of rootPath, even when it
is unknown whether the external program has been compiled under Cygwin.

+-------------------------------+
|i1 : fn = temporaryFileName()  |
|                               |
|o1 = /tmp/M2-2533933-0/0       |
+-------------------------------+
|i2 : rootURI | fn              |
|                               |
|o2 = file:///tmp/M2-2533933-0/0|
+-------------------------------+

See also
========

  * rootPath

For the programmer
==================

The object rootURI, is a string.

rotate(ZZ,VisibleList) -- rotate a list
***************************************

Synopsis
========

  * Function: rotate,
  * Usage:
        rotate(n,v)
  * Inputs:
      * n
      * v
  * Outputs:
      * the list obtained by rotating the list v leftward n places

Description
===========

+-----------------------------------------------------------------------------+
|i1 : p = 0 .. 20                                                             |
|                                                                             |
|o1 = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19,  |
|     ------------------------------------------------------------------------|
|     20)                                                                     |
|                                                                             |
|o1 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i2 : rotate(3,p)                                                             |
|                                                                             |
|o2 = (3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 0, 1, |
|     ------------------------------------------------------------------------|
|     2)                                                                      |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i3 : rotate(-3,p)                                                            |
|                                                                             |
|o3 = (18, 19, 20, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16,  |
|     ------------------------------------------------------------------------|
|     17)                                                                     |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * rotate(ZZ,VisibleList) -- rotate a
    list

round -- round a number
***********************

Description
===========

Synopsis
========

  * Usage:
        round x
  * Inputs:
      * x, a number
  * Outputs:
      * the integer nearest to x
+---------------------+
|i1 : round(-2.3)     |
|                     |
|o1 = -2              |
+---------------------+
|i2 : round(-2.3+5*ii)|
|                     |
|o2 = -2              |
+---------------------+
|i3 : round(2/3)      |
|                     |
|o3 = 1               |
+---------------------+

Synopsis
========

  * Usage:
        round(n,x)
  * Inputs:
      * n, an integer,
      * x, a real number,
  * Outputs:
      * the real number with just n decimal digits to the right of the decimal
        point nearest to x
+-------------------------+
|i4 : round(2,1234.5678)  |
|                         |
|o4 = 1234.57             |
|                         |
|o4 : RR (of precision 53)|
+-------------------------+
|i5 : round(-2,1234.5678) |
|                         |
|o5 = 1200                |
|                         |
|o5 : RR (of precision 53)|
+-------------------------+

See also
========

  * floor -- floor function
  * ceiling -- ceiling function

Ways to use round:
==================

  * "round(CC)"
  * "round(Constant)"
  * "round(QQ)"
  * "round(RR)"
  * "round(ZZ)"
  * "round(ZZ,RR)"

For the programmer
==================

The object round, is a method function.

row and column operations
*************************

The usual row and column operations apply to mutable matrices.  These are:
  * rowAdd -- add a multiple of one row to another
  * rowSwap -- interchange rows
  * rowPermute -- permute some rows
  * rowMult -- multiply a row by a ring element
  * columnAdd -- add a multiple of one column to another
  * columnSwap -- interchange columns
  * columnPermute -- permute some columns
  * columnMult -- multiply a column by a ring element

rowAdd -- add a multiple of one row to another
**********************************************

Synopsis
========

  * Usage:
        rowAdd(m,i,a,j)
  * Inputs:
      * m, a mutable matrix,
      * i, an integer,
      * a, a ring element, in the same ring as m
      * j, an integer,
  * Consequences:
      * The i th row of m is modified by adding a times the j th row of m

Description
===========

+---------------------------------------------+
|i1 : R = ZZ[a..f];                           |
+---------------------------------------------+
|i2 : m = mutableMatrix genericMatrix(R,a,2,3)|
|                                             |
|o2 = | a c e |                               |
|     | b d f |                               |
|                                             |
|o2 : MutableMatrix                           |
+---------------------------------------------+
|i3 : rowAdd(m,0,c,1)                         |
|                                             |
|o3 = | bc+a cd+c cf+e |                      |
|     | b    d    f    |                      |
|                                             |
|o3 : MutableMatrix                           |
+---------------------------------------------+
|i4 : m                                       |
|                                             |
|o4 = | bc+a cd+c cf+e |                      |
|     | b    d    f    |                      |
|                                             |
|o4 : MutableMatrix                           |
+---------------------------------------------+

See also
========

  * mutable matrices
  * row and column operations

Ways to use rowAdd:
===================

  * "rowAdd(MutableMatrix,ZZ,Number,ZZ)"
  * "rowAdd(MutableMatrix,ZZ,RingElement,ZZ)"

For the programmer
==================

The object rowAdd, is a method function.

RowExpression -- the class of all matrix expressions
****************************************************

Description
===========

RowExpression is a type of Expression, representing a
horizontal sequence of expressions.

For the programmer
==================

The object RowExpression, is a header type,
with ancestor classes Expression, <
BasicList < Thing.

rowMult -- multiply a row by a ring element
*******************************************

Synopsis
========

  * Usage:
        rowMult(m,i,a)
  * Inputs:
      * m, a mutable matrix,
      * i, an integer,
      * a, a ring element, in the same ring as m
  * Consequences:
      * The i th row of m is modified by multiplying it by a

Description
===========

+---------------------------------------------+
|i1 : R = ZZ[a..f];                           |
+---------------------------------------------+
|i2 : m = mutableMatrix genericMatrix(R,a,2,3)|
|                                             |
|o2 = | a c e |                               |
|     | b d f |                               |
|                                             |
|o2 : MutableMatrix                           |
+---------------------------------------------+
|i3 : rowMult(m,0,c)                          |
|                                             |
|o3 = | ac c2 ce |                            |
|     | b  d  f  |                            |
|                                             |
|o3 : MutableMatrix                           |
+---------------------------------------------+
|i4 : m                                       |
|                                             |
|o4 = | ac c2 ce |                            |
|     | b  d  f  |                            |
|                                             |
|o4 : MutableMatrix                           |
+---------------------------------------------+

See also
========

  * mutable matrices
  * row and column operations

Ways to use rowMult:
====================

  * "rowMult(MutableMatrix,ZZ,Number)"
  * "rowMult(MutableMatrix,ZZ,RingElement)"

For the programmer
==================

The object rowMult, is a method function.

rowPermute -- permute some rows
*******************************

Synopsis
========

  * Usage:
        rowPermute(m,i,{...})
  * Inputs:
      * m, a mutable matrix,
      * i, an integer, starting row
      * a list of integers, denoting a permutation of 0..d, for some number d
  * Consequences:
      * If the permutation is {p0,p1,...,pd}, then m is modified so that the
        i+j row becomes the i+pj row of the original matrix, for j=0..d

Description
===========

+-------------------------------------------------------+
|i1 : m = mutableMatrix map(ZZ^5,ZZ^6, (i,j) -> 100*i+j)|
|                                                       |
|o1 = | 0   1   2   3   4   5   |                       |
|     | 100 101 102 103 104 105 |                       |
|     | 200 201 202 203 204 205 |                       |
|     | 300 301 302 303 304 305 |                       |
|     | 400 401 402 403 404 405 |                       |
|                                                       |
|o1 : MutableMatrix                                     |
+-------------------------------------------------------+
|i2 : rowPermute(m,1,{2,0,1})                           |
|                                                       |
|o2 = | 0   1   2   3   4   5   |                       |
|     | 300 301 302 303 304 305 |                       |
|     | 100 101 102 103 104 105 |                       |
|     | 200 201 202 203 204 205 |                       |
|     | 400 401 402 403 404 405 |                       |
|                                                       |
|o2 : MutableMatrix                                     |
+-------------------------------------------------------+

See also
========

  * mutable matrices
  * row and column operations

Ways to use rowPermute:
=======================

  * "rowPermute(MutableMatrix,ZZ,List)"

For the programmer
==================

The object rowPermute, is a method function.

rowRankProfile -- find the row rank profile of a mutable matrix
***************************************************************

Synopsis
========

  * Usage:
        rowRankProfile m
  * Inputs:
      * m, a mutable matrix, over RR, or
        CC,
  * Outputs:
      * a list, the lexicographically smallest list of indices of
        linearly independent rows generating the row space of m

Description
===========

+---------------------------------------------------------------+
|i1 : rowRankProfile mutableMatrix {{1,2,3}, {0,0,0.}, {3,4,5} }|
|                                                               |
|o1 = {0, 2}                                                    |
|                                                               |
|o1 : List                                                      |
+---------------------------------------------------------------+

See also
========

  * columnRankProfile -- find the column rank profile
    of a mutable matrix

Ways to use rowRankProfile:
===========================

  * "rowRankProfile(MutableMatrix)"

For the programmer
==================

The object rowRankProfile, is a method function.

rowSwap -- interchange rows
***************************

Synopsis
========

  * Usage:
        rowSwap(m,i,j)
  * Inputs:
      * m, a mutable matrix,
      * i, an integer,
      * j, an integer,
  * Consequences:
      * Interchanges the i th and j th rows of m

Description
===========

+----------------------------------------------+
|i1 : m = mutableMatrix matrix{{1,2,3},{4,5,6}}|
|                                              |
|o1 = | 1 2 3 |                                |
|     | 4 5 6 |                                |
|                                              |
|o1 : MutableMatrix                            |
+----------------------------------------------+
|i2 : rowSwap(m,0,1)                           |
|                                              |
|o2 = | 4 5 6 |                                |
|     | 1 2 3 |                                |
|                                              |
|o2 : MutableMatrix                            |
+----------------------------------------------+
|i3 : m                                        |
|                                              |
|o3 = | 4 5 6 |                                |
|     | 1 2 3 |                                |
|                                              |
|o3 : MutableMatrix                            |
+----------------------------------------------+

See also
========

  * mutable matrices
  * row and column operations

Ways to use rowSwap:
====================

  * "rowSwap(MutableMatrix,ZZ,ZZ)"

For the programmer
==================

The object rowSwap, is a method function.

RR -- the class of all real numbers
***********************************

Description
===========

A real number is entered as a sequence of decimal digits with a point.  It is
stored internally as an arbitrary precision floating point number, using the
MPFR, library.
+-------------------------+
|i1 : 3.14159             |
|                         |
|o1 = 3.14159             |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+
The precision is measured in bits, is visible in the ring displayed on the
second of each pair of output lines, and can be recovered using
precision.
+----------------------+
|i2 : precision 3.14159|
|                      |
|o2 = 53               |
+----------------------+
For real numbers, the functions class, and ring, yield
different results.  That allows numbers of various precisions to be used
without creating a new ring for each precision.
+-----------------------+
|i3 : class 3.1         |
|                       |
|o3 = RR                |
|                       |
|o3 : InexactFieldFamily|
+-----------------------+
|i4 : ring 3.1          |
|                       |
|o4 = RR                |
|       53              |
|                       |
|o4 : RealField         |
+-----------------------+
The precision can be specified on input by appending the letter p and a
positive number.
+--------------------------+
|i5 : 3p300                |
|                          |
|o5 = 3                    |
|                          |
|o5 : RR (of precision 300)|
+--------------------------+
An optional exponent (for the power of ten to multiply by) can be specified on
input by appending the letter e and a number.
+--------------------------+
|i6 : 3e3                  |
|                          |
|o6 = 3000                 |
|                          |
|o6 : RR (of precision 53) |
+--------------------------+
|i7 : -3e-3                |
|                          |
|o7 = -.003                |
|                          |
|o7 : RR (of precision 53) |
+--------------------------+
|i8 : -3p111e-3            |
|                          |
|o8 = -.003                |
|                          |
|o8 : RR (of precision 111)|
+--------------------------+
Numbers that appear alone on an output line are displayed with all their
meaningful digits. (Specifying 100 bits of precision yields about 30 decimal
digits of precision.)
+--------------------------------------+
|i9 : 1/3.                             |
|                                      |
|o9 = .3333333333333333                |
|                                      |
|o9 : RR (of precision 53)             |
+--------------------------------------+
|i10 : 1/3p100                         |
|                                      |
|o10 = .3333333333333333333333333333335|
|                                      |
|o10 : RR (of precision 100)           |
+--------------------------------------+
|i11 : 100 * log(10,2)                 |
|                                      |
|o11 = 30.10299956639811               |
|                                      |
|o11 : RR (of precision 53)            |
+--------------------------------------+
Numbers displayed inside more complicated objects are printed with the number
of digits specified by printingPrecision.
+------------------------+
|i12 : printingPrecision |
|                        |
|o12 = 6                 |
+------------------------+
|i13 : {1/3.,1/3p100}    |
|                        |
|o13 = {.333333, .333333}|
|                        |
|o13 : List              |
+------------------------+
The notion of equality tested by ==, amounts to equality of the
internal binary digits.
+---------------------+
|i14 : .5p100 == .5p30|
|                     |
|o14 = true           |
+---------------------+
|i15 : .2p100 == .2p30|
|                     |
|o15 = false          |
+---------------------+
The notion of (strict) equality tested by ===, also
takes the precision into account.
+----------------------+
|i16 : .5p100 === .5p30|
|                      |
|o16 = false           |
+----------------------+
|i17 : .2p100 === .2p30|
|                      |
|o17 = false           |
+----------------------+
Perhaps surprisingly, the IEEE floating point standard also specifies that
every number, including 0, has a sign bit, and strict equality testing takes it
into account, as it must do, because some arithmetic and transcendental
functions take it into account.
+--------------------------+
|i18 : 0.                  |
|                          |
|o18 = 0                   |
|                          |
|o18 : RR (of precision 53)|
+--------------------------+
|i19 : -0.                 |
|                          |
|o19 = -0                  |
|                          |
|o19 : RR (of precision 53)|
+--------------------------+
|i20 : 1/0.                |
|                          |
|o20 = infinity            |
|                          |
|o20 : RR (of precision 53)|
+--------------------------+
|i21 : 1/-0.               |
|                          |
|o21 = -infinity           |
|                          |
|o21 : RR (of precision 53)|
+--------------------------+
|i22 : log 0               |
|                          |
|o22 = -infinity           |
|                          |
|o22 : RR (of precision 53)|
+--------------------------+
|i23 : csc (0.)            |
|                          |
|o23 = infinity            |
|                          |
|o23 : RR (of precision 53)|
+--------------------------+
|i24 : csc (-0.)           |
|                          |
|o24 = -infinity           |
|                          |
|o24 : RR (of precision 53)|
+--------------------------+
Use toExternalString, to produce something that, when
encountered as input, will reproduce exactly what you had before.
+-------------------------------------------------------------------+
|i25 : x = {1/3.,1/3p100}                                           |
|                                                                   |
|o25 = {.333333, .333333}                                           |
|                                                                   |
|o25 : List                                                         |
+-------------------------------------------------------------------+
|i26 : x == {.333333, .333333}                                      |
|                                                                   |
|o26 = false                                                        |
+-------------------------------------------------------------------+
|i27 : y = toExternalString x                                       |
|                                                                   |
|o27 = {.33333333333333331p53,.33333333333333333333333333333346p100}|
+-------------------------------------------------------------------+
|i28 : x === value y                                                |
|                                                                   |
|o28 = true                                                         |
+-------------------------------------------------------------------+
Transcendental constants and functions are available to high precision, with
numeric.
+--------------------------------------------------------------------+
|i29 : numeric pi                                                    |
|                                                                    |
|o29 = 3.141592653589793                                             |
|                                                                    |
|o29 : RR (of precision 53)                                          |
+--------------------------------------------------------------------+
|i30 : numeric_200 pi                                                |
|                                                                    |
|o30 = 3.141592653589793238462643383279502884197169399375105820974944|
|                                                                    |
|o30 : RR (of precision 200)                                         |
+--------------------------------------------------------------------+
|i31 : Gamma oo                                                      |
|                                                                    |
|o31 = 2.288037795340032417959588909060233922889688153356222441199382|
|                                                                    |
|o31 : RR (of precision 200)                                         |
+--------------------------------------------------------------------+

See also
========

  * toRR -- convert to high-precision real number
  * numeric -- convert to floating point
  * precision
  * format -- format a string or a real number
  * printingPrecision -- current precision for
    printing numbers
  * printingAccuracy -- current accuracy for printing
    numbers
  * printingLeadLimit -- maximum number of leading
    zeroes to use when printing real numbers
  * printingTrailLimit -- maximum number of
    additional trailing digits to use when printing real numbers
  * printingSeparator -- string used to separate
    mantissa from exponent when printing real numbers
  * maxExponent
  * minExponent

Functions and methods returning a real number:
==============================================

  * "QQ * RR" -- see *, -- a binary operator, usually used for
    multiplication
  * "RR * QQ" -- see *, -- a binary operator, usually used for
    multiplication
  * "RR * RR" -- see *, -- a binary operator, usually used for
    multiplication
  * "RR * ZZ" -- see *, -- a binary operator, usually used for
    multiplication
  * "ZZ * RR" -- see *, -- a binary operator, usually used for
    multiplication
  * "+ RR" -- see +, -- a unary or binary operator, usually used for
    addition
  * "QQ + RR" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RR + QQ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RR + RR" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RR + ZZ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "ZZ + RR" -- see +, -- a unary or binary operator, usually used
    for addition
  * "- RR" -- see -, -- a unary or binary operator, usually used for
    negation or subtraction
  * "QQ - RR" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RR - QQ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RR - RR" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RR - ZZ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "ZZ - RR" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "QQ / RR" -- see /, -- a binary operator, usually used for
    division
  * "RR / QQ" -- see /, -- a binary operator, usually used for
    division
  * "RR / RR" -- see /, -- a binary operator, usually used for
    division
  * "RR / ZZ" -- see /, -- a binary operator, usually used for
    division
  * "ZZ / RR" -- see /, -- a binary operator, usually used for
    division
  * "acos(RR)" -- see acos, -- arccosine
  * "agm(RR,RR)" -- see agm, -- arithmetic-geometric mean
  * "asin(RR)" -- see asin, -- arcsine
  * "atan(RR)" -- see atan, -- compute the arctangent of a number
  * "atan2(RR,RR)" -- see atan2, -- compute an angle of a certain
    triangle
  * "Beta(RR,RR)" -- see Beta, -- Beta function
  * "cos(RR)" -- see cos, -- compute the cosine
  * "cosh(RR)" -- see cosh, -- compute the hyperbolic cosine
  * "cot(RR)" -- see cot, -- cotangent
  * "coth(RR)" -- see coth, -- hyperbolic cotangent
  * "csc(RR)" -- see csc, -- cosecant
  * "csch(RR)" -- see csch, -- hyperbolic cosecant
  * "Digamma(RR)" -- see Digamma, -- Digamma function
  * "eint(RR)" -- see eint, -- exponential integral
  * "erf(RR)" -- see erf, -- error function
  * "erfc(RR)" -- see erfc, -- complementary error function
  * "exp(RR)" -- see exp, -- exponential function
  * "expm1(RR)" -- see expm1, -- exponential minus 1
  * "Gamma(RR)" -- see Gamma, -- Gamma function
  * "Gamma(RR,RR)" -- see Gamma, -- Gamma function
  * "inverseErf(RR)" -- see inverseErf, -- inverse error
    function
  * "inverseRegularizedBeta(RR,RR,RR)" -- see inverseRegularizedBeta,
    -- inverse of the regularized beta function
  * "inverseRegularizedGamma(RR,RR)" -- see inverseRegularizedGamma,
    -- inverse of the upper regularized gamma function
  * "log(RR)" -- see log, -- logarithm function
  * "log1p(RR)" -- see log1p, -- logarithm of 1+x
  * "random(RR)" -- see random(ZZ,ZZ), -- get a
    random integer or real number
  * "regularizedBeta(RR,RR,RR)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedGamma(RR,RR)" -- see regularizedGamma,
    -- upper regularized gamma function
  * "sec(RR)" -- see sec, -- secant
  * "sech(RR)" -- see sech, -- hyperbolic secant
  * "sin(RR)" -- see sin, -- compute the sine
  * "sinh(RR)" -- see sinh, -- compute the hyperbolic sine
  * "tan(RR)" -- see tan, -- compute the tangent
  * "tanh(RR)" -- see tanh, -- compute the hyperbolic tangent
  * "zeta(RR)" -- see zeta, -- Riemann zeta function

Methods that use a real number:
===============================

  * "RR !" -- see !, -- factorial
  * "CC % RR" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "RR % QQ" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "RR % RR" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "RR % ZZ" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "CC * RR" -- see *, -- a binary operator, usually used for
    multiplication
  * "RR * CC" -- see *, -- a binary operator, usually used for
    multiplication
  * "RR * RRi" -- see *, -- a binary operator, usually used for
    multiplication
  * "RRi * RR" -- see *, -- a binary operator, usually used for
    multiplication
  * "CC + RR" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RR + CC" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RR + RRi" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RRi + RR" -- see +, -- a unary or binary operator, usually used
    for addition
  * "CC - RR" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RR - CC" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RR - RRi" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RRi - RR" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "CC / RR" -- see /, -- a binary operator, usually used for
    division
  * "RR / CC" -- see /, -- a binary operator, usually used for
    division
  * "RR / RRi" -- see /, -- a binary operator, usually used for
    division
  * "RRi / RR" -- see /, -- a binary operator, usually used for
    division
  * "CC // RR" -- see //, -- a binary operator, usually used for
    quotient
  * "InfiniteNumber // RR" -- see //, -- a binary operator, usually
    used for quotient
  * "RR // QQ" -- see //, -- a binary operator, usually used for
    quotient
  * "RR // RR" -- see //, -- a binary operator, usually used for
    quotient
  * "RR // ZZ" -- see //, -- a binary operator, usually used for
    quotient
  * "abs(RR)" -- see abs, -- absolute value function
  * "agm(CC,RR)" -- see agm, -- arithmetic-geometric mean
  * "agm(RR,CC)" -- see agm, -- arithmetic-geometric mean
  * "atan2(RR,RRi)" -- see atan2, -- compute an angle of a certain
    triangle
  * "atan2(RRi,RR)" -- see atan2, -- compute an angle of a certain
    triangle
  * "Beta(CC,RR)" -- see Beta, -- Beta function
  * "Beta(RR,CC)" -- see Beta, -- Beta function
  * "Beta(RR,RRi)" -- see Beta, -- Beta function
  * "Beta(RRi,RR)" -- see Beta, -- Beta function
  * CC == RR (missing documentation)
  * "clean(RR,Matrix)" -- see clean, -- Set to zero elements that
    are approximately zero
  * "clean(RR,MutableMatrix)" -- see clean, -- Set to zero
    elements that are approximately zero
  * "clean(RR,Number)" -- see clean, -- Set to zero elements that
    are approximately zero
  * "clean(RR,RingElement)" -- see clean, -- Set to zero elements
    that are approximately zero
  * "format(RR)" -- see format, -- format a string or a real
    number
  * "Gamma(CC,RR)" -- see Gamma, -- Gamma function
  * "Gamma(RR,CC)" -- see Gamma, -- Gamma function
  * "Gamma(RR,RRi)" -- see Gamma, -- Gamma function
  * "Gamma(RRi,RR)" -- see Gamma, -- Gamma function
  * InfiniteNumber == RR (missing documentation)
  * InfiniteNumber ? RR (missing documentation)
  * "interval(QQ,RR)" -- see interval, -- construct an interval
  * "interval(RR)" -- see interval, -- construct an interval
  * "interval(RR,QQ)" -- see interval, -- construct an interval
  * "interval(RR,RR)" -- see interval, -- construct an interval
  * "interval(RR,ZZ)" -- see interval, -- construct an interval
  * "interval(ZZ,RR)" -- see interval, -- construct an interval
  * "isc(RR)" -- see isc (OnlineLookup), -- ISC lookup
  * "isMember(RR,RRi)" -- see isMember(QQ,RRi),
    -- membership test in an interval
  * "isReal(RR)" -- see isReal, -- whether a number is real
  * "RR << ZZ" -- see left shift,
  * "lift(RR,type of QQ)" -- see lift, -- lift to another ring
  * "lift(RR,type of ZZ)" -- see lift, -- lift to another ring
  * "lngamma(RR)" -- see lngamma, -- logarithm of the Gamma
    function
  * "log(RR,CC)" -- see log, -- logarithm function
  * "log(RR,RR)" -- see log, -- logarithm function
  * "log(RR,RRi)" -- see log, -- logarithm function
  * "log(RRi,RR)" -- see log, -- logarithm function
  * MutableMatrix * RR (missing documentation)
  * "norm(RR,Matrix)" -- see norm,
  * "norm(RR,MutableMatrix)" -- see norm,
  * "norm(RR,Number)" -- see norm,
  * "norm(RR,RingElement)" -- see norm,
  * "numeric(RR)" -- see numeric, -- convert to floating point
  * "promote(RR,type of QQ)" -- see promote, -- promote to
    another ring
  * QQ == RR (missing documentation)
  * "random(RR,RR)" -- see random(ZZ,ZZ), -- get a
    random integer or real number
  * randomMutableMatrix(ZZ,ZZ,RR,ZZ)
    -- a random mutable matrix of
    integers
  * "regularizedBeta(CC,CC,RR)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(CC,RR,CC)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(CC,RR,RR)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RR,CC,CC)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RR,CC,RR)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RR,RR,CC)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RR,RR,RRi)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RR,RRi,RR)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RR,RRi,RRi)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RRi,RR,RR)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RRi,RR,RRi)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RRi,RRi,RR)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedGamma(CC,RR)" -- see regularizedGamma,
    -- upper regularized gamma function
  * "regularizedGamma(RR,CC)" -- see regularizedGamma,
    -- upper regularized gamma function
  * "regularizedGamma(RR,RRi)" -- see regularizedGamma,
    -- upper regularized gamma function
  * "regularizedGamma(RRi,RR)" -- see regularizedGamma,
    -- upper regularized gamma function
  * "RR >> ZZ" -- see right shift,
  * "ring(RR)" -- see ring, -- get the associated ring of an object
  * "round(RR)" -- see round, -- round a number
  * "round(ZZ,RR)" -- see round, -- round a number
  * RR * MutableMatrix (missing documentation)
  * RR == CC (missing documentation)
  * RR == InfiniteNumber (missing documentation)
  * RR == QQ (missing documentation)
  * RR == RR (missing documentation)
  * RR == RRi (missing documentation)
  * RR == ZZ (missing documentation)
  * RR ? InfiniteNumber (missing documentation)
  * RRi == RR (missing documentation)
  * "size2(RR)" -- see size2, -- number of binary digits to the
    left of the point
  * "sqrt(RR)" -- see sqrt, -- square root function
  * "toCC(RR)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(RR,RR)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,QQ,RR)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,RR)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,RR,QQ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,RR,RR)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,RR,ZZ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,ZZ,RR)" -- see toCC, -- convert to high-precision
    complex number
  * ZZ == RR (missing documentation)

For the programmer
==================

The object RR, is an inexact field family,
with ancestor classes InexactNumber, < Number
< Thing.

RR' -- the parent class of all rings of real numbers
****************************************************

Description
===========

Floating point real numbers are treated in a special way.  Recall first to
create a polynomial, one must first create a polynomial ring to contain it.
And then, the polynomial ring is the class of the polynomial.

+-------------------+
|i1 : R = QQ[x,y,z] |
|                   |
|o1 = R             |
|                   |
|o1 : PolynomialRing|
+-------------------+
|i2 : x^2           |
|                   |
|      2            |
|o2 = x             |
|                   |
|o2 : R             |
+-------------------+
|i3 : class x^2     |
|                   |
|o3 = R             |
|                   |
|o3 : PolynomialRing|
+-------------------+

Floating point real numbers, however, can be created directly, as follows,
without creating a ring.

+-----------------------------------------------------------------------------+
|i4 : r = 4.5                                                                 |
|                                                                             |
|o4 = 4.5                                                                     |
|                                                                             |
|o4 : RR (of precision 53)                                                    |
+-----------------------------------------------------------------------------+
|i5 : s = 4.3p300                                                             |
|                                                                             |
|o5 = 4.3000000000000000000000000000000000000000000000000000000000000000000000|
|     00000000000000000002                                                    |
|                                                                             |
|o5 : RR (of precision 300)                                                   |
+-----------------------------------------------------------------------------+

The floating point numbers created above have different precisions, and thus
are regarded as being elements of different rings, whose elements all have the
same precision.

+----------------+
|i6 : precision r|
|                |
|o6 = 53         |
+----------------+
|i7 : precision s|
|                |
|o7 = 300        |
+----------------+
|i8 : ring r     |
|                |
|o8 = RR         |
|       53       |
|                |
|o8 : RealField  |
+----------------+
|i9 : ring s     |
|                |
|o9 = RR         |
|       300      |
|                |
|o9 : RealField  |
+----------------+

In order to make it convenient to define methods that apply to all such rings,
those rings have a common parent, namely RR'.  Notice that RR' is printed in a
special way.

+---------------------------+
|i10 : RR'                  |
|                           |
|o10 = RR                   |
|        *                  |
|                           |
|o10 : Type                 |
+---------------------------+
|i11 : parent ring r        |
|                           |
|o11 = RR                   |
|        *                  |
|                           |
|o11 : Type                 |
+---------------------------+
|i12 : parent ring s        |
|                           |
|o12 = RR                   |
|        *                  |
|                           |
|o12 : Type                 |
+---------------------------+
|i13 : parent ring s === RR'|
|                           |
|o13 = true                 |
+---------------------------+

Methods that use an object of class RR_*:
=========================================

  * "lift(CC,type of RR_*)" -- see lift, -- lift to another ring
  * "lift(Matrix,type of CC_*,type of RR_*)" -- see lift, -- lift
    to another ring
  * "lift(Matrix,type of RR_*,type of QQ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of RR_*,type of ZZ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of RRi_*,type of RR_*)" -- see lift, -- lift
    to another ring
  * "lift(RRi,type of RR_*)" -- see lift, -- lift to another ring
  * lift(Matrix,type of RR_*,type of RR_*) (missing documentation)
  * liftable(CC,type of RR_*) (missing documentation)

For the programmer
==================

The object RR', is a type, with ancestor classes
InexactNumber', < Nothing < Thing.

RRi -- the class of all real intervals
**************************************

Description
===========

A real interval is entered as a pair of real numbers to the interval function.
It is stored internally as an arbitrary precision interval using the
MPFI, library.
+----------------------------+
|i1 : interval(3.1415,3.1416)|
|                            |
|o1 = [3.1415,3.1416]        |
|                            |
|o1 : RRi (of precision 53)  |
+----------------------------+
The precision is measured in bits, is visible in the ring displayed on the
second of each pair of output lines, and can be recovered using
precision.
+--------------------------------------+
|i2 : precision interval(3.1415,3.1416)|
|                                      |
|o2 = 53                               |
+--------------------------------------+
For real intervals, the functions class, and ring,
yield different results.  That allows numbers of various precisions to be used
without creating a new ring for each precision.
+----------------------------+
|i3 : class interval(3.1,3.5)|
|                            |
|o3 = RRi                    |
|                            |
|o3 : InexactFieldFamily     |
+----------------------------+
|i4 : ring interval(3.1,3.5) |
|                            |
|o4 = RRi                    |
|        53                  |
|                            |
|o4 : RealIntervalField      |
+----------------------------+
The precision can be specified on input by specifying the precision of both
input RR, numbers.Alternatively, the precision can be specified by
including the option Precision.
+---------------------------------------------------------------+
|i5 : interval(2.5p100,3.2p1000)                                |
|                                                               |
|o5 = [2.5,3.200000000000000000000000000001]                    |
|                                                               |
|o5 : RRi (of precision 100)                                    |
+---------------------------------------------------------------+
|i6 : interval(2.5,3.2,Precision=>200)                          |
|                                                               |
|o6 = [2.5,3.20000000000000017763568394002504646778106689453125]|
|                                                               |
|o6 : RRi (of precision 200)                                    |
+---------------------------------------------------------------+
Intervals can also be created using span(Sequence),
to create the smallest interval containing the inputs.
+-------------------------------------+
|i7 : span(2,Precision=>100)          |
|                                     |
|o7 = [2,2]                           |
|                                     |
|o7 : RRi (of precision 100)          |
+-------------------------------------+
|i8 : span(2,3,interval(-1.5,-0.5),73)|
|                                     |
|o8 = [-1.5,73]                       |
|                                     |
|o8 : RRi (of precision 53)           |
+-------------------------------------+
Operations using intervals are computed as sets so that the resulting intervals
contain all possible outputs from pairs of points in input intervals.
+----------------------------------+
|i9 : interval(1,3)+interval(2,4)  |
|                                  |
|o9 = [3,7]                        |
|                                  |
|o9 : RRi (of precision 53)        |
+----------------------------------+
|i10 : interval(-1,1)*interval(2,3)|
|                                  |
|o10 = [-3,3]                      |
|                                  |
|o10 : RRi (of precision 53)       |
+----------------------------------+
|i11 : interval(0,1)-interval(0,1) |
|                                  |
|o11 = [-1,1]                      |
|                                  |
|o11 : RRi (of precision 53)       |
+----------------------------------+
|i12 : interval(1,2)/interval(1,2) |
|                                  |
|o12 = [.5,2]                      |
|                                  |
|o12 : RRi (of precision 53)       |
+----------------------------------+
The notion of equality tested by ==, amounts to checking the equality
of the endpoints of intervals.The notion of equality tested by ===,
takes into account the precision of the inputs as well.
+---------------------------------------------------------------------+
|i13 : interval(1,3) == interval(1,3,Precision=>100)                  |
|                                                                     |
|o13 = true                                                           |
+---------------------------------------------------------------------+
|i14 : interval(1,3) === interval(1,3,Precision=>100)                 |
|                                                                     |
|o14 = false                                                          |
+---------------------------------------------------------------------+
|i15 : interval(1/3,1,Precision=>100)==interval(1/3,1,Precision=>1000)|
|                                                                     |
|o15 = false                                                          |
+---------------------------------------------------------------------+
The notion of inequalities for intervals amounts to testing the inequality for
all points in the intervals.  In particular, see <=, is not the same as
<, or ==.
+----------------------------------+
|i16 : interval(1,2)<=interval(2,3)|
|                                  |
|o16 = true                        |
+----------------------------------+
|i17 : interval(1,2)<=interval(1,2)|
|                                  |
|o17 = false                       |
+----------------------------------+
|i18 : interval(1,2)<interval(2,3) |
|                                  |
|o18 = false                       |
+----------------------------------+
|i19 : interval(1,2)<interval(3,4) |
|                                  |
|o19 = true                        |
+----------------------------------+
Transcendental functions on intervals produce intervals containing the image of
the function on the interval.
+-------------------------------------------+
|i20 : exp(interval(2,4))                   |
|                                           |
|o20 = [7.38905609893065,54.59815003314424] |
|                                           |
|o20 : RRi (of precision 53)                |
+-------------------------------------------+
|i21 : cos(interval(1,1.3))                 |
|                                           |
|o21 = [.2674988286245873,.5403023058681398]|
|                                           |
|o21 : RRi (of precision 53)                |
+-------------------------------------------+
|i22 : sqrt(interval(2))                    |
|                                           |
|o22 = [1.414213562373095,1.414213562373095]|
|                                           |
|o22 : RRi (of precision 53)                |
+-------------------------------------------+
Transcendental functions are available to high precision, with
numericInterval.
+-------------------------------------------------------------------------+
|i23 : numericInterval(100,pi)                                            |
|                                                                         |
|o23 = [3.141592653589793238462643383279,3.141592653589793238462643383282]|
|                                                                         |
|o23 : RRi (of precision 100)                                             |
+-------------------------------------------------------------------------+
|i24 : numericInterval_200 EulerConstant                                  |
|                                                                         |
|o24 = [.5772156649015328606065120900824024310421593359399235988057672    |
|      ,.5772156649015328606065120900824024310421593359399235988057678]   |
|                                                                         |
|o24 : RRi (of precision 200)                                             |
+-------------------------------------------------------------------------+

See also
========

  * toRRi -- construct an interval
  * numericInterval -- converts to an interval
  * precision
  * interval -- construct an interval
  * span(Sequence) -- construct smallest interval
  * span(List) -- construct smallest interval

Functions and methods returning a real interval:
================================================

  * "QQ * RRi" -- see *, -- a binary operator, usually used for
    multiplication
  * "RR * RRi" -- see *, -- a binary operator, usually used for
    multiplication
  * "RRi * QQ" -- see *, -- a binary operator, usually used for
    multiplication
  * "RRi * RR" -- see *, -- a binary operator, usually used for
    multiplication
  * "RRi * RRi" -- see *, -- a binary operator, usually used for
    multiplication
  * "RRi * ZZ" -- see *, -- a binary operator, usually used for
    multiplication
  * "ZZ * RRi" -- see *, -- a binary operator, usually used for
    multiplication
  * "+ RRi" -- see +, -- a unary or binary operator, usually used for
    addition
  * "QQ + RRi" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RR + RRi" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RRi + QQ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RRi + RR" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RRi + RRi" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RRi + ZZ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "ZZ + RRi" -- see +, -- a unary or binary operator, usually used
    for addition
  * "- RRi" -- see -, -- a unary or binary operator, usually used for
    negation or subtraction
  * "QQ - RRi" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RR - RRi" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RRi - QQ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RRi - RR" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RRi - RRi" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RRi - ZZ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "ZZ - RRi" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "QQ / RRi" -- see /, -- a binary operator, usually used for
    division
  * "RR / RRi" -- see /, -- a binary operator, usually used for
    division
  * "RRi / QQ" -- see /, -- a binary operator, usually used for
    division
  * "RRi / RR" -- see /, -- a binary operator, usually used for
    division
  * "RRi / RRi" -- see /, -- a binary operator, usually used for
    division
  * "RRi / ZZ" -- see /, -- a binary operator, usually used for
    division
  * "ZZ / RRi" -- see /, -- a binary operator, usually used for
    division
  * "acos(RRi)" -- see acos, -- arccosine
  * "asin(RRi)" -- see asin, -- arcsine
  * "atan(RRi)" -- see atan, -- compute the arctangent of a number
  * "atan2(RR,RRi)" -- see atan2, -- compute an angle of a certain
    triangle
  * "atan2(RRi,RR)" -- see atan2, -- compute an angle of a certain
    triangle
  * "atan2(RRi,RRi)" -- see atan2, -- compute an angle of a
    certain triangle
  * "Beta(RR,RRi)" -- see Beta, -- Beta function
  * "Beta(RRi,RR)" -- see Beta, -- Beta function
  * "Beta(RRi,RRi)" -- see Beta, -- Beta function
  * "cos(RRi)" -- see cos, -- compute the cosine
  * "cosh(RRi)" -- see cosh, -- compute the hyperbolic cosine
  * "cot(RRi)" -- see cot, -- cotangent
  * "coth(RRi)" -- see coth, -- hyperbolic cotangent
  * "csc(RRi)" -- see csc, -- cosecant
  * "csch(RRi)" -- see csch, -- hyperbolic cosecant
  * "Digamma(RRi)" -- see Digamma, -- Digamma function
  * "eint(RRi)" -- see eint, -- exponential integral
  * "erf(RRi)" -- see erf, -- error function
  * "erfc(RRi)" -- see erfc, -- complementary error function
  * "exp(RRi)" -- see exp, -- exponential function
  * "expm1(RRi)" -- see expm1, -- exponential minus 1
  * "Gamma(RR,RRi)" -- see Gamma, -- Gamma function
  * "Gamma(RRi)" -- see Gamma, -- Gamma function
  * "Gamma(RRi,RR)" -- see Gamma, -- Gamma function
  * "Gamma(RRi,RRi)" -- see Gamma, -- Gamma function
  * intersect(RRi) -- computes intersection of input
    intervals
  * intersect(RRi,RRi) (missing documentation)
  * "inverseErf(RRi)" -- see inverseErf, -- inverse error
    function
  * "log(RR,RRi)" -- see log, -- logarithm function
  * "log(RRi)" -- see log, -- logarithm function
  * "log(RRi,RR)" -- see log, -- logarithm function
  * "log(RRi,RRi)" -- see log, -- logarithm function
  * "log1p(RRi)" -- see log1p, -- logarithm of 1+x
  * "regularizedBeta(RR,RR,RRi)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RR,RRi,RR)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RR,RRi,RRi)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RRi,RR,RR)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RRi,RR,RRi)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RRi,RRi,RR)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedBeta(RRi,RRi,RRi)" -- see regularizedBeta,
    -- regularized beta function
  * "regularizedGamma(RR,RRi)" -- see regularizedGamma,
    -- upper regularized gamma function
  * "regularizedGamma(RRi,RR)" -- see regularizedGamma,
    -- upper regularized gamma function
  * "regularizedGamma(RRi,RRi)" -- see regularizedGamma,
    -- upper regularized gamma function
  * "sec(RRi)" -- see sec, -- secant
  * "sech(RRi)" -- see sech, -- hyperbolic secant
  * "sin(RRi)" -- see sin, -- compute the sine
  * "sinh(RRi)" -- see sinh, -- compute the hyperbolic sine
  * "sqrt(RRi)" -- see sqrt, -- square root function
  * "tan(RRi)" -- see tan, -- compute the tangent
  * "tanh(RRi)" -- see tanh, -- compute the hyperbolic tangent
  * "zeta(RRi)" -- see zeta, -- Riemann zeta function

Methods that use a real interval:
=================================

  * "abs(RRi)" -- see abs, -- absolute value function
  * "diameter(RRi)" -- see diameter, -- diameter of an interval
  * intersection(RRi,RRi) -- computes
    intersection of input intervals
  * isEmpty(RRi) -- empty test for an interval
  * isMember(QQ,RRi) -- membership test in an
    interval
  * "isMember(RR,RRi)" -- see isMember(QQ,RRi),
    -- membership test in an interval
  * "isMember(ZZ,RRi)" -- see isMember(QQ,RRi),
    -- membership test in an interval
  * "isReal(RRi)" -- see isReal, -- whether a number is real
  * isSubset(RRi,RRi) -- subset test for
    intervals
  * "RRi << ZZ" -- see left shift,
  * "lift(RRi,type of QQ)" -- see lift, -- lift to another ring
  * "lift(RRi,type of RR_*)" -- see lift, -- lift to another ring
  * "lift(RRi,type of ZZ)" -- see lift, -- lift to another ring
  * "lngamma(RRi)" -- see lngamma, -- logarithm of the Gamma
    function
  * "numeric(RRi)" -- see numeric, -- convert to floating point
  * "numeric(ZZ,RRi)" -- see numeric, -- convert to floating
    point
  * QQ == RRi (missing documentation)
  * "RRi >> ZZ" -- see right shift,
  * "ring(RRi)" -- see ring, -- get the associated ring of an
    object
  * RR == RRi (missing documentation)
  * RRi == QQ (missing documentation)
  * RRi == RR (missing documentation)
  * RRi == RRi (missing documentation)
  * RRi == ZZ (missing documentation)
  * "size2(RRi)" -- see size2, -- number of binary digits to the
    left of the point
  * ZZ == RRi (missing documentation)

For the programmer
==================

The object RRi, is an inexact field family,
with ancestor classes InexactNumber,
< Number < Thing.

rsort -- sort a list or matrix in reverse order
***********************************************

Description
===========

Same as sort, except that the elements or columns are placed in
reverse order.
+--------------------+
|i1 : rsort {4,2,3,1}|
|                    |
|o1 = {4, 3, 2, 1}   |
|                    |
|o1 : List           |
+--------------------+
The optional parameters are the same as for sort.
+----------------------------------------------+
|i2 : R = QQ[a..d];                            |
+----------------------------------------------+
|i3 : m = matrix{{a*b, c*d, a*d^3, b^3*c, 1_R}}|
|                                              |
|o3 = | ab cd ad3 b3c 1 |                      |
|                                              |
|             1      5                         |
|o3 : Matrix R  <-- R                          |
+----------------------------------------------+
|i4 : rsort(m, DegreeOrder=>Ascending)         |
|                                              |
|o4 = | b3c ad3 ab cd 1 |                      |
|                                              |
|             1      5                         |
|o4 : Matrix R  <-- R                          |
+----------------------------------------------+

See also
========

  * sort -- sort a list or columns of a matrix

Ways to use rsort:
==================

  * "rsort(List)"
  * "rsort(Matrix)"
  * rsort(List,Function) (missing documentation)

For the programmer
==================

The object rsort, is a method function with options.

rsort(...,DegreeOrder=>...) -- specify Ascending, Descending, or null
*********************************************************************

Description
===========

The meaning is the same as from sort(...,MonomialOrder=>...).

Further information
===================

  * Default value: null
  * Function: rsort, -- sort a list or matrix in reverse order
  * Option key: DegreeOrder, -- sort primarily by degree

Functions with optional argument named DegreeOrder:
===================================================

  * rsort(...,DegreeOrder=>...)
    -- specify Ascending,
    Descending, or null
  * sort(...,DegreeOrder=>...)
    -- specify Ascending,
    Descending, or null
  * sortColumns(...,DegreeOrder=>...)
    -- specify Ascending,
    Descending, or null

rsort(...,MonomialOrder=>...) -- specify Ascending or Descending monomial order
*******************************************************************************

Description
===========

The meaning is the same as from sort(...,MonomialOrder=>...).

Further information
===================

  * Default value: Ascending,
  * Function: rsort, -- sort a list or matrix in reverse order
  * Option key: MonomialOrder, -- monomial ordering

Functions with optional argument named MonomialOrder:
=====================================================

  * "graphIdeal(...,MonomialOrder=>...)" -- see graphIdeal(RingMap),
    -- the ideal of the graph of the regular map
    corresponding to a ring map
  * "graphRing(...,MonomialOrder=>...)" -- see graphRing(RingMap),
    -- the coordinate ring of the graph of the regular
    map corresponding to a ring map
  * monoid(...,MonomialOrder=>...)
    -- specify the monomial
    ordering
  * "newRing(...,MonomialOrder=>...)" -- see newRing, -- make a
    copy of a ring, with some features changed
  * "pushForward(...,MonomialOrder=>...)" -- see
    pushForward(RingMap,Module),
  * rsort(...,MonomialOrder=>...)
    -- specify Ascending or
    Descending monomial order
  * sort(...,MonomialOrder=>...)
    -- specify Ascending or
    Descending monomial order
  * sortColumns(...,MonomialOrder=>...)
    -- specify Ascending
    or Descending monomial order
  * "symmetricAlgebra(...,MonomialOrder=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,MonomialOrder=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids
  * "tensor(Ring,Ring,MonomialOrder=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

RunDirectory -- the directory from which to run a program
*********************************************************

Functions with optional argument named RunDirectory:
====================================================

  * "runProgram(...,RunDirectory=>...)" -- see runProgram, --
    run an external program

For the programmer
==================

The object RunDirectory, is a symbol.

runLengthEncode(VisibleList) -- run length encoding
***************************************************

Synopsis
========

  * Function: runLengthEncode,
  * Usage:
        runLengthEncode x
  * Inputs:
      * x
  * Outputs:
      * a list equivalent to x, in which runs and sequences have been expressed
        symbolically as expressions,

Description
===========

The result is useful in printed displays, as a way of making them more compact.
The original list can be recovered by applying value, to the
elements of the result, and then using deepSplice, provided
that x contains no entries that are sequences.

+-----------------------------------------------------------------------------+
|i1 : x = {1,2,3,a,b,c,a,b,c,4,4,4,"asdf"};                                   |
+-----------------------------------------------------------------------------+
|i2 : y = runLengthEncode x                                                   |
|                                                                             |
|o2 = {1..3, 2:a..c, 3:4, asdf}                                               |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : peek y                                                                  |
|                                                                             |
|o3 = {BinaryOperation{.., 1, 3}, BinaryOperation{:, 2, a..c},                |
|     ------------------------------------------------------------------------|
|     BinaryOperation{:, 3, 4}, Holder{asdf}}                                 |
+-----------------------------------------------------------------------------+
|i4 : value \ y                                                               |
|                                                                             |
|o4 = {(1, 2, 3), ((a, b, c), (a, b, c)), (4, 4, 4), asdf}                    |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : deepSplice \\ oo                                                        |
|                                                                             |
|o5 = {1, 2, 3, a, b, c, a, b, c, 4, 4, 4, asdf}                              |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : x === oo                                                                |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * BinaryOperation -- the class of all binary
    operation expressions
  * Holder -- the class of all holder expressions

Ways to use this method:
========================

  * runLengthEncode(VisibleList), --
    run length encoding

runProgram -- run an external program
*************************************

Synopsis
========

  * Usage:
        runProgram(program, args)
        runProgram(program, exe, args)
  * Inputs:
      * program, an instance of the type Program, the program
        to run, generated by findProgram.
      * exe, a string, the specific executable file to run. This
        is only necessary if the program consists of multiple such files.  If
        not given, then program#"name" is used.
      * args, a string, the command line arguments passed to the
        program.
  * Optional inputs,:
      * KeepFiles => a Boolean value, default value false,
        whether to keep the temporary files containing the program's output.
      * RaiseError => a Boolean value, default value true,
        whether to raise an error if the program returns a nonzero value.
      * RunDirectory => a string, default value null, the
        directory from which to run the program.  If it does not exist, then it
        will be created.  If null, then the program will be run
        from the current working directory (see currentDirectory).
      * Verbose => a Boolean value, default value false,
        whether to print the command line input and the program's output.

Description
===========

This method runs an external program which has already been loaded using
findProgram.  The results of this run are available in a
ProgramRun, object.

+---------------------------------------------------------+
|i1 : gfan = findProgram("gfan", "gfan --help")           |
|                                                         |
|o1 = gfan                                                |
|                                                         |
|o1 : Program                                             |
+---------------------------------------------------------+
|i2 : runProgram(gfan, "_version")                        |
|                                                         |
|o2 = 0                                                   |
|                                                         |
|o2 : ProgramRun                                          |
+---------------------------------------------------------+
|i3 : oo#"output"                                         |
|                                                         |
|o3 = Gfan version:                                       |
|     gfan0.6.2                                           |
|                                                         |
|     Forked from source tree on:                         |
|     1506606121 Thu Sep 28 15:42:01 2017                 |
|                                                         |
|     Linked libraries:                                   |
|     GMP 6.3.0                                           |
|     Cddlib       YES                                    |
|     SoPlex        NO                                    |
|     Singular      NO                                    |
+---------------------------------------------------------+
|i4 : runProgram(gfan, "_foo", RaiseError => false)       |
|                                                         |
|o4 = 256                                                 |
|                                                         |
|o4 : ProgramRun                                          |
+---------------------------------------------------------+
|i5 : oo#"error"                                          |
|                                                         |
|o5 = UNKNOWN OPTION: _foo.                               |
|     USE --help AS A SINGLE OPTION TO VIEW THE HELP TEXT.|
+---------------------------------------------------------+

The value corresponding to the "output" key may also be obtained using
toString.

+------------------------------------------+
|i6 : toString runProgram(gfan, "_version")|
|                                          |
|o6 = Gfan version:                        |
|     gfan0.6.2                            |
|                                          |
|     Forked from source tree on:          |
|     1506606121 Thu Sep 28 15:42:01 2017  |
|                                          |
|     Linked libraries:                    |
|     GMP 6.3.0                            |
|     Cddlib       YES                     |
|     SoPlex        NO                     |
|     Singular      NO                     |
+------------------------------------------+

It is also possible to skip findProgram, and just provide
two strings: the name of the program and the command line arguments.

+-----------------------------------------------------------------------------+
|i7 : runProgram("normaliz", "--version")                                     |
|                                                                             |
|o7 = 0                                                                       |
|                                                                             |
|o7 : ProgramRun                                                              |
+-----------------------------------------------------------------------------+
|i8 : peek oo                                                                 |
|                                                                             |
|o8 = ProgramRun{command => /usr/bin/normaliz --version                       |
|                error =>                                                     |
|                output => Normaliz 3.10.2                                    |
|                          ---------------------------------------------------|
|                          with package(s) Flint e-antic nauty                |
|                          Copyright (C) 2007-2022  The Normaliz Team, Univers|
|                          This program comes with ABSOLUTELY NO WARRANTY; Thi|
|                          and you are welcome to redistribute it under certai|
|                          See COPYING for details.                           |
|                                                                             |
|                return value => 0                                            |
|-----------------------------------------------------------------------------|
|                   }                                                         |
|                                                                             |
|                                                                             |
|---------                                                                    |
|                                                                             |
|ity of Osnabrueck.                                                           |
|s is free software,                                                          |
|n conditions;                                                                |
+-----------------------------------------------------------------------------+

Internally, this routine uses run. Another way to interact with
programs is to pass a string beginning with "!" to get,
openIn, openOut, or
openInOut.

See also
========

  * ProgramRun -- result of running an external program
  * findProgram -- load external program
  * status(ProgramRun) -- get the return status
    of a program run
  * run -- run an external command
  * get -- get the contents of a file

Ways to use runProgram:
=======================

  * "runProgram(Program,String)"
  * "runProgram(Program,String,String)"
  * "runProgram(String,String)"

For the programmer
==================

The object runProgram, is a method function with options.

same -- whether everything in a list is the same
************************************************

Synopsis
========

  * Usage:
        same L
  * Inputs:
      * L, a list
  * Outputs:
      * b, a Boolean

Description
===========

+----------------------+
|i1 : same {1, 1, 1, 1}|
|                      |
|o1 = true             |
+----------------------+
|i2 : same {1, 2, 1, 1}|
|                      |
|o2 = false            |
+----------------------+

The comparison is done with "===", which is quick, but not always intuitive.
Here is a simple example of what can go wrong:

+---------------------------+
|i3 : R = QQ[x,y,z];        |
+---------------------------+
|i4 : L = {gcd{x,y}, x/x, 1}|
|                           |
|o4 = {1, 1, 1}             |
|                           |
|o4 : List                  |
+---------------------------+
|i5 : same L                |
|                           |
|o5 = false                 |
+---------------------------+

We can see the problem by asking Macaulay2 to display the class of each element
of L. (Or use the function uniform, which returns whether or
not the elements of a list are all of the same class.)

+--------------------+
|i6 : apply(L, class)|
|                    |
|o6 = {R, frac R, ZZ}|
|                    |
|o6 : List           |
+--------------------+
|i7 : uniform L      |
|                    |
|o7 = false          |
+--------------------+

The first 1 is an element of the ring R, the second 1 is an element of the
fraction field of R, and the third 1 is an integer. Thus Macaulay2 thinks of
these three elements as being pairwise unequal, with respect to the operator
"===".

See also
========

  * commonest -- the most common elements of a list or tally
  * number -- count how many elements of a list satisfy a
    condition
  * set -- make a set
  * uniform -- whether all elements of a list are the same
    class
  * unique -- eliminate duplicates from a list
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

For the programmer
==================

The object same, is a function closure.

scan -- apply a function to each element in a list or sequence
**************************************************************

Synopsis
========

  * Usage:
        scan(L, f)
        scan(L, L', f)
        scan(n, f)
  * Inputs:
      * L, a basic list, or instance of a class with the
        iterator, method installed
      * n, an integer,
      * f, a function,

Description
===========

scan(L, f) applies the function f to each element of the list L. The function
values are discarded.

+-----------------------------------------+
|i1 : scan({a, 4, "George", 2^100}, print)|
|a                                        |
|4                                        |
|George                                   |
|1267650600228229401496703205376          |
+-----------------------------------------+
|i2 : scan("foo", print)                  |
|f                                        |
|o                                        |
|o                                        |
+-----------------------------------------+

scan(n, f) applies the function f to each element of the list 0, 1, ..., n-1

+---------------------------------------------+
|i3 : scan(4, print)                          |
|0                                            |
|1                                            |
|2                                            |
|3                                            |
+---------------------------------------------+
|i4 : v = {a,b,c}; scan(#v, i -> print(i,v#i))|
|(0, a)                                       |
|(1, b)                                       |
|(2, c)                                       |
+---------------------------------------------+

The keyword break, can be used to terminate the scan prematurely,
and optionally to specify a return value for the expression. Here we use it to
locate the first even number in a list.

+-----------------------------------------------------------+
|i6 : scan({3,5,7,11,44,55,77}, i -> if even i then break i)|
|                                                           |
|o6 = 44                                                    |
+-----------------------------------------------------------+

If L is an instance of a class with the iterator, method
installed (e.g., a string), then f is applied to the values obtained by
repeatedly calling next, on the output of iterator L until
StopIteration, is returned.

+-----------------------+
|i7 : scan("foo", print)|
|f                      |
|o                      |
|o                      |
+-----------------------+

See also
========

  * apply -- apply a function to each element
  * accumulate -- apply a binary operator repeatedly
  * fold -- apply a binary operator repeatedly
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use scan:
=================

  * "scan(BasicList,BasicList,Function)"
  * "scan(BasicList,Function)"
  * "scan(Thing,Function)"
  * "scan(ZZ,Function)"

For the programmer
==================

The object scan, is a compiled function.

scanKeys -- apply a function to each key in a hash table or database
********************************************************************

Synopsis
========

  * Usage:
        scanKeys(t, f)
  * Inputs:
      * t, a hash table, or Database
      * f, a function,

Description
===========

scanKeys(t, f) applies the function f to each key in the hash table t.

+----------------------------------------------+
|i1 : t = hashTable {{1,8},{2,20},{3,4},{4,20}}|
|                                              |
|o1 = HashTable{1 => 8 }                       |
|               2 => 20                        |
|               3 => 4                         |
|               4 => 20                        |
|                                              |
|o1 : HashTable                                |
+----------------------------------------------+
|i2 : scanKeys(t, print)                       |
|1                                             |
|2                                             |
|3                                             |
|4                                             |
+----------------------------------------------+
|i3 : scanKeys(t, k -> if k>2 then print t#k)  |
|4                                             |
|20                                            |
+----------------------------------------------+

Caveat
======

This function requires an immutable hash table.  To scan the keys in a mutable
hash table, use scan(keys t, f).

See also
========

  * hash tables
  * applyKeys -- apply a function to each key in a hash table
  * keys -- keys used in a hash table, dictionary, or database
  * scan -- apply a function to each element in a list or sequence
  * scanPairs -- apply a function to the pairs in a hash
    table
  * scanValues -- apply a function to each value in a hash
    table or database

Ways to use scanKeys:
=====================

  * "scanKeys(Database,Function)"
  * "scanKeys(HashTable,Function)"

For the programmer
==================

The object scanKeys, is a method function.

scanLines -- apply a function to each line of a file
****************************************************

Synopsis
========

  * Usage:
        scanLines(f,fn)
  * Inputs:
      * f
      * fn, the name of a file, or a list of names of files
  * Outputs:
      * returns null, unless the function uses break x with a
        non-null value for x, in which case scanning stops and x is returned
        immediately
  * Consequences:
      * applies f to each line of the file(s)

Description
===========

The file is read and processed one block at a time, making this procedure
potentially much better at conserving memory than scan(lines get fn,f) when the
file is very large.

Ways to use scanLines:
======================

  * "scanLines(Function,List)"
  * "scanLines(Function,String)"

For the programmer
==================

The object scanLines, is a method function.

scanPairs -- apply a function to the pairs in a hash table
**********************************************************

Synopsis
========

  * Usage:
        scanPairs(t, f)
  * Inputs:
      * t, a hash table,
      * f, a function,

Description
===========

scanPairs(t, f) applies the function f to each pair (k, t#k) in the hash table
t. In other words, f is applied to each key k paired with its corresponding
value t#k.

+-------------------------------------------------+
|i1 : t = hashTable {{1,8},{2,20},{3,4},{4,20}}   |
|                                                 |
|o1 = HashTable{1 => 8 }                          |
|               2 => 20                           |
|               3 => 4                            |
|               4 => 20                           |
|                                                 |
|o1 : HashTable                                   |
+-------------------------------------------------+
|i2 : scanPairs(t, (k,v) -> print (k+v))          |
|9                                                |
|22                                               |
|7                                                |
|24                                               |
+-------------------------------------------------+
|i3 : scanPairs(t, (k,v) -> if v==20 then print k)|
|2                                                |
|4                                                |
+-------------------------------------------------+

Caveat
======

This function requires an immutable hash table.  To scan the pairs in a mutable
hash table, use scan(pairs t, f).

See also
========

  * hash tables
  * applyPairs -- apply a function to each pair in a hash
    table
  * pairs -- list the pairs in a hash table, dictionary, or basic
    list
  * scan -- apply a function to each element in a list or sequence
  * scanKeys -- apply a function to each key in a hash table
    or database
  * scanValues -- apply a function to each value in a hash
    table or database

Ways to use scanPairs:
======================

  * "scanPairs(HashTable,Function)"

For the programmer
==================

The object scanPairs, is a compiled function.

scanValues -- apply a function to each value in a hash table or database
************************************************************************

Synopsis
========

  * Usage:
        scanValues(t, f)
  * Inputs:
      * t, a hash table,
      * f, a function,

Description
===========

scanValues(t, f) applies the function f to each value in the hash table t.

+----------------------------------------------+
|i1 : t = hashTable {{1,8},{2,20},{3,4},{4,20}}|
|                                              |
|o1 = HashTable{1 => 8 }                       |
|               2 => 20                        |
|               3 => 4                         |
|               4 => 20                        |
|                                              |
|o1 : HashTable                                |
+----------------------------------------------+
|i2 : scanValues(t, print)                     |
|8                                             |
|20                                            |
|4                                             |
|20                                            |
+----------------------------------------------+
|i3 : scanValues(t, v -> if v>10 then print v) |
|20                                            |
|20                                            |
+----------------------------------------------+

Caveat
======

This function requires an immutable hash table.  To scan the values in a
mutable hash table, use scan(values t, f).

See also
========

  * hash tables
  * applyValues -- apply a function to each value in a hash
    table
  * scan -- apply a function to each element in a list or sequence
  * scanKeys -- apply a function to each key in a hash table
    or database
  * scanPairs -- apply a function to the pairs in a hash
    table
  * values -- values in a hash table

Ways to use scanValues:
=======================

  * "scanValues(HashTable,Function)"

For the programmer
==================

The object scanValues, is a method function.

schreyerOrder -- create or obtain free modules with Schreyer monomial orders
****************************************************************************

See also
========

  * monomial orders for free modules

Ways to use schreyerOrder:
==========================

  * schreyerOrder(Matrix) -- create a matrix
    with the same entries whose source free module has a Schreyer monomial
    order
  * schreyerOrder(Module) -- obtain Schreyer
    order information

For the programmer
==================

The object schreyerOrder, is a method function.

schreyerOrder(Matrix) -- create a matrix with the same entries whose source free module has a Schreyer monomial order
*********************************************************************************************************************

Synopsis
========

  * Function: schreyerOrder,
  * Usage:
        schreyerOrder m
  * Inputs:
      * m, G <-- F between free modules
  * Outputs:
      * the same matrix as m, except that its source free module is endowed
        with a Schreyer, or induced, monomial order

Description
===========

Given a matrix $m : F --> G$, the Schreyer order on the monomials of F is given
by: If $a e_i$ and $b e_j$ are monomials of $F$, i.e. $a$ and $b$ are monomials
in the ring, and $e_i$ and $e_j$ are unit column vectors of $F$, then $a e_i >
b e_j$ if and only if either $leadterm(m)(a e_i) > leadterm(m)(b e_j)$ or they
are scalar multiples of the same monomial in $G$, and $i > j$.

If the base ring is a quotient ring, we think of leadterm(m) as a matrix over
the ambient polynomial ring for the purpose of this definition.

In the example below, the source of f is endowed with a Schreyer order.
+--------------------------------------------------+
|i1 : R = ZZ/101[a..d];                            |
+--------------------------------------------------+
|i2 : m = matrix{{a,b,c,d}};                       |
|                                                  |
|             1      4                             |
|o2 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i3 : f = schreyerOrder m                          |
|                                                  |
|o3 = | a b c d |                                  |
|                                                  |
|             1      4                             |
|o3 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i4 : g = syz f                                    |
|                                                  |
|o4 = {1} | -b 0  -c 0  0  -d |                    |
|     {1} | a  -c 0  0  -d 0  |                    |
|     {1} | 0  b  a  -d 0  0  |                    |
|     {1} | 0  0  0  c  b  a  |                    |
|                                                  |
|             4      6                             |
|o4 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i5 : leadTerm g                                   |
|                                                  |
|o5 = {1} | 0 0 0 0 0 0 |                          |
|     {1} | a 0 0 0 0 0 |                          |
|     {1} | 0 b a 0 0 0 |                          |
|     {1} | 0 0 0 c b a |                          |
|                                                  |
|             4      6                             |
|o5 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i6 : hf = map(source f, 1, {{d},{c},{b},{a}})     |
|                                                  |
|o6 = {1} | d |                                    |
|     {1} | c |                                    |
|     {1} | b |                                    |
|     {1} | a |                                    |
|                                                  |
|             4      1                             |
|o6 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i7 : hm = map(source m, 1, {{d},{c},{b},{a}})     |
|                                                  |
|o7 = {1} | d |                                    |
|     {1} | c |                                    |
|     {1} | b |                                    |
|     {1} | a |                                    |
|                                                  |
|             4      1                             |
|o7 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i8 : leadTerm hf                                  |
|                                                  |
|o8 = {1} | 0 |                                    |
|     {1} | 0 |                                    |
|     {1} | b |                                    |
|     {1} | 0 |                                    |
|                                                  |
|             4      1                             |
|o8 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i9 : leadTerm hm                                  |
|                                                  |
|o9 = {1} | 0 |                                    |
|     {1} | 0 |                                    |
|     {1} | 0 |                                    |
|     {1} | a |                                    |
|                                                  |
|             4      1                             |
|o9 : Matrix R  <-- R                              |
+--------------------------------------------------+
Use schreyerOrder(Module), to see if a free
module is endowed with a Schreyer order.
+----------------------------+
|i10 : schreyerOrder source m|
|                            |
|o10 = 0                     |
|                            |
|                    4       |
|o10 : Matrix 0 <-- R        |
+----------------------------+
|i11 : schreyerOrder source f|
|                            |
|o11 = | a 0 0 0 |           |
|      | 0 b 0 0 |           |
|      | 0 0 c 0 |           |
|      | 0 0 0 d |           |
|                            |
|              4      4      |
|o11 : Matrix R  <-- R       |
+----------------------------+

See also
========

  * Schreyer orders -- induced monomial order on a free
    module
  * monomial orders for free modules
  * leadTerm -- get the greatest term
  * schreyerOrder(Module) -- obtain Schreyer
    order information

Ways to use this method:
========================

  * schreyerOrder(Matrix) -- create a matrix
    with the same entries whose source free module has a Schreyer monomial
    order

schreyerOrder(Module) -- obtain Schreyer order information
**********************************************************

Synopsis
========

  * Function: schreyerOrder,
  * Usage:
        schreyerOrder F
  * Inputs:
      * F, a free module
  * Outputs:
      * a matrix, the zero matrix, if F is not equipped with a
        Schreyer order, otherwise a matrix with source F, such that the
        monomial order on F is the one induced by this matrix.

Description
===========

For examples, see Schreyer orders, and
schreyerOrder(Matrix).

See also
========

  * monomial orders for free modules

Ways to use this method:
========================

  * schreyerOrder(Module) -- obtain Schreyer
    order information

Schubert(ZZ,ZZ,VisibleList) -- find the Plücker ideal of a Schubert variety
***************************************************************************

Synopsis
========

  * Function: Schubert,
  * Usage:
        Schubert(k,n,sigma)
  * Inputs:
      * k
      * n
      * sigma, a subset of 0..n of size k+1 that indexes the Schubert variety
  * Optional inputs,:
      * CoefficientRing => a ring, default value ZZ, the
        coefficient ring for the polynomial ring to be made
      * Variable => a symbol, default value "p", the base symbol
        for the indexed variables to be used.  The subscripts are the elements
        of subsets(n+1,k+1), converted to sequences and, if k is 0, converted
        to integers.
  * Outputs:
      * an ideal, the ideal of the Schubert variety indexed by
        sigma

Description
===========

Given natural numbers $k \le{} n$, this routine finds the ideal of the Schubert
variety indexed by sigma in the Grassmannian of projective $k$-planes in $P^n$.

For example, the ideal of the Schubert variety indexed by $\{1,2,4\}$ in the
Grassmannian of projective planes in $P^4$ is displayed in the following
example.

+-----------------------------------------------------------------------------+
|i1 : I = Schubert(2,4,{1,2,4},CoefficientRing => QQ)                         |
|                                                                             |
|o1 = ideal (p     , p     , p     , p     p      - p     p     , p     p     |
|             2,3,4   1,3,4   0,3,4   1,2,3 0,2,4    0,2,3 1,2,4   1,2,3 0,1,4|
|     ------------------------------------------------------------------------|
|     - p     p     , p     p      - p     p     )                            |
|        0,1,3 1,2,4   0,2,3 0,1,4    0,1,3 0,2,4                             |
|                                                                             |
|o1 : Ideal of QQ[p     ..p     , p     , p     , p     , p     , p     , p   |
|                  0,1,2   0,1,3   0,2,3   1,2,3   0,1,4   0,2,4   1,2,4   0,3|
|-----------------------------------------------------------------------------|
|  , p     , p     ]                                                          |
|,4   1,3,4   2,3,4                                                           |
+-----------------------------------------------------------------------------+
|i2 : R = ring I;                                                             |
+-----------------------------------------------------------------------------+
|i3 : C = res I                                                               |
|                                                                             |
|      1      6      14      16      9      2                                 |
|o3 = R  <-- R  <-- R   <-- R   <-- R  <-- R  <-- 0                           |
|                                                                             |
|     0      1      2       3       4      5      6                           |
|                                                                             |
|o3 : ChainComplex                                                            |
+-----------------------------------------------------------------------------+
|i4 : betti C                                                                 |
|                                                                             |
|            0 1  2  3 4 5                                                    |
|o4 = total: 1 6 14 16 9 2                                                    |
|         0: 1 3  3  1 . .                                                    |
|         1: . 3 11 15 9 2                                                    |
|                                                                             |
|o4 : BettiTally                                                              |
+-----------------------------------------------------------------------------+

See also
========

  * Grassmannian -- the Grassmannian of
    linear subspaces of a vector space
  * pfaffians -- ideal generated by Pfaffians

Ways to use this method:
========================

  * Schubert(ZZ,ZZ,VisibleList), --
    find the Plücker ideal of a Schubert variety

scriptCommandLine -- the command line arguments to be used when running a script
********************************************************************************

Synopsis
========

  * Usage:
        scriptCommandLine

Description
===========

A constant whose value is the list of arguments passed to the interpreter when
a script is started, excluding argument 0, the name of the program, and
excluding argument 1, the option "--script".

See also
========

  * commandLine -- the command line arguments

For the programmer
==================

The object scriptCommandLine, is a list.

ScriptedFunctor -- the class of all scripted functors
*****************************************************

Description
===========

A scripted functor accepts a subscript or a superscript: the primary example is
HH.

See also
========

  * subscript -- specify the function in a scripted functor
    for a subscript
  * superscript -- specify the function in a scripted
    functor for a superscript
  * argument -- specify the function in a scripted functor for
    an argument

Methods that use a scripted functor:
====================================

  * "? ScriptedFunctor" -- see ? Symbol, -- view brief
    documentation of a symbol
  * "methodOptions(ScriptedFunctor)" -- see methodOptions(Function),
    -- recover the options used when a method
    function was created
  * "methods(ScriptedFunctor)" -- see methods, -- list methods
  * "ScriptedFunctor ^ Thing"
  * "ScriptedFunctor _ Thing"
  * "ScriptedFunctor Thing"

Protected objects of class ScriptedFunctor:
===========================================

  * Ext -- compute an Ext module
  * HH -- general homology and cohomology functor
  * hh (Varieties) -- Hodge numbers of a smooth projective variety
  * id -- identity map
  * OO (Varieties) -- the structure sheaf
  * sheafExt (Varieties) -- sheaf Ext of coherent sheaves
  * Tor -- Tor module

For the programmer
==================

The object ScriptedFunctor, is a type, with
ancestor classes MutableHashTable, < HashTable
< Thing.

searchPath(List,String) -- search a path for a file
***************************************************

Synopsis
========

  * Function: searchPath,
  * Usage:
        searchPath(pa,fn)
        searchPath fn
  * Inputs:
      * pa, a list of strings giving paths to directories.  Each one ends with
        a slash. If omitted, then path, is used
      * fn
  * Outputs:
      * a list of those directories in pa containing files named fn

See also
========

  * File -- the class of all files
  * minimizeFilename -- minimize a file name
  * relativizeFilename -- relativize a file name
  * baseFilename -- the base part of a filename or path
  * toAbsolutePath -- the absolute path version of a
    file name
  * path -- list of directories to look in

Ways to use this method:
========================

  * searchPath(List,String) -- search a
    path for a file
  * "searchPath(String)"

sec -- secant
*************

Synopsis
========

  * Usage:
        sec x
        sec I
  * Inputs:
      * x
      * I, a real interval,
  * Outputs:
      * a real number, the secant of x
      * a real interval, an interval containing the secants of the
        points of I

Description
===========

+-------------------------+
|i1 : sec(pi/3)           |
|                         |
|o1 = 2                   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See Trigonometric function (see
https://en.wikipedia.org/wiki/Trigonometric_function ).

Ways to use sec:
================

  * "sec(CC)"
  * "sec(RR)"
  * "sec(RRi)"
  * sec(RingElement) (missing documentation)

For the programmer
==================

The object sec, is a method function.

sech -- hyperbolic secant
*************************

Synopsis
========

  * Usage:
        sech x
        sech I
  * Inputs:
      * x
      * I, a real interval,
  * Outputs:
      * a real number, the hyperbolic secant of x
      * a real interval, an interval containing the hyerbolic
        secants of the points of I

Description
===========

+-------------------------+
|i1 : sech(pi/3)          |
|                         |
|o1 = .6248879662960872   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See Hyperbolic function (see https://en.wikipedia.org/wiki/Hyperbolic_function
).

Ways to use sech:
=================

  * "sech(CC)"
  * "sech(RR)"
  * "sech(RRi)"
  * sech(RingElement) (missing documentation)

For the programmer
==================

The object sech, is a method function.

seeParsing -- display parsing precedence table for Macaulay2 operators
**********************************************************************

Synopsis
========

  * Usage:
        seeParsing()

Description
===========

We intend to eliminate this function in favor of operatorAttributes.

See also
========

  * parsing precedence, in detail

For the programmer
==================

The object seeParsing, is a function closure.

select -- select from a list, hash table, or string
***************************************************

See also
========

  * partition -- partition a set or list by values of a
    function

Ways to use select:
===================

  * select(BasicList,Function), --
    select elements from a list
  * select(BasicList,Type) -- select
    elements of a given type in a list
  * select(HashTable,Function), --
    select part of a hash table
  * "select(String,String)" -- see select(String,String,String),
    -- select and reformat substrings
    matching a regular expression
  * select(String,String,String),
    -- select and reformat substrings matching a regular expression
  * select(Thing,Function) -- select
    elements from an object with an iterator
  * select(ZZ,BasicList,Function),
    -- select a limited number of elements from a list
  * select(ZZ,Function) -- select integers
  * select(ZZ,HashTable,Function),
    -- select a limited number of pairs from a hash table
  * "select(Set,Function)" -- see select(ZZ,Set,Function),
    -- select a part of a set
  * select(ZZ,Set,Function) -- select a
    part of a set

For the programmer
==================

The object select, is a method function with options.

select(BasicList,Function) -- select elements from a list
*********************************************************

Synopsis
========

  * Function: select,
  * Usage:
        select(v,f)
  * Inputs:
      * v
      * f, returning either true, or false,
  * Outputs:
      * a list of those elements of the list v that yield true when the
        function f is applied

Description
===========

The order of the elements in the result will be the same as in the original
list v, and the class of the result will be the same as the class of v.
+-----------------------------+
|i1 : select({1,2,3,4,5}, odd)|
|                             |
|o1 = {1, 3, 5}               |
|                             |
|o1 : List                    |
+-----------------------------+
|i2 : select([1,2,3,4,5], odd)|
|                             |
|o2 = [1, 3, 5]               |
|                             |
|o2 : Array                   |
+-----------------------------+

See also
========

  * select(ZZ,BasicList,Function),
    -- select a limited number of elements from a list
  * partition -- partition a set or list by values of a
    function
  * positions -- which elements of a list satisfy a condition

Ways to use this method:
========================

  * select(BasicList,Function), --
    select elements from a list

select(BasicList,Type) -- select elements of a given type in a list
*******************************************************************

Synopsis
========

  * Function: select,
  * Usage:
        select(L, T)
  * Inputs:
      * L, a basic list,
      * T, a type,
  * Outputs:
      * a basic list, containing elements of L whose class
        inherits from type T

Description
===========

The order of the elements in the result will be the same as in the original
list L, and the class of the result will be the same as the class of L.

+------------------------------------+
|i1 : select({1,"2",3.14,4+5*ii}, ZZ)|
|                                    |
|o1 = {1}                            |
|                                    |
|o1 : List                           |
+------------------------------------+
|i2 : select([1,"2",3.14,4+5*ii], RR)|
|                                    |
|o2 = [3.14]                         |
|                                    |
|o2 : Array                          |
+------------------------------------+

See also
========

  * select(BasicList,Function), --
    select elements from a list

Ways to use this method:
========================

  * select(BasicList,Type) -- select
    elements of a given type in a list

select(HashTable,Function) -- select part of a hash table
*********************************************************

Synopsis
========

  * Function: select,
  * Usage:
        select(v,f)
        selectValues(v,f)
  * Inputs:
      * v
      * f, returning either true, or false,
  * Outputs:
      * whose pairs are those key-value pairs (k,w) of the hash table v that
        yield true when the function f is applied to the value w.

Description
===========

The hash table v should be immutable: to scan the values in a mutable hash
table, use scan(values x, f).
+------------------------------------------------------+
|i1 : x = new HashTable from { x => 1, y => 2, z => 3 }|
|                                                      |
|o1 = HashTable{x => 1}                                |
|               y => 2                                 |
|               z => 3                                 |
|                                                      |
|o1 : HashTable                                        |
+------------------------------------------------------+
|i2 : select(x,odd)                                    |
|                                                      |
|o2 = HashTable{x => 1}                                |
|               z => 3                                 |
|                                                      |
|o2 : HashTable                                        |
+------------------------------------------------------+

See also
========

  * select(ZZ,HashTable,Function),
    -- select a limited number of pairs from a hash table
  * partition -- partition a set or list by values of a
    function
  * selectKeys -- select a part of a hash table by keys
  * selectPairs -- select a part of a hash table by pairs

Ways to use this method:
========================

  * select(HashTable,Function), --
    select part of a hash table

select(Thing,Function) -- select elements from an object with an iterator
*************************************************************************

Synopsis
========

  * Function: select,
  * Usage:
        select(x, f)
  * Inputs:
      * x, a thing, an instance of a class with the
        iterator, method installed;
      * f, a function, returning either true, or
        false,;
  * Outputs:
      * an iterator,

Description
===========

Suppose x is an instance of a class with the iterator, method
installed, e.g., a string, and suppose iter is the output of iterator x.  Then
a new Iterator, object is returned whose next,
method returns the next output of next iter for which f next iter is true,
unless next iter returns StopIteration, in which case
this new iterator does the same.

+----------------------------------------------+
|i1 : selectiter = select("foo", i -> i == "o")|
|                                              |
|o1 = selectiter                               |
|                                              |
|o1 : Iterator                                 |
+----------------------------------------------+
|i2 : next selectiter                          |
|                                              |
|o2 = o                                        |
+----------------------------------------------+
|i3 : next selectiter                          |
|                                              |
|o3 = o                                        |
+----------------------------------------------+
|i4 : next selectiter                          |
|                                              |
|o4 = StopIteration                            |
|                                              |
|o4 : Symbol                                   |
+----------------------------------------------+

See also
========

  * iterator -- get an iterator
  * Iterator -- class for iterators
  * next -- get the next object from an iterator
  * StopIteration -- stop iteration
  * apply(Thing,Function) -- apply a
    function to an object with an iterator

Ways to use this method:
========================

  * select(Thing,Function) -- select
    elements from an object with an iterator

select(ZZ,BasicList,Function) -- select a limited number of elements from a list
********************************************************************************

Synopsis
========

  * Function: select,
  * Usage:
        select(n,v,f)
  * Inputs:
      * n
      * v
      * f, returning either true, or false,
  * Outputs:
      * a list containing at most n elements of the list v that yield true when
        the function f is applied.

Description
===========

The order of the elements in the result will be the same as in the original
list v.
+-------------------------+
|i1 : select(4,0..10,even)|
|                         |
|o1 = (0, 2, 4, 6)        |
|                         |
|o1 : Sequence            |
+-------------------------+

See also
========

  * select(BasicList,Function), --
    select elements from a list
  * partition -- partition a set or list by values of a
    function

Ways to use this method:
========================

  * select(ZZ,BasicList,Function),
    -- select a limited number of elements from a list

select(ZZ,Function) -- select integers
**************************************

Synopsis
========

  * Function: select,
  * Usage:
        select(n,f)
  * Inputs:
      * n
      * f, returning either true, or false,
  * Outputs:
      * a list of those natural numbers i less than n that yield true when the
        function f is applied

Description
===========

+----------------------------------------+
|i1 : select(20, odd)                    |
|                                        |
|o1 = {1, 3, 5, 7, 9, 11, 13, 15, 17, 19}|
|                                        |
|o1 : List                               |
+----------------------------------------+
|i2 : select(20, even)                   |
|                                        |
|o2 = {0, 2, 4, 6, 8, 10, 12, 14, 16, 18}|
|                                        |
|o2 : List                               |
+----------------------------------------+

See also
========

  * select(ZZ,BasicList,Function),
    -- select a limited number of elements from a list
  * partition -- partition a set or list by values of a
    function
  * positions -- which elements of a list satisfy a condition

Ways to use this method:
========================

  * select(ZZ,Function) -- select integers

select(ZZ,HashTable,Function) -- select a limited number of pairs from a hash table
***********************************************************************************

Synopsis
========

  * Function: select,
  * Usage:
        select(n,v,f)
        selectValues(n,v,f)
  * Inputs:
      * n
      * v
      * f, returning either true, or false,
  * Outputs:
      * whose pairs are those key-value pairs of the hash table v that yield
        true when the function f is applied to the value, except that at most n
        pairs will be selected

Description
===========

The hash table v should be immutable: to scan the values in a mutable hash
table, use scan(values x, f).
+------------------------------------------------------+
|i1 : x = new HashTable from { x => 1, y => 2, z => 3 }|
|                                                      |
|o1 = HashTable{x => 1}                                |
|               y => 2                                 |
|               z => 3                                 |
|                                                      |
|o1 : HashTable                                        |
+------------------------------------------------------+
|i2 : select(1,x,odd)                                  |
|                                                      |
|o2 = HashTable{x => 1}                                |
|                                                      |
|o2 : HashTable                                        |
+------------------------------------------------------+

See also
========

  * select(HashTable,Function), --
    select part of a hash table
  * partition -- partition a set or list by values of a
    function
  * selectKeys -- select a part of a hash table by keys
  * selectPairs -- select a part of a hash table by pairs

Ways to use this method:
========================

  * select(ZZ,HashTable,Function),
    -- select a limited number of pairs from a hash table

select(ZZ,Set,Function) -- select a part of a set
*************************************************

Synopsis
========

  * Function: select,
  * Usage:
        select(x, f)
        select(n, x, f)
  * Inputs:
      * n, an integer,
      * x, a set,
      * f, a function,
  * Outputs:
      * a set, containing all (or n, if it is given) elements of x
        that evaluate to true when passed to f

Description
===========

+----------------------------------------+
|i1 : x = set(1..10)                     |
|                                        |
|o1 = set {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}|
|                                        |
|o1 : Set                                |
+----------------------------------------+
|i2 : select(x, odd)                     |
|                                        |
|o2 = set {9, 1, 3, 5, 7}                |
|                                        |
|o2 : Set                                |
+----------------------------------------+
|i3 : select(2, x, odd)                  |
|                                        |
|o3 = set {1, 3}                         |
|                                        |
|o3 : Set                                |
+----------------------------------------+

Ways to use this method:
========================

  * "select(Set,Function)"
  * select(ZZ,Set,Function) -- select a
    part of a set

selectInSubring -- select columns in a subring
**********************************************

Synopsis
========

  * Usage:
        selectInSubring(i,m)
  * Inputs:
      * i, an integer,
      * m, a matrix,
  * Outputs:
      * a matrix, with the same target and ring as m, consisting
        of those columns of m which lie in the subring where the first i blocks
        of the monomial order are zero

Description
===========

For example, consider the following block (or product) order.
+--------------------------------------------------------------------+
|i1 : R = QQ[x,y,a..d,t,MonomialOrder=>{2,4,1}];                     |
+--------------------------------------------------------------------+
|i2 : m = matrix{{x*a-d^2, a^3-1, x-a^100, a*b*d+t*c^3, t^3-t^2-t+1}}|
|                                                                    |
|o2 = | xa-d2 a3-1 x-a100 c3t+abd t3-t2-t+1 |                        |
|                                                                    |
|             1      5                                               |
|o2 : Matrix R  <-- R                                                |
+--------------------------------------------------------------------+
|i3 : selectInSubring(1,m)                                           |
|                                                                    |
|o3 = | a3-1 c3t+abd t3-t2-t+1 |                                     |
|                                                                    |
|             1      3                                               |
|o3 : Matrix R  <-- R                                                |
+--------------------------------------------------------------------+
|i4 : selectInSubring(2,m)                                           |
|                                                                    |
|o4 = | t3-t2-t+1 |                                                  |
|                                                                    |
|             1      1                                               |
|o4 : Matrix R  <-- R                                                |
+--------------------------------------------------------------------+

The lexicographic order is considered as one block, as in the following
example.
+---------------------------------------------+
|i5 : S = QQ[a..d,MonomialOrder=>Lex];        |
+---------------------------------------------+
|i6 : m = matrix{{a^2-b, b^2-c, c^2-d, d^2-1}}|
|                                             |
|o6 = | a2-b b2-c c2-d d2-1 |                 |
|                                             |
|             1      4                        |
|o6 : Matrix S  <-- S                         |
+---------------------------------------------+
|i7 : selectInSubring(1,m)                    |
|                                             |
|o7 = 0                                       |
|                                             |
|             1                               |
|o7 : Matrix S  <-- 0                         |
+---------------------------------------------+

If you wish to be able to pick out the elements not involving a, or a and b,
etc, then create a block monomial order.
+---------------------------------------------+
|i8 : S = QQ[a..d,MonomialOrder=>{4:1}];      |
+---------------------------------------------+
|i9 : m = matrix{{a^2-b, b^2-c, c^2-d, d^2-1}}|
|                                             |
|o9 = | a2-b b2-c c2-d d2-1 |                 |
|                                             |
|             1      4                        |
|o9 : Matrix S  <-- S                         |
+---------------------------------------------+
|i10 : selectInSubring(1,m)                   |
|                                             |
|o10 = | b2-c c2-d d2-1 |                     |
|                                             |
|              1      3                       |
|o10 : Matrix S  <-- S                        |
+---------------------------------------------+
|i11 : selectInSubring(2,m)                   |
|                                             |
|o11 = | c2-d d2-1 |                          |
|                                             |
|              1      2                       |
|o11 : Matrix S  <-- S                        |
+---------------------------------------------+
|i12 : selectInSubring(3,m)                   |
|                                             |
|o12 = | d2-1 |                               |
|                                             |
|              1      1                       |
|o12 : Matrix S  <-- S                        |
+---------------------------------------------+

Caveat
======

This routine doesn't do what one would expect for graded orders such as GLex.
There, the first part of the monomial order is the degree, which is usually not
zero.

See also
========

  * monomial orderings
  * leadTerm -- get the greatest term
  * eliminate (Elimination)

Ways to use selectInSubring:
============================

  * "selectInSubring(ZZ,Matrix)"

For the programmer
==================

The object selectInSubring, is a method function.

selectKeys -- select a part of a hash table by keys
***************************************************

Synopsis
========

  * Usage:
        selectKeys(x, f)
        selectKeys(n, x, f)
  * Inputs:
      * n, an integer,
      * x, a hash table, must be immutable;
      * f, a function,
  * Outputs:
      * a hash table, containing all (or n, if it is given)
        key-value pairs (k,v) from x for which f k evaluates to true.

Description
===========

+----------------------------------------------------------+
|i1 : x = hashTable{(1, a), (2, b), (3, c), (4, d), (5, e)}|
|                                                          |
|o1 = HashTable{1 => a}                                    |
|               2 => b                                     |
|               3 => c                                     |
|               4 => d                                     |
|               5 => e                                     |
|                                                          |
|o1 : HashTable                                            |
+----------------------------------------------------------+
|i2 : selectKeys(x, odd)                                   |
|                                                          |
|o2 = HashTable{1 => a}                                    |
|               3 => c                                     |
|               5 => e                                     |
|                                                          |
|o2 : HashTable                                            |
+----------------------------------------------------------+
|i3 : selectKeys(2, x, odd)                                |
|                                                          |
|o3 = HashTable{1 => a}                                    |
|               3 => c                                     |
|                                                          |
|o3 : HashTable                                            |
+----------------------------------------------------------+

See also
========

  * selectValues -- select part of a
    hash table
  * selectPairs -- select a part of a hash table by pairs

Ways to use selectKeys:
=======================

  * "selectKeys(HashTable,Function)"
  * "selectKeys(ZZ,HashTable,Function)"

For the programmer
==================

The object selectKeys, is a method function.

selectPairs -- select a part of a hash table by pairs
*****************************************************

Synopsis
========

  * Usage:
        selectPairs(x, f)
        selectPairs(n, x, f)
  * Inputs:
      * n, an integer,
      * x, a hash table, must be immutable;
      * f, a function,
  * Outputs:
      * a hash table, containing all (or n, if it is given)
        key-value pairs (k,v) from x for which f(k,v) evaluates to true.

Description
===========

+-----------------------------------------------------------+
|i1 : x = hashTable{(1, 2), (2, 4), (3, 6), (4, 8), (5, 10)}|
|                                                           |
|o1 = HashTable{1 => 2 }                                    |
|               2 => 4                                      |
|               3 => 6                                      |
|               4 => 8                                      |
|               5 => 10                                     |
|                                                           |
|o1 : HashTable                                             |
+-----------------------------------------------------------+
|i2 : selectPairs(x, (k,v) -> odd(k + v))                   |
|                                                           |
|o2 = HashTable{1 => 2 }                                    |
|               3 => 6                                      |
|               5 => 10                                     |
|                                                           |
|o2 : HashTable                                             |
+-----------------------------------------------------------+
|i3 : selectPairs(2, x, (k, v) -> odd(k + v))               |
|                                                           |
|o3 = HashTable{1 => 2}                                     |
|               3 => 6                                      |
|                                                           |
|o3 : HashTable                                             |
+-----------------------------------------------------------+

See also
========

  * selectValues -- select part of a
    hash table
  * selectKeys -- select a part of a hash table by keys

Ways to use selectPairs:
========================

  * "selectPairs(HashTable,Function)"
  * "selectPairs(ZZ,HashTable,Function)"

For the programmer
==================

The object selectPairs, is a compiled function.

selectVariables(List,PolynomialRing) -- make a subring of a polynomial ring generated by selected variables
***********************************************************************************************************

Synopsis
========

  * Function: selectVariables,
  * Usage:
        (S,F) = selectVariables(v,R)
  * Inputs:
      * v, a sorted list of numbers specifying which variables to select
      * R
  * Outputs:
      * S, a polynomial ring, a polynomial ring
        generated as a subring of R by the variables whose indices occur in the
        list v, together with the induced monomial ordering
      * F, a ring map, the inclusion map from S to R

Description
===========

+-----------------------------------------------------------------------------+
|i1 : (S,F) = selectVariables({2,4}, QQ[a..h,Weights=>1..8]);                 |
+-----------------------------------------------------------------------------+
|i2 : describe S                                                              |
|                                                                             |
|o2 = QQ[c, e, Degrees => {2:1}, Heft => {1}, MonomialOrder =>                |
|                                                                             |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32}]                                                        |
|{Weights => {3, 5} }                                                         |
|{GRevLex => {2:1}  }                                                         |
|{Position => Up    }                                                         |
+-----------------------------------------------------------------------------+
|i3 : options S                                                               |
|                                                                             |
|o3 = OptionTable{Constants => false                   }                      |
|                                  1                                          |
|                 DegreeGroup => ZZ                                           |
|                 DegreeLift => null                                          |
|                 DegreeMap => null                                           |
|                 DegreeRank => 1                                             |
|                 Degrees => {{1}, {1}}                                       |
|                 Global => true                                              |
|                 Heft => {1}                                                 |
|                 Inverses => false                                           |
|                 Join => null                                                |
|                 Local => false                                              |
|                 MonomialOrder => {MonomialSize => 32}                       |
|                                  {Weights => {3, 5} }                       |
|                                  {GRevLex => {1, 1} }                       |
|                                  {Position => Up    }                       |
|                 SkewCommutative => {}                                       |
|                 Variables => {c, e}                                         |
|                 WeylAlgebra => {}                                           |
|                                                                             |
|o3 : OptionTable                                                             |
+-----------------------------------------------------------------------------+
|i4 : F                                                                       |
|                                                                             |
|o4 = map (QQ[a..h], S, {c, e})                                               |
|                                                                             |
|o4 : RingMap QQ[a..h] <-- S                                                  |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * selectVariables(List,PolynomialRing)
    -- make a subring of a
    polynomial ring generated by selected variables

SelfInitializingType -- the class of all self initializing types
****************************************************************

Description
===========

A self initializing type X will produce an instance of X from initial data v
with the expression X v.

+----------------------------------------------+
|i1 : X = new SelfInitializingType of BasicList|
|                                              |
|o1 = X                                        |
|                                              |
|o1 : SelfInitializingType                     |
+----------------------------------------------+
|i2 : x = X {1,2,3}                            |
|                                              |
|o2 = X{1, 2, 3}                               |
|                                              |
|o2 : X                                        |
+----------------------------------------------+
|i3 : class x                                  |
|                                              |
|o3 = X                                        |
|                                              |
|o3 : SelfInitializingType                     |
+----------------------------------------------+

See Command, is an example of a self initializing type.

See also
========

  * HeaderType -- a class of lists with abbreviated
    constructors
  * WrapperType -- a class of lists with abbreviated
    constructors

Methods that use a self initializing type:
==========================================

  * "SelfInitializingType Thing"
  * /// SelfInitializingType \\ Thing /// -- see Thing // Function,
    -- apply a function
  * "Thing // SelfInitializingType" -- see Thing // Function,
    -- apply a function
  * /// SelfInitializingType \ VisibleList /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "VisibleList / SelfInitializingType" -- see VisibleList / Function,
    -- apply a function to elements of a list

Protected objects of class SelfInitializingType:
================================================

  * Bag -- the class of all bags
  * Command -- the class of all commands
  * Eliminate -- elimination order
  * Hybrid (MinimalPrimes) -- the class of lists encapsulating
    hybrid strategies
  * Iterator -- class for iterators
  * LowerBound (Varieties) -- the class of lower bound
    objects
  * NumberedVerticalList -- a type of visible
    self-initializing list that prints vertically
  * ProductOrder -- product ordering
  * "TestInput" -- see tests, -- locate a package's tests
  * URL -- a type representing a URL
  * VerticalList -- a type of visible self-initializing
    list that prints vertically

For the programmer
==================

The object SelfInitializingType, is a type,
with ancestor classes Type, < MutableHashTable
< HashTable < Thing.

sequence -- make a sequence
***************************

Synopsis
========

  * Usage:
        sequence v
  * Inputs:
      * v, a thing,
  * Outputs:
      * a sequence, v if v is a sequence, otherwise a sequence
        of length 1 containing v

Description
===========

Such a function is needed occasionally to restore uniformity, because a
nonempty parenthesized expression with no commas is not parsed as a sequence.

+------------------+
|i1 : sequence()   |
|                  |
|o1 = ()           |
|                  |
|o1 : Sequence     |
+------------------+
|i2 : sequence(4)  |
|                  |
|o2 = 1 : (4)      |
|                  |
|o2 : Sequence     |
+------------------+
|i3 : sequence(4,5)|
|                  |
|o3 = (4, 5)       |
|                  |
|o3 : Sequence     |
+------------------+
|i4 : identity()   |
|                  |
|o4 = ()           |
|                  |
|o4 : Sequence     |
+------------------+
|i5 : identity(4)  |
|                  |
|o5 = 4            |
+------------------+
|i6 : identity(4,5)|
|                  |
|o6 = (4, 5)       |
|                  |
|o6 : Sequence     |
+------------------+

See also
========

  * unsequence -- extract the single element from a sequence
    of length 1

For the programmer
==================

The object sequence, is a compiled function.

serialNumber -- serial number of a dictionary, task, symbol, mutable hash table, or mutable list,
**************************************************************************************************

Synopsis
========

  * Usage:
        serialNumber x
  * Inputs:
      * x
  * Outputs:
      * an integer, the serial number of x

Description
===========

+----------------------+
|i1 : serialNumber asdf|
|                      |
|o1 = 1528252          |
+----------------------+
|i2 : serialNumber foo |
|                      |
|o2 = 1528254          |
+----------------------+
|i3 : serialNumber ZZ  |
|                      |
|o3 = 1000050          |
+----------------------+

For the programmer
==================

The object serialNumber, is a compiled function.

Set -- the class of all sets
****************************

Description
===========

Elements of sets may be any immutable object, such as integers, ring elements
and lists of such.  Ideals may also be elements of sets.
+-------------------------+
|i1 : A = set {1,2};      |
+-------------------------+
|i2 : R = QQ[a..d];       |
+-------------------------+
|i3 : B = set{a^2-b*c,b*d}|
|                         |
|           2             |
|o3 = set {a  - b*c, b*d} |
|                         |
|o3 : Set                 |
+-------------------------+
Set operations, such as membership, union,
see intersection,
difference, Cartesian product,
Cartesian power, and subset,
are available. For example,
+-----------------------------------------+
|i4 : toList B                            |
|                                         |
|       2                                 |
|o4 = {a  - b*c, b*d}                     |
|                                         |
|o4 : List                                |
+-----------------------------------------+
|i5 : member(1,A)                         |
|                                         |
|o5 = true                                |
+-----------------------------------------+
|i6 : member(-b*c+a^2,B)                  |
|                                         |
|o6 = true                                |
+-----------------------------------------+
|i7 : A ** A                              |
|                                         |
|o7 = set {(1, 1), (1, 2), (2, 1), (2, 2)}|
|                                         |
|o7 : Set                                 |
+-----------------------------------------+
|i8 : A^**2                               |
|                                         |
|o8 = set {(1, 1), (1, 2), (2, 1), (2, 2)}|
|                                         |
|o8 : Set                                 |
+-----------------------------------------+
|i9 : set{1,3,2} - set{1}                 |
|                                         |
|o9 = set {2, 3}                          |
|                                         |
|o9 : Set                                 |
+-----------------------------------------+
|i10 : set{4,5} + set{5,6}                |
|                                         |
|o10 = set {4, 5, 6}                      |
|                                         |
|o10 : Set                                |
+-----------------------------------------+
|i11 : set{4,5} * set{5,6}                |
|                                         |
|o11 = set {5}                            |
|                                         |
|o11 : Set                                |
+-----------------------------------------+
|i12 : set{1,3,2} === set{1,2,3}          |
|                                         |
|o12 = true                               |
+-----------------------------------------+

See Ideals, in Macaulay2 come equipped with a specific sequence of
generators, so the following two ideals are not considered strictly equal, and
thus the set containing them will appear to have two elements.
+--------------------------------------+
|i13 : I = ideal(a,b); J = ideal(b,a); |
|                                      |
|o13 : Ideal of R                      |
|                                      |
|o14 : Ideal of R                      |
+--------------------------------------+
|i15 : I == J                          |
|                                      |
|o15 = true                            |
+--------------------------------------+
|i16 : I === J                         |
|                                      |
|o16 = false                           |
+--------------------------------------+
|i17 : C = set(ideal(a,b),ideal(b,a))  |
|                                      |
|o17 = set {ideal (b, a), ideal (a, b)}|
|                                      |
|o17 : Set                             |
+--------------------------------------+
However, if you trim, the ideals, then the generating sets will be
the same, and so the set containing them will have one element.
+-----------------------------------------------+
|i18 : C1 = set(trim ideal(a,b),trim ideal(b,a))|
|                                               |
|o18 = set {ideal (b, a)}                       |
|                                               |
|o18 : Set                                      |
+-----------------------------------------------+

A set is implemented as a HashTable, whose keys are the
elements of the set, and whose values are all 1.  In particular, this means
that two objects are considered the same exactly when they are strictly equal,
according to ===.

Functions and methods returning a set:
======================================

  * Command \ Set (missing documentation)
  * Function \ Set (missing documentation)
  * "intersect(Set,Set)" -- see intersection(Set,Set),
    -- set intersection
  * intersection(Set,Set) -- set
    intersection
  * "Set * Set" -- see intersection(Set,Set),
    -- set intersection
  * "select(Set,Function)" -- see select(ZZ,Set,Function),
    -- select a part of a set
  * select(ZZ,Set,Function) -- select a
    part of a set
  * "set(VisibleList)" -- see set, -- make a set
  * Set ** Set -- Cartesian product
  * "Set - List" -- see Set - Set, -- set difference
  * Set - Set -- set difference
  * Set / Command (missing documentation)
  * Set / Function (missing documentation)
  * "Set + Set" -- see union(Set,Set), -- set union
  * union(Set,Set) -- set union

Methods that use a set:
=======================

  * "# Set" -- see # BasicList, -- length or cardinality
  * "commonest(Set)" -- see commonest, -- the most common
    elements of a list or tally
  * "elements(Set)" -- see elements, -- list of elements
  * "isMember(Thing,Set)" -- see isMember, -- test membership
    in a list or set
  * isSubset(Set,Set) -- whether one object is
    a subset of another
  * "isSubset(Set,VisibleList)" -- see isSubset(Set,Set),
    -- whether one object is a subset of another
  * "isSubset(VisibleList,Set)" -- see isSubset(Set,Set),
    -- whether one object is a subset of another
  * product(Set) -- product of elements
  * Set #? Thing -- test set membership
  * "List - Set" -- see Set - Set, -- set difference
  * "subsets(Set)" -- see subsets, -- produce the subsets of a
    set or list
  * "subsets(Set,ZZ)" -- see subsets, -- produce the subsets of
    a set or list
  * sum(Set) -- sum of elements
  * "toList(Set)" -- see toList, -- create a list

For the programmer
==================

The object Set, is a type, with ancestor classes
Tally, < VirtualTally < HashTable
< Thing.

set -- make a set
*****************

Synopsis
========

  * Usage:
        set v
        set(v1,v2,...)
  * Inputs:
      * v, a list,
  * Outputs:
      * a set,  the set whose elements are the members of the list
        v

Description
===========

+-------------------------+
|i1 : v = {1,2,3,2,1}     |
|                         |
|o1 = {1, 2, 3, 2, 1}     |
|                         |
|o1 : List                |
+-------------------------+
|i2 : S = set v           |
|                         |
|o2 = set {1, 2, 3}       |
|                         |
|o2 : Set                 |
+-------------------------+
|i3 : T = set(a,b,c,a,b,d)|
|                         |
|o3 = set {c, d, a, b}    |
|                         |
|o3 : Set                 |
+-------------------------+

See also
========

  * Set -- the class of all sets

Ways to use set:
================

  * "set(VisibleList)"

For the programmer
==================

The object set, is a compiled function.

Set #? Thing -- test set membership
***********************************

Synopsis
========

  * Operator: #?,
  * Usage:
        x#?e
  * Inputs:
      * x
      * e
  * Outputs:
      * a Boolean value, whether e is in the set x

Description
===========

This is identical to member(e,x).
+-------------------+
|i1 : x = set{1,2,3}|
|                   |
|o1 = set {1, 2, 3} |
|                   |
|o1 : Set           |
+-------------------+
|i2 : x#?2          |
|                   |
|o2 = true          |
+-------------------+
|i3 : member(2,x)   |
|                   |
|o3 = true          |
+-------------------+

See also
========

  * Set -- the class of all sets

Ways to use this method:
========================

  * Set #? Thing -- test set membership

Set ** Set -- Cartesian product
*******************************

Synopsis
========

  * Operator: **,
  * Usage:
        x ** y
  * Inputs:
      * x
      * y
  * Outputs:
      * whose elements are the sequences (a,b), where a is an element of x, and
        b is an element of y., a set,

Description
===========

+---------------------------------------------------------+
|i1 : set {1,2} ** set {a,b,c}                            |
|                                                         |
|o1 = set {(1, a), (2, a), (1, b), (2, b), (1, c), (2, c)}|
|                                                         |
|o1 : Set                                                 |
+---------------------------------------------------------+
Suppose we wish to form the set of all triples with entries either in the set A
below.
+-----------------------------------------------------------------------------+
|i2 : A = set{1,2}                                                            |
|                                                                             |
|o2 = set {1, 2}                                                              |
|                                                                             |
|o2 : Set                                                                     |
+-----------------------------------------------------------------------------+
|i3 : A ** A ** A                                                             |
|                                                                             |
|o3 = set {((1, 1), 1), ((1, 2), 1), ((1, 1), 2), ((2, 1), 1), ((2, 2), 1),   |
|     ------------------------------------------------------------------------|
|     ((1, 2), 2), ((2, 1), 2), ((2, 2), 2)}                                  |
|                                                                             |
|o3 : Set                                                                     |
+-----------------------------------------------------------------------------+
To make this last a set of triples, see splice, each element
together. Or, use VirtualTally ^** ZZ.
+-----------------------------------------------------------------------------+
|i4 : (A ** A ** A)/splice                                                    |
|                                                                             |
|o4 = set {(1, 1, 1), (1, 1, 2), (1, 2, 1), (2, 1, 1), (2, 1, 2), (2, 2, 1),  |
|     ------------------------------------------------------------------------|
|     (1, 2, 2), (2, 2, 2)}                                                   |
|                                                                             |
|o4 : Set                                                                     |
+-----------------------------------------------------------------------------+
|i5 : A^**3                                                                   |
|                                                                             |
|o5 = set {((1, 1), 1), ((1, 2), 1), ((1, 1), 2), ((2, 1), 1), ((2, 2), 1),   |
|     ------------------------------------------------------------------------|
|     ((1, 2), 2), ((2, 1), 2), ((2, 2), 2)}                                  |
|                                                                             |
|o5 : Set                                                                     |
+-----------------------------------------------------------------------------+

See also
========

  * Set -- the class of all sets

Ways to use this method:
========================

  * Set ** Set -- Cartesian product

Set - Set -- set difference
***************************

Synopsis
========

  * Operator: -,
  * Usage:
        x - y
  * Inputs:
      * x,  or a list,
      * y,  or a list,
  * Outputs:
      * a set, or a list, consisting of those elements
        of x not in y

Description
===========

At least one of x, y must be a set, and the other may be a list.  If x is a
list, then so is the result.
+------------------------+
|i1 : set{a,b,c} - set{a}|
|                        |
|o1 = set {c, b}         |
|                        |
|o1 : Set                |
+------------------------+
|i2 : set{a,b,c} - {a}   |
|                        |
|o2 = set {c, b}         |
|                        |
|o2 : Set                |
+------------------------+
|i3 : {a,b,c} - set{a}   |
|                        |
|o3 = {b, c}             |
|                        |
|o3 : List               |
+------------------------+

See also
========

  * Set -- the class of all sets

Ways to use this method:
========================

  * "List - Set"
  * "Set - List"
  * Set - Set -- set difference

setGroupID -- set the process group identifier
**********************************************

Synopsis
========

  * Usage:
        setGroupID(pid,pgid)
  * Inputs:
      * pid, an integer,
      * pgid, an integer,
  * Consequences:
      * The process group id of the process with process id pid is set to pgid.
        If pid is 0, the current process is affected.  If pgid is 0, the new
        process group id is equal to the process id.

See also
========

  * processID -- the process identifier
  * groupID -- the process group identifier

For the programmer
==================

The object setGroupID, is a compiled function.

setRandomSeed -- set starting point for random number generator
***************************************************************

Synopsis
========

  * Usage:
        setRandomSeed()
        setRandomSeed(seed)
  * Consequences:
      * If seed is (), initializes the random number generator to a fixed
        state, identical to the initial state (upon program start) in version
        1.2 and earlier of Macaulay2. Otherwise sets randomSeed to a value
        based on seed.

Description
===========

Since version 1.2, when Macaulay2 starts the random number seed is initially
set to a number that depends on the current date, the time (in seconds), and
the process id, except for when running examples and tests in packages, where
it is always initialized to 0 by passing the command line option
--no-randomize.

The sequence of future pseudo-random results is determined by the random number
seed.

+------------------------------------+
|i1 : setRandomSeed()                |
+------------------------------------+
|i2 : random 2^100                   |
|                                    |
|o2 = 278091837517481385900793178228 |
+------------------------------------+
|i3 : random 2^100                   |
|                                    |
|o3 = 1096904973926824930696315518408|
+------------------------------------+
|i4 : setRandomSeed()                |
+------------------------------------+
|i5 : random 2^100                   |
|                                    |
|o5 = 278091837517481385900793178228 |
+------------------------------------+
|i6 : random 2^100                   |
|                                    |
|o6 = 1096904973926824930696315518408|
+------------------------------------+

If an integer seed is given, the random number seed is set to the low-order 32
bits of the seed.

+----------------------------------------------+
|i7 : setRandomSeed 123456                     |
|                                              |
|o7 = 123456                                   |
+----------------------------------------------+
|i8 : for i to 10 list random 100              |
|                                              |
|o8 = {8, 29, 5, 22, 4, 32, 35, 57, 3, 95, 36} |
|                                              |
|o8 : List                                     |
+----------------------------------------------+
|i9 : setRandomSeed 123456                     |
|                                              |
|o9 = 123456                                   |
+----------------------------------------------+
|i10 : for i to 10 list random 100             |
|                                              |
|o10 = {8, 29, 5, 22, 4, 32, 35, 57, 3, 95, 36}|
|                                              |
|o10 : List                                    |
+----------------------------------------------+

If a string seed is given, sets the random number seed to an integer computed
from it. Every character of the string contributes to the seed, but only 32
bits of data are used. The sequence of future pseudo-random results is
determined by the seed.

+--------------------------------------------------+
|i11 : setRandomSeed "thrkwjsxz"                   |
|                                                  |
|o11 = 1267386136561992923                         |
+--------------------------------------------------+
|i12 : for i to 10 list random 100                 |
|                                                  |
|o12 = {28, 70, 67, 31, 68, 14, 42, 24, 16, 14, 51}|
|                                                  |
|o12 : List                                        |
+--------------------------------------------------+
|i13 : setRandomSeed "thrkwjsxz"                   |
|                                                  |
|o13 = 1267386136561992923                         |
+--------------------------------------------------+
|i14 : for i to 10 list random 100                 |
|                                                  |
|o14 = {28, 70, 67, 31, 68, 14, 42, 24, 16, 14, 51}|
|                                                  |
|o14 : List                                        |
+--------------------------------------------------+

Code
====

../../../../../Macaulay2/m2/system.m2:145:20-145:45:
setRandomSeed ZZ := seed -> randomSeed = seed
../../../../../Macaulay2/m2/system.m2:146:24-146:85:
setRandomSeed String := seed -> setRandomSeed fold((i
../../../../../Macaulay2/m2/system.m2:147:26-147:104:
setRandomSeed Sequence := seed -> if seed === () then
-------------------------------------------------------------------------------
--source code:
       -- magic assignment, calls rawSetRandomSeed internally
--source code:
,j) -> 101*i + j, 0, ascii seed)
 --source code:
 rawRandomInitialize() else setRandomSeed hash seed

Ways to use setRandomSeed:
==========================

  * "setRandomSeed(Sequence)"
  * "setRandomSeed(String)"
  * "setRandomSeed(ZZ)"

For the programmer
==================

The object setRandomSeed, is a method function with a single argument.

setup
*****

Synopsis
========

  * Usage:
        setup()
  * Consequences:
      * Initialization files for emacs and the standard command shells will
        have lines added to them to allow the Macaulay2 files to be found. A
        missing initialization file will be created only if doing so will not
        prevent the command shell from reading further initialization files.
        The user is prompted before each file is modified and offered the
        opportunity to review or reject the changes.

Description
===========

Backup files are made carefully, and if a mangled initialization file is
detected, it will not be modified. The lines added are bracketed by comment
lines containing the phrases Macaulay 2 start and Macaulay 2 end.

The initialization files will contain added commands that add the appropriate
directory to the front of the environment variable PATH so the program M2 can
be found, unless that directory already occurs in the path, in which case it
does not check whether that directory is the first one on the path containing a
program whose name is M2, for fear of escalating a competition with another
init file.  (The expert user may prefer to remove those commands and instead,
to create a symbolic link from a directory already on their path to the program
M2.)

The other environment variables affected are MANPATH, INFOPATH, and
LD_LIBRARY_PATH.

This function is intended to be run only by users, not by system
administrators, nor on behalf of users by system administrators, because system
administrators can easily install Macaulay2 in such a way that the files can
all be found.

Caveat
======

Warning: there is at least one important situation where you will not want to
run the Macaulay2 setup() command.  For example, suppose you have installed M2,
not in its own private location as described above, but in a directory with
many other executable files.  Suppose also that your account is adapted so it
will run programs correctly on hardware of more than one architecture, or on
differing operating systems, or even on various releases of the same operating
system.  Then setup() will modify your command shell init files so the
directory containing M2 will the first one searched when looking for a program.
If you then try to use your account on different hardware, incorrect programs
may be found, namely, those in the same directory as M2.  Similarly, incorrect
shareable libraries may also be found.

See also
========

  * setupEmacs

Ways to use setup:
==================

  * "setup()"

For the programmer
==================

The object setup, is a method function.

setupEmacs
**********

Synopsis
========

  * Usage:
        setupEmacs()
  * Consequences:
      * The initialization file for emacs (.emacs in your home directory) will
        have lines added to allow the Macaulay2 emacs mode to operate. The user
        is prompted before the file is modified and offered the opportunity to
        review or reject the change.

Description
===========

A backup files is made carefully, and if a mangled initialization file is
detected, it will not be modified. The lines added are bracketed by comment
lines containing the phrases Macaulay 2 start and Macaulay 2 end. The function
setup, does all this and more.

See also
========

  * setup
  * setting up the Macaulay2 emacs interface
  * using Macaulay2 with emacs

Ways to use setupEmacs:
=======================

  * "setupEmacs()"

For the programmer
==================

The object setupEmacs, is a method function.

setupLift -- set up lift from one ring to another
*************************************************

Synopsis
========

  * Usage:
        setupLift (f,R,S)
        setupLift g
  * Inputs:
      * f, a function,
      * R, a ring,
      * S, a ring,
      * g, a ring map,

Description
===========

There are two possible ways of implementing lift, using setupLift.
In the first one, we use a function:

+-----------------------------------------------------------------------------+
|i1 : R=QQ[x]                                                                 |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : S=QQ[y]                                                                 |
|                                                                             |
|o2 = S                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : setupPromote map(R,S,{x^2})                                             |
+-----------------------------------------------------------------------------+
|i4 : setupLift(a->sum(listForm a, (e,c)->if odd first e then error "not      |
|-----------------------------------------------------------------------------|
|liftable" else c*y^(first e//2)),R,S)                                        |
+-----------------------------------------------------------------------------+
|i5 : promote(y^2+2,R)                                                        |
|                                                                             |
|      4                                                                      |
|o5 = x  + 2                                                                  |
|                                                                             |
|o5 : R                                                                       |
+-----------------------------------------------------------------------------+
|i6 : lift(oo,S)                                                              |
|                                                                             |
|      2                                                                      |
|o6 = y  + 2                                                                  |
|                                                                             |
|o6 : S                                                                       |
+-----------------------------------------------------------------------------+
|i7 : lift(x,S,Verify=>false)                                                 |
+-----------------------------------------------------------------------------+

In the second one, we define a ring map which is a partial inverse to the
promotion map:

+------------------------------------------+
|i8 : R=QQ[x,y]                            |
|                                          |
|o8 = R                                    |
|                                          |
|o8 : PolynomialRing                       |
+------------------------------------------+
|i9 : S=R[s]                               |
|                                          |
|o9 = S                                    |
|                                          |
|o9 : PolynomialRing                       |
+------------------------------------------+
|i10 : setupPromote map(R,S,{x+y})         |
+------------------------------------------+
|i11 : setupLift map(S,R,{s,0})            |
+------------------------------------------+
|i12 : promote(s^3+2*s-1,R)                |
|                                          |
|       3     2        2    3              |
|o12 = x  + 3x y + 3x*y  + y  + 2x + 2y - 1|
|                                          |
|o12 : R                                   |
+------------------------------------------+
|i13 : lift(oo,S)                          |
|                                          |
|       3                                  |
|o13 = s  + 2s - 1                         |
|                                          |
|o13 : S                                   |
+------------------------------------------+
|i14 : lift(x,S,Verify=>false)             |
+------------------------------------------+

See also
========

  * setupPromote -- set up promote from one ring to
    another

Ways to use setupLift:
======================

  * "setupLift(Function,Ring,Ring)"
  * "setupLift(RingMap)"

For the programmer
==================

The object setupLift, is a method function.

setupPromote -- set up promote from one ring to another
*******************************************************

Synopsis
========

  * Usage:
        setupPromote f
  * Inputs:
      * f, a ring map,

Description
===========

This defines promotion from one ring to another as the application of a ring
map. After calling setupPromote, any operation that is given an element of the
source of f but expects an element of the target of f will automatically
promote, it by applying f.

+---------------------------------------------+
|i1 : R=QQ[x_1,x_2]                           |
|                                             |
|o1 = R                                       |
|                                             |
|o1 : PolynomialRing                          |
+---------------------------------------------+
|i2 : R'=QQ[e_1,e_2,Degrees=>{1,2}]           |
|                                             |
|o2 = R'                                      |
|                                             |
|o2 : PolynomialRing                          |
+---------------------------------------------+
|i3 : setupPromote map(R,R',{x_1+x_2,x_1*x_2})|
+---------------------------------------------+
|i4 : promote(e_1^2,R)                        |
|                                             |
|      2            2                         |
|o4 = x  + 2x x  + x                          |
|      1     1 2    2                         |
|                                             |
|o4 : R                                       |
+---------------------------------------------+
|i5 : e_1*x_1                                 |
|                                             |
|      2                                      |
|o5 = x  + x x                                |
|      1    1 2                               |
|                                             |
|o5 : R                                       |
+---------------------------------------------+
|i6 : e_2==x_1*x_2                            |
|                                             |
|o6 = true                                    |
+---------------------------------------------+

See also
========

  * setupLift -- set up lift from one ring to another

Ways to use setupPromote:
=========================

  * "setupPromote(RingMap)"

For the programmer
==================

The object setupPromote, is a method function.

shield -- shield evaluation from interrupts
*******************************************

Description
===========

shield x -- executes the expression x, temporarily ignoring interrupts.

For the programmer
==================

The object shield, is a keyword.

show -- display various objects in an external viewer
*****************************************************

Synopsis
========

  * Usage:
        show x
  * Inputs:
      * x, a markup list (Text), an instance of the type
        TEX (Text), or an instance of the type URL,
  * Consequences:
      * An external viewer, such as a web browser or PDF viewer, is started to
        view the object x

Description
===========

The functions showTex and showHtml are specializations of the show method which
first convert x to a TEX (Text), or Hypertext (Text),
object, respectively, and display that result.

For example, the following lines would display a matrix in a browser or PDF
viewer:

+-----------------------------------------------------------------------------+
|i1 : showTex matrix{{1,2,3},{4,5,6}}                                         |
|+ cd /tmp/M2-95678-0/0/                                                      |
|+ pdflatex -interaction=batchmode show                                       |
|This is pdfTeX, Version 3.14159265-2.6-1.40.21 (TeX Live 2020) (preloaded    |
|restricted \write18 enabled.                                                 |
|entering extended mode                                                       |
|-----------------------------------------------------------------------------|
|format=pdflatex)                                                             |
+-----------------------------------------------------------------------------+
|i2 : showHtml matrix{{1,2,3},{4,5,6}}                                        |
|Opening in existing browser session.                                         |
+-----------------------------------------------------------------------------+

By default, the viewer is determined by either open on macOS or xdg-open on
Linux distributions. As backup for when neither open nor xdg-open is available,
the environmental variable WWWBROWSER or firefox is used.

Caveat
======

No attempt is made to wrap large matrices or equations. The code for this
function is Unix dependent at the moment, requiring that certain commands like
pdflatex are present.

See also
========

  * tex -- convert to $\TeX$ format
  * texMath -- convert to TeX math format
  * html -- convert to HTML format

Ways to use show:
=================

  * "show(URL)"

For the programmer
==================

The object show, is a method function.

showClassStructure -- display class structure
*********************************************

Description
===========

Synopsis
========

  * Usage:
        showClassStructure
  * Outputs:
      * a display of the class structure of all objects assigned to global
        variables

Synopsis
========

  * Usage:
        showClassStructure (x,y,...)
  * Inputs:
      * x
      * y
  * Outputs:
      * a display of the class structure of objects specified

Each object is displayed to the right of its class.

+---------------------------------------------------------------+
|i1 : showClassStructure                                        |
|                                                               |
|o1 = Type : AffineVariety                                      |
|            AngleBarList                                       |
|            Array                                              |
|            AssociativeExpression                              |
|            AtomicInt                                          |
|            BasicList                                          |
|            BettiTally                                         |
|            Boolean : false                                    |
|                      true                                     |
|            CacheFunction                                      |
|            CacheTable                                         |
|            CC                                                 |
|              *                                                |
|            ChainComplex                                       |
|            ChainComplexMap                                    |
|            CoherentSheaf                                      |
|            CompiledFunction : addCancelTask                   |
|                               addDependencyTask               |
|                               addStartTask                    |
|                               alarm                           |
|                               ancestor                        |
|                               any                             |
|                               append                          |
|                               apply                           |
|                               applyKeys                       |
|                               applyPairs                      |
|                               applyValues                     |
|                               ascii                           |
|                               atEndOfFile                     |
|                               cancelTask                      |
|                               changeDirectory                 |
|                               characters                      |
|                               class                           |
|                               clearEcho                       |
|                               collectGarbage                  |
|                               combine                         |
|                               commandInterpreter              |
|                               concatenate                     |
|                               connectionCount                 |
|                               copy                            |
|                               cpuTime                         |
|                               createTask                      |
|                               currentColumnNumber             |
|                               currentDirectory                |
|                               currentRowNumber                |
|                               currentTime                     |
|                               deepSplice                      |
|                               difference                      |
|                               disassemble                     |
|                               drop                            |
|                               echoOff                         |
|                               echoOn                          |
|                               erase                           |
|                               exec                            |
|                               fileExecutable                  |
|                               fileExists                      |
|                               fileLength                      |
|                               fileMode                        |
|                               fileReadable                    |
|                               fileTime                        |
|                               fileWritable                    |
|                               firstkey                        |
|                               flagLookup                      |
|                               fork                            |
|                               frames                          |
|                               functionBody                    |
|                               GCstats                         |
|                               get                             |
|                               getc                            |
|                               getenv                          |
|                               getGlobalSymbol                 |
|                               getIOThreadMode                 |
|                               getNetFile                      |
|                               groupID                         |
|                               hash                            |
|                               hashTable                       |
|                               horizontalJoin                  |
|                               identity                        |
|                               installMethod                   |
|                               instance                        |
|                               isANumber                       |
|                               isCanceled                      |
|                               isDirectory                     |
|                               isGlobalSymbol                  |
|                               isInputFile                     |
|                               isListener                      |
|                               isMutable                       |
|                               isOpen                          |
|                               isOutputFile                    |
|                               isReady                         |
|                               isRegularFile                   |
|                               join                            |
|                               keys                            |
|                               kill                            |
|                               left                            |
|                               limitFiles                      |
|                               limitProcesses                  |
|                               linkFile                        |
|                               localDictionaries               |
|                               lookup                          |
|                               lookupCount                     |
|                               merge                           |
|                               mergePairs                      |
|                               midpoint                        |
|                               mingle                          |
|                               minimizeFilename                |
|                               minus                           |
|                               mkdir                           |
|                               nanosleep                       |
|                               newClass                        |
|                               newNetFile                      |
|                               nextkey                         |
|                               openDatabase                    |
|                               openDatabaseOut                 |
|                               openFiles                       |
|                               openIn                          |
|                               openInOut                       |
|                               openListener                    |
|                               openOut                         |
|                               openOutAppend                   |
|                               override                        |
|                               pairs                           |
|                               parent                          |
|                               plus                            |
|                               power                           |
|                               powermod                        |
|                               prepend                         |
|                               printString                     |
|                               processID                       |
|                               protect                         |
|                               pseudocode                      |
|                               read                            |
|                               readDirectory                   |
|                               readlink                        |
|                               realpath                        |
|                               recursionDepth                  |
|                               relativizeFilename              |
|                               remove                          |
|                               removeDirectory                 |
|                               removeFile                      |
|                               reorganize                      |
|                               reverse                         |
|                               right                           |
|                               run                             |
|                               scan                            |
|                               scanPairs                       |
|                               schedule                        |
|                               selectPairs                     |
|                               sequence                        |
|                               serialNumber                    |
|                               set                             |
|                               setEcho                         |
|                               setGroupID                      |
|                               setIOExclusive                  |
|                               setIOSynchronized               |
|                               setIOUnSynchronized             |
|                               size2                           |
|                               sleep                           |
|                               splice                          |
|                               stack                           |
|                               substring                       |
|                               symbolBody                      |
|                               symlinkFile                     |
|                               take                            |
|                               tally                           |
|                               taskResult                      |
|                               times                           |
|                               toCC                            |
|                               toRR                            |
|                               toRRi                           |
|                               toSequence                      |
|                               uncurry                         |
|                               unsequence                      |
|                               unstack                         |
|                               utf8                            |
|                               utf8check                       |
|                               utf8substring                   |
|                               values                          |
|                               wait                            |
|                               wrap                            |
|                               youngest                        |
|            CompiledFunctionBody                               |
|            CompiledFunctionClosure                            |
|            ComplexField                                       |
|            Cone                                               |
|            Constant : CatalanConstant                         |
|                       EulerConstant                           |
|                       ii                                      |
|                       pi                                      |
|            Database                                           |
|            Descent                                            |
|            Dictionary                                         |
|            DocumentTag                                        |
|            EngineRing                                         |
|            Expression                                         |
|            Fan                                                |
|            File : stdio                                       |
|            FilePosition                                       |
|            FractionField                                      |
|            Function                                           |
|            FunctionBody                                       |
|            FunctionClosure : addEndFunction                   |
|                              ancestors                        |
|                              applicationDirectory             |
|                              applyTable                       |
|                              baseFilename                     |
|                              beginDocumentation               |
|                              benchmark                        |
|                              cacheValue                       |
|                              centerString                     |
|                              columnate                        |
|                              currentPosition                  |
|                              demark                           |
|                              End                              |
|                              error                            |
|                              even                             |
|                              first                            |
|                              getNonUnit                       |
|                              getSymbol                        |
|                              globalAssign                     |
|                              globalAssignFunction             |
|                              globalAssignment                 |
|                              globalReleaseFunction            |
|                              input                            |
|                              installedPackages                |
|                              installMinprimes                 |
|                              inversePermutation               |
|                              isFinitePrimeField               |
|                              isPrimitive                      |
|                              isTable                          |
|                              last                             |
|                              lines                            |
|                              load                             |
|                              memoizeClear                     |
|                              memoizeValues                    |
|                              method                           |
|                              mod                              |
|                              monomialCurveIdeal               |
|                              needs                            |
|                              notImplemented                   |
|                              number                           |
|                              odd                              |
|                              on                               |
|                              pager                            |
|                              peek                             |
|                              print                            |
|                              printerr                         |
|                              same                             |
|                              seeParsing                       |
|                              showHtml                         |
|                              showTex                          |
|                              stashValue                       |
|                              subtable                         |
|                              synonym                          |
|                              syzygyScheme                     |
|                              table                            |
|                              temporaryFileName                |
|                              toAbsolutePath                   |
|                              toLower                          |
|                              toUpper                          |
|                              tutorial                         |
|                              uniform                          |
|                              uninstallAllPackages             |
|                              userSymbols                      |
|                              zero                             |
|            GaloisField                                        |
|            GeneralOrderedMonoid                               |
|            GlobalDictionary : PackageDictionary               |
|            GradedModule                                       |
|            GradedModuleMap                                    |
|            GroebnerBasis                                      |
|            GroebnerBasisOptions                               |
|            HashTable                                          |
|            HeaderType : Adjacent                              |
|                         BinaryOperation                       |
|                         Divide                                |
|                         Equation                              |
|                         FunctionApplication                   |
|                         MapExpression                         |
|                         MatrixExpression                      |
|                         Power                                 |
|                         RowExpression                         |
|                         SparseMonomialVectorExpression        |
|                         SparseVectorExpression                |
|                         Subscript                             |
|                         Superscript                           |
|                         Table                                 |
|                         VectorExpression                      |
|            Ideal                                              |
|            ImmutableType                                      |
|            IndeterminateNumber : indeterminate                |
|            IndexedVariable                                    |
|            IndexedVariableTable                               |
|            InexactField                                       |
|            InexactFieldFamily : CC                            |
|                                 RR                            |
|                                 RRi                           |
|            InexactNumber                                      |
|            InexactNumber                                      |
|                         *                                     |
|            InfiniteNumber : infinity                          |
|            Keyword                                            |
|            List                                               |
|            LocalDictionary                                    |
|            Manipulator : close                                |
|                          closeIn                              |
|                          closeOut                             |
|                          endl                                 |
|                          flush                                |
|            Matrix                                             |
|            MethodFunction : abs                               |
|                             accumulate                        |
|                             acos                              |
|                             acosh                             |
|                             acot                              |
|                             acoth                             |
|                             addCone                           |
|                             addPolyhedron                     |
|                             adjoint'                          |
|                             affineHull                        |
|                             affineImage                       |
|                             affinePreimage                    |
|                             agm                               |
|                             all                               |
|                             ambDim                            |
|                             ambient                           |
|                             antipode                          |
|                             apropos                           |
|                             areCompatible                     |
|                             arXiv                             |
|                             asin                              |
|                             asinh                             |
|                             assert                            |
|                             atan                              |
|                             atan2                             |
|                             atanh                             |
|                             autoload                          |
|                             barycentricTriangulation          |
|                             baseName                          |
|                             baseRing                          |
|                             BesselJ                           |
|                             BesselY                           |
|                             Beta                              |
|                             between                           |
|                             binomial                          |
|                             bipyramid                         |
|                             borel                             |
|                             ccRefinement                      |
|                             ceiling                           |
|                             cellDecompose                     |
|                             changeBase                        |
|                             char                              |
|                             chi                               |
|                             clean                             |
|                             coefficient                       |
|                             coefficientRing                   |
|                             coimage                           |
|                             cokernel                          |
|                             columnAdd                         |
|                             columnMult                        |
|                             columnPermute                     |
|                             columnRankProfile                 |
|                             columnSwap                        |
|                             commonFace                        |
|                             commonRing                        |
|                             comodule                          |
|                             compareExchange                   |
|                             complement                        |
|                             complete                          |
|                             components                        |
|                             compositions                      |
|                             compress                          |
|                             conductor                         |
|                             cone                              |
|                             coneFromHData                     |
|                             coneFromVData                     |
|                             cones                             |
|                             conjugate                         |
|                             contains                          |
|                             content                           |
|                             contract                          |
|                             contract'                         |
|                             convexHull                        |
|                             cos                               |
|                             cosh                              |
|                             cot                               |
|                             coth                              |
|                             cover                             |
|                             coverMap                          |
|                             crossPolytope                     |
|                             csc                               |
|                             csch                              |
|                             cyclicPolytope                    |
|                             debug                             |
|                             default                           |
|                             degree                            |
|                             degreeGroup                       |
|                             degreeLength                      |
|                             degrees                           |
|                             degreesMonoid                     |
|                             degreesRing                       |
|                             delete                            |
|                             denominator                       |
|                             depth                             |
|                             diagonalMatrix                    |
|                             diameter                          |
|                             dictionary                        |
|                             diff                              |
|                             diff'                             |
|                             Digamma                           |
|                             dim                               |
|                             directProduct                     |
|                             dismiss                           |
|                             divideByVariable                  |
|                             doc                               |
|                             dualCone                          |
|                             dualFaceRepresentationMap         |
|                             eagonNorthcott                    |
|                             effCone                           |
|                             effGenerators                     |
|                             ehrhart                           |
|                             eint                              |
|                             elements                          |
|                             eliminate                         |
|                             emptyPolyhedron                   |
|                             endPackage                        |
|                             entries                           |
|                             erf                               |
|                             erfc                              |
|                             euler                             |
|                             eulers                            |
|                             exchange                          |
|                             exp                               |
|                             expectedReesIdeal                 |
|                             expm1                             |
|                             exponents                         |
|                             exportFrom                        |
|                             faceFan                           |
|                             faces                             |
|                             facesAsCones                      |
|                             facesAsPolyhedra                  |
|                             facets                            |
|                             fan                               |
|                             fanFromGfan                       |
|                             Fano                              |
|                             findSynonyms                      |
|                             fittingIdeal                      |
|                             flip                              |
|                             floor                             |
|                             fold                              |
|                             formation                         |
|                             frac                              |
|                             fraction                          |
|                             fromDividedPowers                 |
|                             fVector                           |
|                             Gamma                             |
|                             gbRemove                          |
|                             gbSnapshot                        |
|                             gcdCoefficients                   |
|                             genera                            |
|                             generateAssertions                |
|                             generator                         |
|                             genericMatrix                     |
|                             genericSkewMatrix                 |
|                             genericSymmetricMatrix            |
|                             genus                             |
|                             getChangeMatrix                   |
|                             getWWW                            |
|                             gramm                             |
|                             halfspaces                        |
|                             headlines                         |
|                             heft                              |
|                             height                            |
|                             hilbertFunction                   |
|                             hirzebruch                        |
|                             homogenize                        |
|                             homomorphism                      |
|                             httpHeaders                       |
|                             hypercube                         |
|                             hyperplanes                       |
|                             icFractions                       |
|                             icMap                             |
|                             icPIdeal                          |
|                             image                             |
|                             imageFan                          |
|                             imaginaryPart                     |
|                             importFrom                        |
|                             incompCones                       |
|                             incompPolyhedra                   |
|                             index                             |
|                             indices                           |
|                             inducesWellDefinedMap             |
|                             inInterior                        |
|                             insert                            |
|                             installAssignmentMethod           |
|                             installHilbertFunction            |
|                             instances                         |
|                             integrate                         |
|                             interiorLatticePoints             |
|                             interiorPoint                     |
|                             interiorVector                    |
|                             inverse                           |
|                             inverseErf                        |
|                             inverseRegularizedBeta            |
|                             inverseRegularizedGamma           |
|                             irreducibleCharacteristicSeries   |
|                             irreducibleDecomposition          |
|                             isAffineRing                      |
|                             isBorel                           |
|                             isc                               |
|                             isCommutative                     |
|                             isCompact                         |
|                             isComplete                        |
|                             isConstant                        |
|                             isDirectSum                       |
|                             isEmpty                           |
|                             isFace                            |
|                             isField                           |
|                             isFinite                          |
|                             isFreeModule                      |
|                             isFullDimensional                 |
|                             isHomogeneous                     |
|                             isIdeal                           |
|                             isInfinite                        |
|                             isInjective                       |
|                             isIsomorphism                     |
|                             isLatticePolytope                 |
|                             isLiftable                        |
|                             isMember                          |
|                             isModule                          |
|                             isMonomialIdeal                   |
|                             isNormal                          |
|                             isPointed                         |
|                             isPolynomialRing                  |
|                             isPolytopal                       |
|                             isProjective                      |
|                             isPure                            |
|                             isQuotientModule                  |
|                             isQuotientOf                      |
|                             isQuotientRing                    |
|                             isReal                            |
|                             isRing                            |
|                             isSimplicial                      |
|                             isSkewCommutative                 |
|                             isSquareFree                      |
|                             isStandardGradedPolynomialRing    |
|                             isSubmodule                       |
|                             isSubquotient                     |
|                             isSubset                          |
|                             isSupportedInZeroLocus            |
|                             isSurjective                      |
|                             isUnit                            |
|                             isWellDefined                     |
|                             isWeylAlgebra                     |
|                             jacobian                          |
|                             kernelOfLocalization              |
|                             koszul                            |
|                             latticePoints                     |
|                             latticeVolume                     |
|                             leadCoefficient                   |
|                             leadComponent                     |
|                             leadMonomial                      |
|                             leadTerm                          |
|                             liftable                          |
|                             linealitySpace                    |
|                             linearTransform                   |
|                             linSpace                          |
|                             listForm                          |
|                             listSymbols                       |
|                             lngamma                           |
|                             log                               |
|                             log1p                             |
|                             LUdecomposition                   |
|                             makeDirectory                     |
|                             maxCones                          |
|                             maxFace                           |
|                             maxPolyhedra                      |
|                             memoize                           |
|                             methodOptions                     |
|                             minFace                           |
|                             minimalNonFaces                   |
|                             minimize                          |
|                             minkowskiSum                      |
|                             minkSummandCone                   |
|                             mixedVolume                       |
|                             module                            |
|                             monomialSubideal                  |
|                             multidegree                       |
|                             multigraded                       |
|                             nefCone                           |
|                             nefGenerators                     |
|                             newCoordinateSystem               |
|                             newtonPolytope                    |
|                             next                              |
|                             nextPrime                         |
|                             norm                              |
|                             normalFan                         |
|                             nullhomotopy                      |
|                             nullSpace                         |
|                             numColumns                        |
|                             numerator                         |
|                             numeric                           |
|                             numericInterval                   |
|                             numgens                           |
|                             numRows                           |
|                             nVertices                         |
|                             objectiveVector                   |
|                             ofClass                           |
|                             pack                              |
|                             packageTemplate                   |
|                             pad                               |
|                             part                              |
|                             partition                         |
|                             partitions                        |
|                             parts                             |
|                             pdim                              |
|                             peek'                             |
|                             permanents                        |
|                             permutations                      |
|                             pfaffians                         |
|                             pivots                            |
|                             poincare                          |
|                             poincareN                         |
|                             polar                             |
|                             polarFace                         |
|                             poly                              |
|                             polyhedra                         |
|                             polyhedralComplex                 |
|                             polyhedron                        |
|                             polyhedronFromHData               |
|                             polytope                          |
|                             positions                         |
|                             posOrthant                        |
|                             precision                         |
|                             preimage                          |
|                             presentation                      |
|                             product                           |
|                             profile                           |
|                             Proj                              |
|                             projectiveHilbertPolynomial       |
|                             promote                           |
|                             proximum                          |
|                             pseudoRemainder                   |
|                             pushout                           |
|                             pyramid                           |
|                             QRDecomposition                   |
|                             quotient'                         |
|                             quotientRemainder                 |
|                             quotientRemainder'                |
|                             randomKRationalPoint              |
|                             rank                              |
|                             realPart                          |
|                             reducedRowEchelonForm             |
|                             reduceHilbert                     |
|                             reductionNumber                   |
|                             registerFinalizer                 |
|                             regularizedBeta                   |
|                             regularizedGamma                  |
|                             regularSubdivision                |
|                             regularTriangulation              |
|                             relations                         |
|                             remainder                         |
|                             remainder'                        |
|                             removeLowestDimension             |
|                             reshape                           |
|                             ring                              |
|                             rotate                            |
|                             round                             |
|                             rowAdd                            |
|                             rowMult                           |
|                             rowPermute                        |
|                             rowRankProfile                    |
|                             rowSwap                           |
|                             saveSession                       |
|                             scanKeys                          |
|                             scanLines                         |
|                             scanValues                        |
|                             schreyerOrder                     |
|                             searchPath                        |
|                             sec                               |
|                             sech                              |
|                             secondaryPolytope                 |
|                             selectInSubring                   |
|                             selectKeys                        |
|                             selectValues                      |
|                             selectVariables                   |
|                             setup                             |
|                             setupEmacs                        |
|                             setupLift                         |
|                             setupPromote                      |
|                             sheaf                             |
|                             sheafMap                          |
|                             show                              |
|                             simplex                           |
|                             sin                               |
|                             singularLocus                     |
|                             sinh                              |
|                             size                              |
|                             skeleton                          |
|                             smallestFace                      |
|                             smoothSubfan                      |
|                             someTerms                         |
|                             source                            |
|                             Spec                              |
|                             splitWWW                          |
|                             sqrt                              |
|                             stacksProject                     |
|                             standardForm                      |
|                             standardPairs                     |
|                             stanleyReisnerRing                |
|                             statePolytope                     |
|                             stdSimplex                        |
|                             stellarSubdivision                |
|                             store                             |
|                             sublatticeBasis                   |
|                             sublists                          |
|                             submatrix                         |
|                             submatrix'                        |
|                             submatrixByDegrees                |
|                             subquotient                       |
|                             subsets                           |
|                             substitute                        |
|                             sum                               |
|                             super                             |
|                             support                           |
|                             switch                            |
|                             sylvesterMatrix                   |
|                             symmetricPower                    |
|                             tailCone                          |
|                             tan                               |
|                             tanh                              |
|                             target                            |
|                             tensorAssociativity               |
|                             terms                             |
|                             testHunekeQuestion                |
|                             tests                             |
|                             toDividedPowers                   |
|                             toField                           |
|                             topCoefficients                   |
|                             topComponents                     |
|                             toSublattice                      |
|                             trace                             |
|                             triangulate                       |
|                             truncateOutput                    |
|                             ultimate                          |
|                             unbag                             |
|                             uniquePermutations                |
|                             urlEncode                         |
|                             value                             |
|                             variety                           |
|                             vector                            |
|                             versalEmbedding                   |
|                             vertexEdgeMatrix                  |
|                             vertexFacetMatrix                 |
|                             vertices                          |
|                             volume                            |
|                             wedgeProduct                      |
|                             weightRange                       |
|                             whichGm                           |
|                             width                             |
|                             wikipedia                         |
|                             zeta                              |
|            MethodFunctionBinary : gcd                         |
|                                   intersect                   |
|                                   lcm                         |
|                                   tensor                      |
|                                   union                       |
|            MethodFunctionSingle : chainComplex                |
|                                   code                        |
|                                   commonest                   |
|                                   describe                    |
|                                   directSum                   |
|                                   document                    |
|                                   EXAMPLE                     |
|                                   examples                    |
|                                   export                      |
|                                   exportMutable               |
|                                   expression                  |
|                                   flatten                     |
|                                   format                      |
|                                   gradedModule                |
|                                   gradedModuleMap             |
|                                   hold                        |
|                                   hooks                       |
|                                   html                        |
|                                   hypertext                   |
|                                   ideal                       |
|                                   info                        |
|                                   isSorted                    |
|                                   iterator                    |
|                                   length                      |
|                                   locate                      |
|                                   makeDocumentTag             |
|                                   makePackageIndex            |
|                                   mathML                      |
|                                   max                         |
|                                   maxPosition                 |
|                                   methods                     |
|                                   min                         |
|                                   minPosition                 |
|                                   monoid                      |
|                                   monomialIdeal               |
|                                   net                         |
|                                   newPackage                  |
|                                   options                     |
|                                   package                     |
|                                   pretty                      |
|                                   regexQuote                  |
|                                   runLengthEncode             |
|                                   setRandomSeed               |
|                                   span                        |
|                                   SYNOPSIS                    |
|                                   tex                         |
|                                   texMath                     |
|                                   toExternalString            |
|                                   toList                      |
|                                   toString                    |
|                                   transpose                   |
|                                   undocumented                |
|                                   unique                      |
|                                   use                         |
|                                   vars                        |
|            MethodFunctionWithOptions : about                  |
|                                        addHook                |
|                                        adjoint                |
|                                        analyticSpread         |
|                                        annihilator            |
|                                        associatedGradedRing   |
|                                        associatedPrimes       |
|                                        basis                  |
|                                        betti                  |
|                                        canonicalBundle        |
|                                        capture                |
|                                        check                  |
|                                        checkDegrees           |
|                                        codim                  |
|                                        coefficients           |
|                                        cohomology             |
|                                        compose                |
|                                        conwayPolynomial       |
|                                        copyDirectory          |
|                                        copyFile               |
|                                        cotangentSheaf         |
|                                        decompose              |
|                                        determinant            |
|                                        discriminant           |
|                                        distinguished          |
|                                        dual                   |
|                                        eigenvalues            |
|                                        eigenvectors           |
|                                        extend                 |
|                                        exteriorPower          |
|                                        factor                 |
|                                        fillMatrix             |
|                                        findFiles              |
|                                        findHeft               |
|                                        findProgram            |
|                                        flattenRing            |
|                                        forceGB                |
|                                        fromDual               |
|                                        gb                     |
|                                        gcdLLL                 |
|                                        generators             |
|                                        getPrimeWithRootOfUnity|
|                                        GF                     |
|                                        graphIdeal             |
|                                        graphRing              |
|                                        Grassmannian           |
|                                        groebnerBasis          |
|                                        hermite                |
|                                        hilbertBasis           |
|                                        hilbertPolynomial      |
|                                        hilbertSeries          |
|                                        Hom                    |
|                                        homology               |
|                                        homomorphism'          |
|                                        icFracP                |
|                                        idealizer              |
|                                        independentSets        |
|                                        inducedMap             |
|                                        installPackage         |
|                                        integralClosure        |
|                                        intersectInP           |
|                                        intersection           |
|                                        interval               |
|                                        inverseSystem          |
|                                        isIsomorphic           |
|                                        isLinearType           |
|                                        isLLL                  |
|                                        isPrimary              |
|                                        isPrime                |
|                                        isPseudoprime          |
|                                        isReduction            |
|                                        isReflexive            |
|                                        isSmooth               |
|                                        isVeryAmple            |
|                                        jacobianDual           |
|                                        kernel                 |
|                                        kernelLLL              |
|                                        lift                   |
|                                        LLL                    |
|                                        loadPackage            |
|                                        localize               |
|                                        makeS2                 |
|                                        map                    |
|                                        markedGB               |
|                                        match                  |
|                                        matrix                 |
|                                        mingens                |
|                                        minimalBetti           |
|                                        minimalPresentation    |
|                                        minimalPrimes          |
|                                        minimalReduction       |
|                                        minors                 |
|                                        modulo                 |
|                                        monomials              |
|                                        moveFile               |
|                                        multiplicity           |
|                                        mutableIdentity        |
|                                        mutableMatrix          |
|                                        needsPackage           |
|                                        netList                |
|                                        newRing                |
|                                        normalCone             |
|                                        oeis                   |
|                                        parallelApply          |
|                                        polarize               |
|                                        position               |
|                                        primaryComponent       |
|                                        primaryDecomposition   |
|                                        prune                  |
|                                        pullback               |
|                                        pushForward            |
|                                        quotient               |
|                                        radical                |
|                                        radicalContainment     |
|                                        random                 |
|                                        randomMutableMatrix    |
|                                        rays                   |
|                                        readPackage            |
|                                        reesAlgebra            |
|                                        reesIdeal              |
|                                        regex                  |
|                                        regSeqInIdeal          |
|                                        regularity             |
|                                        replace                |
|                                        resolution             |
|                                        resultant              |
|                                        ringFromFractions      |
|                                        roots                  |
|                                        rsort                  |
|                                        runHooks               |
|                                        runProgram             |
|                                        saturate               |
|                                        Schubert               |
|                                        select                 |
|                                        separate               |
|                                        sheafHom               |
|                                        simpleDocFrob          |
|                                        smithNormalForm        |
|                                        solve                  |
|                                        sort                   |
|                                        sortColumns            |
|                                        specialFiber           |
|                                        specialFiberIdeal      |
|                                        status                 |
|                                        SVD                    |
|                                        symlinkDirectory       |
|                                        symmetricAlgebra       |
|                                        symmetricAlgebraIdeal  |
|                                        symmetricKernel        |
|                                        syz                    |
|                                        tangentCone            |
|                                        tangentSheaf           |
|                                        toDual                 |
|                                        trim                   |
|                                        truncate               |
|                                        uninstallPackage       |
|            Module                                             |
|            Monoid                                             |
|            MonoidElement                                      |
|            MonomialIdeal                                      |
|            MultigradedBettiTally                              |
|            MutableHashTable                                   |
|            MutableList                                        |
|            MutableMatrix                                      |
|            Net                                                |
|            NetFile                                            |
|            Nothing                                            |
|            Number                                             |
|            OneExpression                                      |
|            Option                                             |
|            OptionTable                                        |
|            OrderedMonoid                                      |
|            Package : Classic                                  |
|                      Complexes                                |
|                      ConwayPolynomials                        |
|                      Core                                     |
|                      Elimination                              |
|                      FourierMotzkin                           |
|                      GenericInitialIdeal                      |
|                      IntegralClosure                          |
|                      InverseSystems                           |
|                      Isomorphism                              |
|                      LLLBases                                 |
|                      Macaulay2Doc                             |
|                      MinimalPrimes                            |
|                      OnlineLookup                             |
|                      PackageCitations                         |
|                      Parsing                                  |
|                      Polyhedra                                |
|                      PrimaryDecomposition                     |
|                      ReesAlgebra                              |
|                      Saturation                               |
|                      SimpleDoc                                |
|                      SimplicialComplexes                      |
|                      TangentCone                              |
|                      Text                                     |
|                      Topcom                                   |
|                      Truncations                              |
|                      User                                     |
|                      Varieties                                |
|            Partition                                          |
|            PolyhedralComplex                                  |
|            PolyhedralObject                                   |
|            Polyhedron                                         |
|            PolynomialRing                                     |
|            Program                                            |
|            ProgramRun                                         |
|            ProjectiveHilbertPolynomial                        |
|            ProjectiveVariety                                  |
|            Pseudocode                                         |
|            PseudocodeClosure                                  |
|            QuotientRing                                       |
|            RealField                                          |
|            Resolution                                         |
|            Ring : QQ                                          |
|                   ZZ                                          |
|            RingElement                                        |
|            RingFamily                                         |
|            RingMap                                            |
|            RR                                                 |
|              *                                                |
|            RRi                                                |
|               *                                               |
|            ScriptedFunctor : Ext                              |
|                              HH                               |
|                              hh                               |
|                              id                               |
|                              OO                               |
|                              sheafExt                         |
|                              Tor                              |
|            SelfInitializingType : Bag                         |
|                                   Command : cite              |
|                                             clearAll          |
|                                             clearOutput       |
|                                             copyright         |
|                                             edit              |
|                                             exit              |
|                                             help              |
|                                             infoHelp          |
|                                             listLocalSymbols  |
|                                             listUserSymbols   |
|                                             profileSummary    |
|                                             quit              |
|                                             restart           |
|                                             showClassStructure|
|                                             showStructure     |
|                                             showUserStructure |
|                                             viewHelp          |
|                                   Eliminate                   |
|                                   Hybrid                      |
|                                   Iterator                    |
|                                   LowerBound                  |
|                                   NumberedVerticalList        |
|                                   ProductOrder                |
|                                   TestInput                   |
|                                   URL                         |
|                                   VerticalList                |
|            Sequence                                           |
|            Set                                                |
|            SheafMap                                           |
|            SheafOfRings                                       |
|            String                                             |
|            SumOfTwists                                        |
|            Symbol                                             |
|            SymbolBody                                         |
|            Tally                                              |
|            Task                                               |
|            Thing                                              |
|            Time                                               |
|            Variety                                            |
|            Vector                                             |
|            VirtualTally                                       |
|            VisibleList                                        |
|            WrapperType : Describe                             |
|                          DirectSum                            |
|                          Holder                               |
|                          Minus                                |
|                          Parenthesize                         |
|                          Product                              |
|                          SheafExpression                      |
|                          Sum                                  |
|                          TensorProduct                        |
|            ZeroExpression                                     |
|                                                               |
|o1 : Descent                                                   |
+---------------------------------------------------------------+

See also
========

  * showStructure -- display parent structure
  * showUserStructure -- show parent structure for
    those types defined by user

For the programmer
==================

The object showClassStructure, is a command.

showStructure -- display parent structure
*****************************************

Description
===========

Synopsis
========

  * Usage:
        showStructure
  * Outputs:
      * a display of the parent structure of all types assigned to global
        variables

Synopsis
========

  * Usage:
        showStructure (X,Y,...)
  * Inputs:
      * X, a type,
      * Y, a type,
  * Outputs:
      * a display of the class structure of the types specified

Each such type is displayed to the right of its parent.

A type is an instance of Type, by definition.

+-----------------------------------------------------------------------------+
|i1 : showStructure                                                           |
|                                                                             |
|o1 = Thing : AtomicInt                                                       |
|             BasicList : Command                                             |
|                         Eliminate                                           |
|                         Expression : Adjacent                               |
|                                      AssociativeExpression : DirectSum      |
|                                                              Equation       |
|                                                              Product        |
|                                                              Sum            |
|                                                              TensorProduct  |
|                                      BinaryOperation                        |
|                                      Divide                                 |
|                                      FunctionApplication                    |
|                                      Holder : Describe                      |
|                                               OneExpression                 |
|                                               Parenthesize                  |
|                                               ZeroExpression                |
|                                      MapExpression                          |
|                                      MatrixExpression                       |
|                                      Minus                                  |
|                                      Power                                  |
|                                      RowExpression                          |
|                                      SheafExpression                        |
|                                      SparseMonomialVectorExpression         |
|                                      SparseVectorExpression                 |
|                                      Subscript                              |
|                                      Superscript                            |
|                                      Table                                  |
|                                      VectorExpression                       |
|                         FilePosition                                        |
|                         IndexedVariable                                     |
|                         LowerBound                                          |
|                         Manipulator                                         |
|                         MutableList : Bag                                   |
|                         Option                                              |
|                         Partition                                           |
|                         ProductOrder                                        |
|                         RingElement                                         |
|                         SumOfTwists                                         |
|                         Time                                                |
|                         URL                                                 |
|                         Vector                                              |
|                         VisibleList : AngleBarList                          |
|                                       Array                                 |
|                                       List : Hybrid                         |
|                                              VerticalList : NumberedVertical|
|                                       Sequence                              |
|             Boolean                                                         |
|             Database                                                        |
|             Dictionary : GlobalDictionary                                   |
|                          LocalDictionary                                    |
|             File                                                            |
|             Function : CompiledFunction                                     |
|                        CompiledFunctionClosure : MethodFunction             |
|                        FunctionClosure : CacheFunction                      |
|                                          Iterator                           |
|                                          MethodFunctionBinary               |
|                                          MethodFunctionSingle               |
|                                          MethodFunctionWithOptions          |
|             FunctionBody : CompiledFunctionBody                             |
|             HashTable : CoherentSheaf                                       |
|                         DocumentTag                                         |
|                         Ideal : MonomialIdeal                               |
|                         ImmutableType : Module                              |
|                         Matrix                                              |
|                         MonoidElement                                       |
|                         MutableHashTable : CacheTable                       |
|                                            Descent                          |
|                                            GradedModule : ChainComplex      |
|                                            GradedModuleMap : ChainComplexMap|
|                                            GroebnerBasis                    |
|                                            IndexedVariableTable             |
|                                            Package                          |
|                                            PolyhedralObject : Cone          |
|                                                               Fan           |
|                                                               PolyhedralComp|
|                                                               Polyhedron    |
|                                            Resolution                       |
|                                            ScriptedFunctor                  |
|                                            Type : HeaderType                |
|                                                   Monoid : OrderedMonoid : G|
|                                                   Ring : EngineRing : Fracti|
|                                                                       Galois|
|                                                                       Inexac|
|                                                                             |
|                                                                       Polyno|
|                                                                       Quotie|
|                                                   RingFamily : InexactFieldF|
|                                                   SelfInitializingType      |
|                                                   WrapperType               |
|                                            Variety : AffineVariety          |
|                                                      ProjectiveVariety      |
|                         MutableMatrix                                       |
|                         OptionTable : GroebnerBasisOptions                  |
|                         Program                                             |
|                         ProgramRun                                          |
|                         ProjectiveHilbertPolynomial                         |
|                         RingMap                                             |
|                         SheafMap                                            |
|                         SheafOfRings                                        |
|                         TestInput                                           |
|                         VirtualTally : BettiTally : MultigradedBettiTally   |
|                                        Tally : Set                          |
|             Net : String                                                    |
|             NetFile                                                         |
|             Nothing : InexactNumber  : CC                                   |
|                                    *     *                                  |
|                                        RR                                   |
|                                          *                                  |
|                                        RRi                                  |
|                                           *                                 |
|             Number : Constant                                               |
|                      IndeterminateNumber                                    |
|                      InexactNumber : CC                                     |
|                                      RR                                     |
|                                      RRi                                    |
|                      InfiniteNumber                                         |
|                      QQ                                                     |
|                      ZZ                                                     |
|             Pseudocode : PseudocodeClosure                                  |
|             Symbol : Keyword                                                |
|             SymbolBody                                                      |
|             Task                                                            |
|                                                                             |
|o1 : Descent                                                                 |
|-----------------------------------------------------------------------------|
|List                                                                         |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|lex                                                                          |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|eneralOrderedMonoid                                                          |
|onField                                                                      |
|Field                                                                        |
|tField : ComplexField                                                        |
|         RealField                                                           |
|mialRing                                                                     |
|ntRing                                                                       |
|amily                                                                        |
+-----------------------------------------------------------------------------+
|i2 : showStructure(ZZ,QQ,RR,RR_200,QQ[x],Ring)                               |
|                                                                             |
|o2 = Thing : BasicList : RingElement : QQ[x]                                 |
|             HashTable : MutableHashTable : Type : Ring                      |
|             Nothing : InexactNumber  : RR  : RR                             |
|                                    *     *     200                          |
|             Number : InexactNumber : RR                                     |
|                      QQ                                                     |
|                      ZZ                                                     |
|                                                                             |
|o2 : Descent                                                                 |
+-----------------------------------------------------------------------------+

See also
========

  * showClassStructure -- display class structure
  * showUserStructure -- show parent structure for
    those types defined by user
  * ancestors -- the ancestors of something

For the programmer
==================

The object showStructure, is a command.

showUserStructure -- show parent structure for those types defined by user
**************************************************************************

Synopsis
========

  * Usage:
        showUserStructure
  * Outputs:
      * a display of the parent structure of the types defined by the user and
        assigned to global variables

Description
===========

Each type is displayed to the right of its parent.

A type is an instance of the class Type.

+---------------------------------------------------+
|i1 : R = QQ[x,y]                                   |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : X = new Type of List                          |
|                                                   |
|o2 = X                                             |
|                                                   |
|o2 : Type                                          |
+---------------------------------------------------+
|i3 : Y = new Type of X                             |
|                                                   |
|o3 = Y                                             |
|                                                   |
|o3 : Type                                          |
+---------------------------------------------------+
|i4 : Z = new Type of X                             |
|                                                   |
|o4 = Z                                             |
|                                                   |
|o4 : Type                                          |
+---------------------------------------------------+
|i5 : showUserStructure                             |
|                                                   |
|o5 = Thing : BasicList : RingElement : R           |
|                         VisibleList : List : X : Y|
|                                                  Z|
|                                                   |
|o5 : Descent                                       |
+---------------------------------------------------+

See also
========

  * showStructure -- display parent structure
  * parent -- parent type of an object
  * ancestors -- the ancestors of something

For the programmer
==================

The object showUserStructure, is a command.

sin -- compute the sine
***********************

Synopsis
========

  * Usage:
        sin x
        sin I
  * Inputs:
      * x, a real number,
      * I, a real interval,
  * Outputs:
      * a real number, the sine of x
      * a real interval, an interval containing the sines of the
        points of I

Description
===========

+-------------------------+
|i1 : sin (pi/2)          |
|                         |
|o1 = 1                   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

Ways to use sin:
================

  * "sin(CC)"
  * "sin(RR)"
  * "sin(RRi)"
  * sin(RingElement) (missing documentation)

For the programmer
==================

The object sin, is a method function.

singularLocus -- singular locus
*******************************

Description
===========

singularLocus R -- produce the singular locus of a ring, which is assumed to be
integral.

This function can also be applied to an ideal, in which case the singular locus
of the quotient ring is returned, or to a variety.
+----------------------------------------------------+
|i1 : singularLocus(QQ[x,y] / (x^2 - y^3))           |
|                                                    |
|            QQ[x..y]                                |
|o1 = ---------------------                          |
|         3    2         2                           |
|     (- y  + x , 2x, -3y )                          |
|                                                    |
|o1 : QuotientRing                                   |
+----------------------------------------------------+
|i2 : singularLocus Spec( QQ[x,y,z] / (x^2 - y^3) )  |
|                                                    |
|         /       QQ[x..z]      \                    |
|o2 = Spec|---------------------|                    |
|         |    3    2         2 |                    |
|         \(- y  + x , 2x, -3y )/                    |
|                                                    |
|o2 : AffineVariety                                  |
+----------------------------------------------------+
|i3 : singularLocus Proj( QQ[x,y,z] / (x^2*z - y^3) )|
|                                                    |
|         /QQ[x..z]\                                 |
|o3 = Proj|--------|                                 |
|         |      2 |                                 |
|         \ (x, y )/                                 |
|                                                    |
|o3 : ProjectiveVariety                              |
+----------------------------------------------------+

For rings over ZZ, the locus where the ring is not smooth over
ZZ, is computed.

+---------------------------------------------+
|i4 : singularLocus(ZZ[x,y]/(x^2-x-y^3+y^2))  |
|                                             |
|                     ZZ[x..y]                |
|o4 = ----------------------------------------|
|         3    2    2                  2      |
|     (- y  + x  + y  - x, 2x - 1, - 3y  + 2y)|
|                                             |
|o4 : QuotientRing                            |
+---------------------------------------------+
|i5 : gens gb ideal oo                        |
|                                             |
|o5 = | 11 y+3 x+5 |                          |
|                                             |
|                      1               3      |
|o5 : Matrix (ZZ[x..y])  <-- (ZZ[x..y])       |
+---------------------------------------------+

Ways to use singularLocus:
==========================

  * "singularLocus(Ideal)"
  * "singularLocus(Ring)"
  * singularLocus(AffineVariety) (missing documentation)
  * singularLocus(ProjectiveVariety) (missing documentation)

For the programmer
==================

The object singularLocus, is a method function.

sinh -- compute the hyperbolic sine
***********************************

Synopsis
========

  * Usage:
        sinh x
        sinh I
  * Inputs:
      * x, a real number,
      * I, a real interval,
  * Outputs:
      * a real number, the hyperbolic sine of x
      * a real interval, an interval containing the hyerbolic sines
        of the points of I

Ways to use sinh:
=================

  * "sinh(CC)"
  * "sinh(RR)"
  * "sinh(RRi)"
  * sinh(RingElement) (missing documentation)

For the programmer
==================

The object sinh, is a method function.

size -- the size of an object
*****************************

Description
===========

size x -- returns the size of x which usually gives a rough indication of
memory space required to store the object x.

For a polynomial, the size is the number of terms.

This function should be replaced by something more generally useful.

Ways to use size:
=================

  * "size(RingElement)"

For the programmer
==================

The object size, is a method function.

size2 -- number of binary digits to the left of the point
*********************************************************

Synopsis
========

  * Usage:
        size2 x
  * Inputs:
      * x, a number,
  * Outputs:
      * the smallest number n such that 2^n is strictly greater than the
        absolute value of x

Description
===========

This function is not implemented for rational numbers.
+----------------------+
|i1 : size2 4          |
|                      |
|o1 = 3                |
+----------------------+
|i2 : size2 3          |
|                      |
|o2 = 2                |
+----------------------+
|i3 : size2 4.         |
|                      |
|o3 = 3                |
+----------------------+
|i4 : size2 3.99999999 |
|                      |
|o4 = 2                |
+----------------------+
|i5 : size2 0          |
|                      |
|o5 = -1073741824      |
+----------------------+
|i6 : size2 0.         |
|                      |
|o6 = -1073741824      |
+----------------------+
|i7 : size2 (1/0.)     |
|                      |
|o7 = 1073741823       |
+----------------------+
|i8 : size2 (1/0.-1/0.)|
|                      |
|o8 = 1073741823       |
+----------------------+

Ways to use size2:
==================

  * "size2(CC)"
  * "size2(RR)"
  * "size2(RRi)"
  * "size2(ZZ)"

For the programmer
==================

The object size2, is a compiled function.

smithNormalForm(Matrix) -- smith normal form for a matrix over ZZ or a PID
**************************************************************************

Synopsis
========

  * Function: smithNormalForm,
  * Usage:
        (D,P,Q) = smithNormalForm M
        (D,P) = smithNormalForm(M,ChangeMatrix=>{true,false})
        (D,Q) = smithNormalForm(M,ChangeMatrix=>{false,true})
        D = smithNormalForm(M,ChangeMatrix=>{false,false})
  * Inputs:
      * M
  * Optional inputs,:
      * ChangeMatrix => a list, default value {true, true}, of two
        Boolean elements. This determines whether the change of basis matrices
        P and/or Q are computed
      * KeepZeroes => a Boolean value, default value true,
        whether to keep rows and columns that are completely zero
  * Outputs:
      * D, a matrix, The Smith normal form of M
      * P, a matrix, invertible (left) change of basis matrix
      * Q, a matrix, invertible (right) change of basis matrix

Description
===========

This function produces a diagonal matrix D, and invertible matrices P and Q
such that D = PMQ.  Warning: even though this function is called the Smith
normal form, it doesn't necessarily satisfy the more stringent condition that
the diagonal entries d1, d2, ..., dn of D satisfy: d1|d2|...|dn..
+--------------------------------------------------------------------------+
|i1 : M = matrix{{1,2,3},{1,34,45},{2213,1123,6543},{0,0,0}}               |
|                                                                          |
|o1 = | 1    2    3    |                                                   |
|     | 1    34   45   |                                                   |
|     | 2213 1123 6543 |                                                   |
|     | 0    0    0    |                                                   |
|                                                                          |
|              4       3                                                   |
|o1 : Matrix ZZ  <-- ZZ                                                    |
+--------------------------------------------------------------------------+
|i2 : (D,P,Q) = smithNormalForm M                                          |
|                                                                          |
|o2 = (| 135654 0 0 |, | 1 33471 -43292 0 |, | 171927 -42421 54868  |)     |
|      | 0      1 0 |  | 0 1     0      0 |  | 93042  -22957 29693  |      |
|      | 0      0 1 |  | 0 0     1      0 |  | -74119 18288  -23654 |      |
|      | 0      0 0 |  | 0 0     0      1 |                                |
|                                                                          |
|o2 : Sequence                                                             |
+--------------------------------------------------------------------------+
|i3 : D == P * M * Q                                                       |
|                                                                          |
|o3 = true                                                                 |
+--------------------------------------------------------------------------+
|i4 : (D,P) = smithNormalForm(M, ChangeMatrix=>{true,false})               |
|                                                                          |
|o4 = (| 135654 0 0 |, | 1 33471 -43292 0 |)                               |
|      | 0      1 0 |  | 0 1     0      0 |                                |
|      | 0      0 1 |  | 0 0     1      0 |                                |
|      | 0      0 0 |  | 0 0     0      1 |                                |
|                                                                          |
|o4 : Sequence                                                             |
+--------------------------------------------------------------------------+
|i5 : D = smithNormalForm(M, ChangeMatrix=>{false,false}, KeepZeroes=>true)|
|                                                                          |
|o5 = | 135654 0 0 |                                                       |
|     | 0      1 0 |                                                       |
|     | 0      0 1 |                                                       |
|                                                                          |
|              3       3                                                   |
|o5 : Matrix ZZ  <-- ZZ                                                    |
+--------------------------------------------------------------------------+

This function is the underlying routine used by minimalPresentation,
in the case when the ring is ZZ, or a
polynomial ring in one variable over a field.

+-------------------------------+
|i6 : prune coker M             |
|                               |
|o6 = cokernel | 135654 |       |
|              | 0      |       |
|                               |
|                              2|
|o6 : ZZ-module, quotient of ZZ |
+-------------------------------+
In the following example, we test the result be checking that the entries of
D1, P1 M Q1 are the same. The degrees associated to these matrices do not match
up, so a simple test of equality would return false.
+-----------------------------------------------------------------------------+
|i7 : S = ZZ/101[t]                                                           |
|                                                                             |
|o7 = S                                                                       |
|                                                                             |
|o7 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i8 : D = diagonalMatrix{t^2+1, (t^2+1)^2, (t^2+1)^3, (t^2+1)^5}              |
|                                                                             |
|o8 = | t2+1 0        0            0                       |                  |
|     | 0    t4+2t2+1 0            0                       |                  |
|     | 0    0        t6+3t4+3t2+1 0                       |                  |
|     | 0    0        0            t10+5t8+10t6+10t4+5t2+1 |                  |
|                                                                             |
|             4      4                                                        |
|o8 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i9 : P = random(S^4, S^4)                                                    |
|                                                                             |
|o9 = | 24  19  -8  -38 |                                                     |
|     | -36 19  -22 -16 |                                                     |
|     | -30 -10 -29 39  |                                                     |
|     | -29 -29 -24 21  |                                                     |
|                                                                             |
|             4      4                                                        |
|o9 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i10 : Q = random(S^4, S^4)                                                   |
|                                                                             |
|o10 = | 34  -18 -28 16  |                                                    |
|      | 19  -13 -47 22  |                                                    |
|      | -47 -43 38  45  |                                                    |
|      | -39 -15 2   -34 |                                                    |
|                                                                             |
|              4      4                                                       |
|o10 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+
|i11 : M = P*D*Q                                                              |
|                                                                             |
|o11 = | -33t10+37t8+46t6+48t4-24t2+5 -36t10+22t8-16t6+21t4+27t2+33           |
|      | 18t10-11t8+2t6+7t4-37t2-13   38t10-12t8+13t6+42t4-50t2-29            |
|      | -6t10-30t8-10t6+t4+33t2+46   21t10+4t8+43t6+41t4+19                  |
|      | -11t10+46t8+8t6-4t4+29t2-16  -12t10+41t8+3t6+20t4-31t2               |
|      -----------------------------------------------------------------------|
|      25t10+24t8+47t6-40t4-13t2-26  -21t10-4t8+36t6+37t4+35t2+17 |           |
|      -32t10+42t8-45t6+16t4-12t2-46 39t10-7t8+6t6-41t4+10t2+2    |           |
|      -23t10-14t8-19t6-36t4-25t2-17 -13t10+36t8-21t6-23t4+49t2+2 |           |
|      42t10+8t8+13t6-44t4+2t2-8     -7t10-35t8-39t6-9t4+35t2+33  |           |
|                                                                             |
|              4      4                                                       |
|o11 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+
|i12 : (D1,P1,Q1) = smithNormalForm M;                                        |
+-----------------------------------------------------------------------------+
|i13 : D1 - P1*M*Q1 == 0                                                      |
|                                                                             |
|o13 = true                                                                   |
+-----------------------------------------------------------------------------+
|i14 : prune coker M                                                          |
|                                                                             |
|o14 = cokernel | t10+5t8+10t6+10t4+5t2+1 0            0        0    |        |
|               | 0                       t6+3t4+3t2+1 0        0    |        |
|               | 0                       0            t4+2t2+1 0    |        |
|               | 0                       0            0        t2+1 |        |
|                                                                             |
|                             4                                               |
|o14 : S-module, quotient of S                                                |
+-----------------------------------------------------------------------------+
This routine is under development.  The main idea is to compute a Gröbner
basis, transpose the generators, and repeat, until we encounter a matrix whose
transpose is already a Gröbner basis.  This may depend heavily on the monomial
order.

Caveat
======

The Smith normal form itself is NOT returned! This function is under
development, and its performance might need to be improved.  Also, this
function doesn't warn the user if the ring is not a PID.

See also
========

  * minimalPresentation(Module), --
    minimal presentation of a module

Ways to use this method:
========================

  * smithNormalForm(Matrix) -- smith normal
    form for a matrix over ZZ or a PID

solve -- solve linear equation(s)
*********************************

Synopsis
========

  * Usage:
        X = solve(A,B)
  * Inputs:
      * A, a matrix, or a mutable matrix,
        of size m by n over a field R, which can be one of: ZZ/p, GF(p^n), QQ,
        RR, CC
      * B, of the same type of matrix as A, over the same ring, of size m by r
  * Optional inputs,:
      * ClosestFit => a Boolean value, default value false,
        whether to use the least squares method, in the case when the ring is
        RR or CC
      * MaximalRank => a Boolean value, default value false,
        declares to the system that the matrix is full rank.  In some cases,
        this can dramatically speed up the computation.  If the matrix is not
        full rank, then the results are potentially meaningless.
      * Invertible (missing documentation) => ..., default value false,
      * Precision => ..., default value 0
  * Outputs:
      * X, of the same type of matrix as A, over the same ring, such that
        $AX=B$

Description
===========

+--------------------------------------------------+
|i1 : kk = ZZ/101;                                 |
+--------------------------------------------------+
|i2 : A = matrix"1,2,3,4;1,3,6,10;19,7,11,13" ** kk|
|                                                  |
|o2 = | 1  2 3  4  |                               |
|     | 1  3 6  10 |                               |
|     | 19 7 11 13 |                               |
|                                                  |
|              3       4                           |
|o2 : Matrix kk  <-- kk                            |
+--------------------------------------------------+
|i3 : b = matrix"1;1;1" ** kk                      |
|                                                  |
|o3 = | 1 |                                        |
|     | 1 |                                        |
|     | 1 |                                        |
|                                                  |
|              3       1                           |
|o3 : Matrix kk  <-- kk                            |
+--------------------------------------------------+
|i4 : x = solve(A,b)                               |
|                                                  |
|o4 = | 2  |                                       |
|     | -1 |                                       |
|     | 34 |                                       |
|     | 0  |                                       |
|                                                  |
|              4       1                           |
|o4 : Matrix kk  <-- kk                            |
+--------------------------------------------------+
|i5 : A*x-b                                        |
|                                                  |
|o5 = 0                                            |
|                                                  |
|              3       1                           |
|o5 : Matrix kk  <-- kk                            |
+--------------------------------------------------+
+----------------------------------------------------------------+
|i6 : kk = GF(25)                                                |
|                                                                |
|o6 = kk                                                         |
|                                                                |
|o6 : GaloisField                                                |
+----------------------------------------------------------------+
|i7 : a = kk_0                                                   |
|                                                                |
|o7 = a                                                          |
|                                                                |
|o7 : kk                                                         |
+----------------------------------------------------------------+
|i8 : A = matrix"a,a+1,a+2,3a,4;a-1,1,2a,6,10;19,7,a,11,13" ** kk|
|                                                                |
|o8 = | a   a+1 a+2 -2a -1 |                                     |
|     | a-1 1   2a  1   0  |                                     |
|     | -1  2   a   1   -2 |                                     |
|                                                                |
|              3       5                                         |
|o8 : Matrix kk  <-- kk                                          |
+----------------------------------------------------------------+
|i9 : b = matrix"1;-a+1;1" ** kk                                 |
|                                                                |
|o9 = | 1    |                                                   |
|     | -a+1 |                                                   |
|     | 1    |                                                   |
|                                                                |
|              3       1                                         |
|o9 : Matrix kk  <-- kk                                          |
+----------------------------------------------------------------+
|i10 : x = solve(A,b)                                            |
|                                                                |
|o10 = | -a    |                                                 |
|      | -2a+1 |                                                 |
|      | -2a   |                                                 |
|      | 0     |                                                 |
|      | 0     |                                                 |
|                                                                |
|               5       1                                        |
|o10 : Matrix kk  <-- kk                                         |
+----------------------------------------------------------------+
|i11 : A*x-b                                                     |
|                                                                |
|o11 = 0                                                         |
|                                                                |
|               3       1                                        |
|o11 : Matrix kk  <-- kk                                         |
+----------------------------------------------------------------+
+---------------------------------------------------+
|i12 : kk = QQ                                      |
|                                                   |
|o12 = QQ                                           |
|                                                   |
|o12 : Ring                                         |
+---------------------------------------------------+
|i13 : A = matrix"1,2,3,4;1,3,6,10;19,7,11,13" ** kk|
|                                                   |
|o13 = | 1  2 3  4  |                               |
|      | 1  3 6  10 |                               |
|      | 19 7 11 13 |                               |
|                                                   |
|               3       4                           |
|o13 : Matrix QQ  <-- QQ                            |
+---------------------------------------------------+
|i14 : b = matrix"1;1;1" ** kk                      |
|                                                   |
|o14 = | 1 |                                        |
|      | 1 |                                        |
|      | 1 |                                        |
|                                                   |
|               3       1                           |
|o14 : Matrix QQ  <-- QQ                            |
+---------------------------------------------------+
|i15 : x = solve(A,b)                               |
|                                                   |
|o15 = | -7/47  |                                   |
|      | 54/47  |                                   |
|      | -18/47 |                                   |
|      | 0      |                                   |
|                                                   |
|               4       1                           |
|o15 : Matrix QQ  <-- QQ                            |
+---------------------------------------------------+
|i16 : A*x-b                                        |
|                                                   |
|o16 = 0                                            |
|                                                   |
|               3       1                           |
|o16 : Matrix QQ  <-- QQ                            |
+---------------------------------------------------+

Over RR_{53} or CC_{53}, if the matrix A is non-singular and square, then
highly optimized lapack routines will be called.

+--------------------------------------------+
|i17 : printingPrecision = 4;                |
+--------------------------------------------+
|i18 : A = matrix "1,2,3;1,3,6;19,7,11" ** RR|
|                                            |
|o18 = | 1  2 3  |                           |
|      | 1  3 6  |                           |
|      | 19 7 11 |                           |
|                                            |
|                 3         3                |
|o18 : Matrix RR    <-- RR                   |
|               53        53                 |
+--------------------------------------------+
|i19 : b = matrix "1;1;1" ** RR              |
|                                            |
|o19 = | 1 |                                 |
|      | 1 |                                 |
|      | 1 |                                 |
|                                            |
|                 3         1                |
|o19 : Matrix RR    <-- RR                   |
|               53        53                 |
+--------------------------------------------+
|i20 : x = solve(A,b)                        |
|                                            |
|o20 = | -.1489 |                            |
|      | 1.149  |                            |
|      | -.383  |                            |
|                                            |
|                 3         1                |
|o20 : Matrix RR    <-- RR                   |
|               53        53                 |
+--------------------------------------------+
|i21 : A*x-b                                 |
|                                            |
|o21 = | 2.22e-16  |                         |
|      | -2.22e-16 |                         |
|      | 0         |                         |
|                                            |
|                 3         1                |
|o21 : Matrix RR    <-- RR                   |
|               53        53                 |
+--------------------------------------------+
|i22 : norm oo                               |
|                                            |
|o22 = 2.220446049250313e-16                 |
|                                            |
|o22 : RR (of precision 53)                  |
+--------------------------------------------+
|i23 : clean(1e-15, A*x-b)                   |
|                                            |
|o23 = | 0 |                                 |
|      | 0 |                                 |
|      | 0 |                                 |
|                                            |
|                 3         1                |
|o23 : Matrix RR    <-- RR                   |
|               53        53                 |
+--------------------------------------------+

If you know that your matrix is square, and invertible, then providing the
hint: MaximalRank=>true allows Macaulay2 to choose the fastest routines.  For
small matrix sizes, it should not be too noticeable, but for large matrices,
the difference in time taken can be dramatic.

+-----------------------------------------------------------+
|i24 : printingPrecision = 4;                               |
+-----------------------------------------------------------+
|i25 : N = 40                                               |
|                                                           |
|o25 = 40                                                   |
+-----------------------------------------------------------+
|i26 : A = mutableMatrix(CC_53, N, N); fillMatrix A;        |
+-----------------------------------------------------------+
|i28 : B = mutableMatrix(CC_53, N, 2); fillMatrix B;        |
+-----------------------------------------------------------+
|i30 : time X = solve(A,B);                                 |
| -- used 0.000294508s (cpu); 0.000292824s (thread); 0s (gc)|
+-----------------------------------------------------------+
|i31 : time X = solve(A,B, MaximalRank=>true);              |
| -- used 7.7894e-05s (cpu); 7.7879e-05s (thread); 0s (gc)  |
+-----------------------------------------------------------+
|i32 : norm(A*X-B)                                          |
|                                                           |
|o32 = 5.512120354514498e-15                                |
|                                                           |
|o32 : RR (of precision 53)                                 |
+-----------------------------------------------------------+

Over higher precision RR or CC, these routines will be much slower than the
lower precision lapack routines.

+-----------------------------------------------------+
|i33 : N = 100                                        |
|                                                     |
|o33 = 100                                            |
+-----------------------------------------------------+
|i34 : A = mutableMatrix(CC_100, N, N); fillMatrix A; |
+-----------------------------------------------------+
|i36 : B = mutableMatrix(CC_100, N, 2); fillMatrix B; |
+-----------------------------------------------------+
|i38 : time X = solve(A,B);                           |
| -- used 0.239745s (cpu); 0.150694s (thread); 0s (gc)|
+-----------------------------------------------------+
|i39 : time X = solve(A,B, MaximalRank=>true);        |
| -- used 0.119272s (cpu); 0.119275s (thread); 0s (gc)|
+-----------------------------------------------------+
|i40 : norm(A*X-B)                                    |
|                                                     |
|o40 = 1.491578274689709814082355885932e-28           |
|                                                     |
|o40 : RR (of precision 100)                          |
+-----------------------------------------------------+

Giving the option ClosestFit=>true, in the case when the field is RR or CC,
uses a least squares algorithm to find a best fit solution.

+---------------------------------------------------+
|i41 : kk = RR_53;                                  |
+---------------------------------------------------+
|i42 : A = matrix"1,2,3,4;1,3,6,10;19,7,11,13" ** kk|
|                                                   |
|o42 = | 1  2 3  4  |                               |
|      | 1  3 6  10 |                               |
|      | 19 7 11 13 |                               |
|                                                   |
|                 3         4                       |
|o42 : Matrix RR    <-- RR                          |
|               53        53                        |
+---------------------------------------------------+
|i43 : b = matrix"1;1;1" ** kk                      |
|                                                   |
|o43 = | 1 |                                        |
|      | 1 |                                        |
|      | 1 |                                        |
|                                                   |
|                 3         1                       |
|o43 : Matrix RR    <-- RR                          |
|               53        53                        |
+---------------------------------------------------+
|i44 : x1 = solve(A,b, ClosestFit=>true)            |
|                                                   |
|o44 = | -.1899 |                                   |
|      | .6399  |                                   |
|      | .3367  |                                   |
|      | -.275  |                                   |
|                                                   |
|                 4         1                       |
|o44 : Matrix RR    <-- RR                          |
|               53        53                        |
+---------------------------------------------------+
|i45 : A*x1-b                                       |
|                                                   |
|o45 = | -8.882e-16 |                               |
|      | -6.661e-16 |                               |
|      | -1.332e-15 |                               |
|                                                   |
|                 3         1                       |
|o45 : Matrix RR    <-- RR                          |
|               53        53                        |
+---------------------------------------------------+

Giving both options ClosestFit and MaximalRank allows Macaulay2 to call a
faster algorithm.

+----------------------------------------------------------+
|i46 : x2 = solve(A,b, ClosestFit=>true, MaximalRank=>true)|
|                                                          |
|o46 = | -.1899 |                                          |
|      | .6399  |                                          |
|      | .3367  |                                          |
|      | -.275  |                                          |
|                                                          |
|                 4         1                              |
|o46 : Matrix RR    <-- RR                                 |
|               53        53                               |
+----------------------------------------------------------+
|i47 : A*x2-b                                              |
|                                                          |
|o47 = | 0         |                                       |
|      | 0         |                                       |
|      | 3.109e-15 |                                       |
|                                                          |
|                 3         1                              |
|o47 : Matrix RR    <-- RR                                 |
|               53        53                               |
+----------------------------------------------------------+

Caveat
======

(1) This function is limited in scope, but has been designed to be much faster
than generic algorithms. (2) If the matrix is a square invertible matrix,
giving the option MaximalRank=>true can strongly speed up the computation. (3)
For mutable matrices, this function is only currently implemented for densely
encoded matrices.

See also
========

  * LUdecomposition -- LU decomposition
  * inverse -- compute the inverse
  * determinant -- determinant of a matrix
  * SVD -- singular value decomposition of a matrix
  * norm
  * clean -- Set to zero elements that are approximately zero

Ways to use solve:
==================

  * "solve(Matrix,Matrix)"
  * "solve(MutableMatrix,MutableMatrix)"
  * solve(Matrix,Vector) (missing documentation)

For the programmer
==================

The object solve, is a method function with options.

someTerms -- select some terms of a polynomial
**********************************************

Synopsis
========

  * Usage:
        someTerms(f,i,n)
  * Inputs:
      * f, a ring element, in a polynomial ring
      * i, an integer, the starting index
      * n, an integer, the number of terms to select
  * Outputs:
      * a ring element, the n terms of the polynomial f
        starting with the i-th one

Description
===========

The index i is 0-based, and a negative number refers to location from the end
of the polynomial.
+------------------------------------------+
|i1 : R = ZZ[a..d];                        |
+------------------------------------------+
|i2 : f = (a+2*b-3)^2                      |
|                                          |
|      2            2                      |
|o2 = a  + 4a*b + 4b  - 6a - 12b + 9       |
|                                          |
|o2 : R                                    |
+------------------------------------------+
|i3 : someTerms(f,0,1) -- the lead term    |
|                                          |
|      2                                   |
|o3 = a                                    |
|                                          |
|o3 : R                                    |
+------------------------------------------+
|i4 : someTerms(f,-1,1) -- the last term   |
|                                          |
|o4 = 9                                    |
|                                          |
|o4 : R                                    |
+------------------------------------------+
|i5 : someTerms(f,-2,2) -- the last 2 terms|
|                                          |
|o5 = - 12b + 9                            |
|                                          |
|o5 : R                                    |
+------------------------------------------+
Here is an example where the coefficient ring is also a polynomial ring.
+-----------------------------------------------------------------------------+
|i6 : S = R[x,y,z];                                                           |
+-----------------------------------------------------------------------------+
|i7 : f = (x*(a-b)+y^2+a-1)^2                                                 |
|                                                                             |
|      4               2     2           2  2            2      2             |
|o7 = y  + (2a - 2b)x*y  + (a  - 2a*b + b )x  + (2a - 2)y  + (2a  - 2a*b - 2a |
|     ------------------------------------------------------------------------|
|               2                                                             |
|     + 2b)x + a  - 2a + 1                                                    |
|                                                                             |
|o7 : S                                                                       |
+-----------------------------------------------------------------------------+
|i8 : someTerms(f,-1,1) -- the last term                                      |
|                                                                             |
|      2                                                                      |
|o8 = a  - 2a + 1                                                             |
|                                                                             |
|o8 : S                                                                       |
+-----------------------------------------------------------------------------+
|i9 : someTerms(f,-2,2) -- the last 2 terms                                   |
|                                                                             |
|        2                       2                                            |
|o9 = (2a  - 2a*b - 2a + 2b)x + a  - 2a + 1                                   |
|                                                                             |
|o9 : S                                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * monomials -- matrix of monomials in a ring element or
    matrix
  * coefficients -- monomials and their coefficients
  * terms -- provide a list of terms of a polynomial
  * leadTerm -- get the greatest term

Ways to use someTerms:
======================

  * "someTerms(RingElement,ZZ,ZZ)"

For the programmer
==================

The object someTerms, is a method function.

Sort -- a Strategy option value
*******************************

Description
===========

Sort -- a strategy used with the keyword Strategy.

Indicates that the Gröbner basis should be sorted by lead term; usually this is
a bad idea.  Normally the basis is sorted only by degree. The running time can
change either for the good or bad.

See also
========

  * gb(...,Strategy=>...) -- compute a Gröbner basis

For the programmer
==================

The object Sort, is a symbol.

sort -- sort a list or columns of a matrix
******************************************

See also
========

  * rsort -- sort a list or matrix in reverse order
  * sortColumns -- permutation giving sort order
  * <= -- less than or equal
  * ? -- comparison operator

Ways to use sort:
=================

  * sort(List) -- sort a list
  * sort(List,Function) (missing documentation)
  * sort(Matrix) -- sort the columns of a matrix

For the programmer
==================

The object sort, is a method function with options.

sort(...,DegreeOrder=>...) -- specify Ascending, Descending, or null
********************************************************************

Synopsis
========

  * Usage:
        sort(...,DegreeOrder=>x)
  * Inputs:
      * x, a symbol, either Ascending,
        Descending, or null,
  * Consequences:
      * If x is not null, first order the columns of the matrix in ascending or
        descending degree (depending on x).  If x is null, then only use the
        monomial order in the sort

Further information
===================

  * Default value: null
  * Function: sort, -- sort a list or columns of a matrix
  * Option key: DegreeOrder, -- sort primarily by degree

Caveat
======

This option only works for sorting columns of a matrix, not the elements of a
list

Functions with optional argument named DegreeOrder:
===================================================

  * rsort(...,DegreeOrder=>...)
    -- specify Ascending,
    Descending, or null
  * sort(...,DegreeOrder=>...)
    -- specify Ascending,
    Descending, or null
  * sortColumns(...,DegreeOrder=>...)
    -- specify Ascending,
    Descending, or null

sort(...,MonomialOrder=>...) -- specify Ascending or Descending monomial order
******************************************************************************

Synopsis
========

  * Usage:
        sort(...,MonomialOrder=>x)
  * Inputs:
      * x, a symbol, either Ascending, or
        Descending,
  * Consequences:
      * After the degree order has been considered, sort the columns of the
        matrix in Ascending or Descending monomial order

Further information
===================

  * Default value: Ascending,
  * Function: sort, -- sort a list or columns of a matrix
  * Option key: MonomialOrder, -- monomial ordering

Caveat
======

This option only works for sorting columns of a matrix, not the elements of a
list

Functions with optional argument named MonomialOrder:
=====================================================

  * "graphIdeal(...,MonomialOrder=>...)" -- see graphIdeal(RingMap),
    -- the ideal of the graph of the regular map
    corresponding to a ring map
  * "graphRing(...,MonomialOrder=>...)" -- see graphRing(RingMap),
    -- the coordinate ring of the graph of the regular
    map corresponding to a ring map
  * monoid(...,MonomialOrder=>...)
    -- specify the monomial
    ordering
  * "newRing(...,MonomialOrder=>...)" -- see newRing, -- make a
    copy of a ring, with some features changed
  * "pushForward(...,MonomialOrder=>...)" -- see
    pushForward(RingMap,Module),
  * rsort(...,MonomialOrder=>...)
    -- specify Ascending or
    Descending monomial order
  * sort(...,MonomialOrder=>...)
    -- specify Ascending or
    Descending monomial order
  * sortColumns(...,MonomialOrder=>...)
    -- specify Ascending
    or Descending monomial order
  * "symmetricAlgebra(...,MonomialOrder=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,MonomialOrder=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids
  * "tensor(Ring,Ring,MonomialOrder=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

sort(List) -- sort a list
*************************

Synopsis
========

  * Function: sort,
  * Usage:
        sort v
  * Inputs:
      * v
  * Optional inputs,:
      * DegreeOrder, =>
        ..., default value null, specify Ascending, Descending, or null
      * MonomialOrder, =>
        ..., default value Ascending, specify Ascending or Descending monomial
        order
  * Outputs:
      * a list,  of the same length as v sorted in ascending order

Description
===========

The sort function uses <=, to compare elements of the list, which in
turn calls upon the comparison operator ?, so, to determine how the
elements are sorted, refer to its documentation.  Methods for new user defined
types of objects can be installed for it, too, to obtain the desired sorting
behavior.

+-----------------------+
|i1 : sort {c,e,a,f,b,f}|
|                       |
|o1 = {a, b, c, e, f, f}|
|                       |
|o1 : List              |
+-----------------------+
|i2 : sort {4,2,6,3,8,2}|
|                       |
|o2 = {2, 2, 3, 4, 6, 8}|
|                       |
|o2 : List              |
+-----------------------+

Comparison of strings is implemented so that symbols come before alphanumeric
characters, upper and lower case characters are sorted together, and strings of
digits are sorted by size of the implied number.

+------------------------------------------------+
|i3 : sort {"a11","a1","a2","A11","A1","A2","B2"}|
|                                                |
|o3 = {A1, a1, A2, a2, A11, a11, B2}             |
|                                                |
|o3 : List                                       |
+------------------------------------------------+

Visible lists (lists, sequences, and arrays) are compared lexicographically.

+---------------------------------------------+
|i4 : sort {(1,1),(2,1),(3,1),(1,2),(3,2)}    |
|                                             |
|o4 = {(1, 1), (1, 2), (2, 1), (3, 1), (3, 2)}|
|                                             |
|o4 : List                                    |
+---------------------------------------------+

If the elements of the list are polynomials, then the monomial order is used to
sort the elements according to their lead terms.

+-------------------------------------+
|i5 : R = ZZ[a..d,MonomialOrder=>Lex];|
+-------------------------------------+
|i6 : sort{a*d, b^100, c^3*d}         |
|                                     |
|       3    100                      |
|o6 = {c d, b   , a*d}                |
|                                     |
|o6 : List                            |
+-------------------------------------+

The optional arguments are not used in this version of sort.

Caveat
======

If a list contains elements of different types, the sorting still occurs, but
might not be particularly intuitive.

See also
========

  * rsort -- sort a list or matrix in reverse order
  * <= -- less than or equal
  * ? -- comparison operator

Ways to use this method:
========================

  * sort(List) -- sort a list

sort(Matrix) -- sort the columns of a matrix
********************************************

Synopsis
========

  * Function: sort,
  * Usage:
        sort m
  * Inputs:
      * m, between free modules
  * Optional inputs,:
      * DegreeOrder, =>
        ..., default value null, specify Ascending, Descending, or null
      * MonomialOrder, =>
        ..., default value Ascending, specify Ascending or Descending monomial
        order
  * Outputs:
      * a matrix, with the same shape as m whose columns are
        sorted in increasing order

Description
===========

The default order is to sort the columns in ascending degree first, and within
each degree, first compare ring elements in the highest non-zero component,
breaking ties by going to the next lower component. Zero is considered earlier
in the order than other elements
+----------------------------------------------------+
|i1 : R = ZZ/32003[a..d,MonomialOrder=>Lex];         |
+----------------------------------------------------+
|i2 : m = matrix{{a*d, b^2, b^100, b^50*d^50, c^2*d}}|
|                                                    |
|o2 = | ad b2 b100 b50d50 c2d |                      |
|                                                    |
|             1      5                               |
|o2 : Matrix R  <-- R                                |
+----------------------------------------------------+
|i3 : sort m                                         |
|                                                    |
|o3 = | c2d b2 b50d50 b100 ad |                      |
|                                                    |
|             1      5                               |
|o3 : Matrix R  <-- R                                |
+----------------------------------------------------+

The two optional arguments can modify this default order. The value of
DegreeOrder, is considered first (Ascending, Descending, or null),
and after that the monomial (or ring) order is used to break ties, either
ascending or descending, depending on the value of MonomialOrder.

To sort the columns of m in descending monomial order:
+----------------------------------------------------------+
|i4 : options sort                                         |
|                                                          |
|o4 = OptionTable{DegreeOrder => null       }              |
|                 MonomialOrder => Ascending               |
|                                                          |
|o4 : OptionTable                                          |
+----------------------------------------------------------+
|i5 : sort(m, DegreeOrder=>null, MonomialOrder=>Descending)|
|                                                          |
|o5 = | ad b100 b50d50 b2 c2d |                            |
|                                                          |
|             1      5                                     |
|o5 : Matrix R  <-- R                                      |
+----------------------------------------------------------+

See also
========

  * sortColumns -- permutation giving sort order

Ways to use this method:
========================

  * sort(Matrix) -- sort the columns of a matrix

sortColumns -- permutation giving sort order
********************************************

Synopsis
========

  * Usage:
        sortColumns m
  * Inputs:
      * m, between free modules
  * Optional inputs,:
      * DegreeOrder,
        => ..., default value null, specify Ascending, Descending, or null
      * MonomialOrder,
        => ..., default value Ascending, specify Ascending or Descending
        monomial order
  * Outputs:
      * a list, of integers, representing the order which places
        the columns in order

Description
===========

See sort(Matrix), for the ordering used.  The meanings
of the optional parameters is also the same.
+----------------------------------------------------+
|i1 : R = ZZ/32003[a..d,MonomialOrder=>Lex];         |
+----------------------------------------------------+
|i2 : m = matrix{{a*d, b^2, b^100, b^50*d^50, c^2*d}}|
|                                                    |
|o2 = | ad b2 b100 b50d50 c2d |                      |
|                                                    |
|             1      5                               |
|o2 : Matrix R  <-- R                                |
+----------------------------------------------------+
|i3 : p = sortColumns m                              |
|                                                    |
|o3 = {4, 1, 3, 2, 0}                                |
|                                                    |
|o3 : List                                           |
+----------------------------------------------------+
|i4 : m_p                                            |
|                                                    |
|o4 = | c2d b2 b50d50 b100 ad |                      |
|                                                    |
|             1      5                               |
|o4 : Matrix R  <-- R                                |
+----------------------------------------------------+
+---------------------------------------------------------------------+
|i5 : p = sortColumns(m, DegreeOrder=>null, MonomialOrder=>Descending)|
|                                                                     |
|o5 = {0, 2, 3, 1, 4}                                                 |
|                                                                     |
|o5 : List                                                            |
+---------------------------------------------------------------------+
|i6 : m_p                                                             |
|                                                                     |
|o6 = | ad b100 b50d50 b2 c2d |                                       |
|                                                                     |
|             1      5                                                |
|o6 : Matrix R  <-- R                                                 |
+---------------------------------------------------------------------+
+--------------------------------------------------+
|i7 : R = ZZ/101[a..c];                            |
+--------------------------------------------------+
|i8 : f = matrix{{1,a,a^2,b^2,b,c,c^2,a*b,b*c,a*c}}|
|                                                  |
|o8 = | 1 a a2 b2 b c c2 ab bc ac |                |
|                                                  |
|             1      10                            |
|o8 : Matrix R  <-- R                              |
+--------------------------------------------------+
|i9 : s = sortColumns f                            |
|                                                  |
|o9 = {0, 5, 4, 1, 6, 8, 9, 3, 7, 2}               |
|                                                  |
|o9 : List                                         |
+--------------------------------------------------+
|i10 : f_s                                         |
|                                                  |
|o10 = | 1 c b a c2 bc ac b2 ab a2 |               |
|                                                  |
|              1      10                           |
|o10 : Matrix R  <-- R                             |
+--------------------------------------------------+
|i11 : s = sortColumns(f,DegreeOrder => Descending)|
|                                                  |
|o11 = {6, 8, 9, 3, 7, 2, 5, 4, 1, 0}              |
|                                                  |
|o11 : List                                        |
+--------------------------------------------------+
|i12 : f_s                                         |
|                                                  |
|o12 = | c2 bc ac b2 ab a2 c b a 1 |               |
|                                                  |
|              1      10                           |
|o12 : Matrix R  <-- R                             |
+--------------------------------------------------+

See also
========

  * sort -- sort a list or columns of a matrix

Ways to use sortColumns:
========================

  * "sortColumns(Matrix)"

For the programmer
==================

The object sortColumns, is a method function with options.

sortColumns(...,DegreeOrder=>...) -- specify Ascending, Descending, or null
***************************************************************************

Synopsis
========

  * Usage:
        sortColumns(...,DegreeOrder=>x)
  * Inputs:
      * x, a symbol, either Ascending,
        Descending, or null,
  * Consequences:
      * If x is not null, first order the columns of the matrix in ascending or
        descending degree (depending on x).  If x is null, then only use the
        monomial order in the sort

Further information
===================

  * Default value: null
  * Function: sortColumns, -- permutation giving sort order
  * Option key: DegreeOrder, -- sort primarily by degree

Caveat
======

This option only works for sorting columns of a matrix, not the elements of a
list

Functions with optional argument named DegreeOrder:
===================================================

  * rsort(...,DegreeOrder=>...)
    -- specify Ascending,
    Descending, or null
  * sort(...,DegreeOrder=>...)
    -- specify Ascending,
    Descending, or null
  * sortColumns(...,DegreeOrder=>...)
    -- specify Ascending,
    Descending, or null

sortColumns(...,MonomialOrder=>...) -- specify Ascending or Descending monomial order
*************************************************************************************

Synopsis
========

  * Usage:
        sortColumns(...,MonomialOrder=>x)
  * Inputs:
      * x, a symbol, either Ascending, or
        Descending,
  * Consequences:
      * After the degree order has been considered, sort the columns of the
        matrix in Ascending or Descending monomial order

Further information
===================

  * Default value: Ascending,
  * Function: sortColumns, -- permutation giving sort order
  * Option key: MonomialOrder, -- monomial ordering

Caveat
======

This option only works for sorting columns of a matrix, not the elements of a
list

Functions with optional argument named MonomialOrder:
=====================================================

  * "graphIdeal(...,MonomialOrder=>...)" -- see graphIdeal(RingMap),
    -- the ideal of the graph of the regular map
    corresponding to a ring map
  * "graphRing(...,MonomialOrder=>...)" -- see graphRing(RingMap),
    -- the coordinate ring of the graph of the regular
    map corresponding to a ring map
  * monoid(...,MonomialOrder=>...)
    -- specify the monomial
    ordering
  * "newRing(...,MonomialOrder=>...)" -- see newRing, -- make a
    copy of a ring, with some features changed
  * "pushForward(...,MonomialOrder=>...)" -- see
    pushForward(RingMap,Module),
  * rsort(...,MonomialOrder=>...)
    -- specify Ascending or
    Descending monomial order
  * sort(...,MonomialOrder=>...)
    -- specify Ascending or
    Descending monomial order
  * sortColumns(...,MonomialOrder=>...)
    -- specify Ascending
    or Descending monomial order
  * "symmetricAlgebra(...,MonomialOrder=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,MonomialOrder=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids
  * "tensor(Ring,Ring,MonomialOrder=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

SortStrategy -- specify a strategy for sorting S-pairs
******************************************************

Description
===========

SortStrategy -- a keyword for an optional argument that specifies the strategy
to be used for sorting S-pairs.

Functions with optional argument named SortStrategy:
====================================================

  * resolution(...,SortStrategy=>...)

For the programmer
==================

The object SortStrategy, is a symbol.

source -- source of a map
*************************

Description
===========

Gives the source of a map of rings, chain complexes or modules

See also
========

  * target -- target of a map

Ways to use source:
===================

  * source(ChainComplexMap) --  find the
    source of a map of chain complexes
  * source(GradedModuleMap) -- find the
    source of a map of graded modules
  * source(Matrix) -- find the source module of
    matrix
  * source(RingMap) -- find the source ring for a
    map of rings
  * source(SheafMap) (missing documentation)

For the programmer
==================

The object source, is a method function.

source(ChainComplexMap) --  find the source of a map of chain complexes
***********************************************************************

Synopsis
========

  * Function: source,
  * Usage:
        source f
  * Inputs:
      * f, a chain complex map,
  * Outputs:
      * the source chain complex of f

Description
===========

In the example below, we have a map between two modules and extend it to a map
between projective resolutions of the two modules. Then source gives the source
of the map of chain complexes.
+----------------------------------+
|i1 : R = ZZ[x,y,z];               |
+----------------------------------+
|i2 : M = R^1/(x,y,z);             |
+----------------------------------+
|i3 : N = R^1/(x^2,y^2,x*y*z,z^2); |
+----------------------------------+
|i4 : g = map(N,M,x*y);            |
|                                  |
|o4 : Matrix N <-- M               |
+----------------------------------+
|i5 : f = res g;                   |
+----------------------------------+
|i6 : source f                     |
|                                  |
|      1      3      3      1      |
|o6 = R  <-- R  <-- R  <-- R  <-- 0|
|                                  |
|     0      1      2      3      4|
|                                  |
|o6 : ChainComplex                 |
+----------------------------------+
(That was an expensive way of resolving M.)

Ways to use this method:
========================

  * source(ChainComplexMap) --  find the
    source of a map of chain complexes

source(GradedModuleMap) -- find the source of a map of graded modules
*********************************************************************

Synopsis
========

  * Function: source,
  * Usage:
        source f
  * Inputs:
      * f
  * Outputs:
      * a graded module,

Ways to use this method:
========================

  * source(GradedModuleMap) -- find the
    source of a map of graded modules

source(Matrix) -- find the source module of matrix
**************************************************

Synopsis
========

  * Function: source,
  * Usage:
        source f
  * Inputs:
      * f, a matrix,
  * Outputs:
      * the source module of f

Description
===========

+---------------------------------+
|i1 : R = ZZ[x,y,z];              |
+---------------------------------+
|i2 : M = R^1/(x,y,z);            |
+---------------------------------+
|i3 : N = R^1/(x^2,y^2,x*y*z,z^2);|
+---------------------------------+
|i4 : g = map(N,M,x*y);           |
|                                 |
|o4 : Matrix N <-- M              |
+---------------------------------+
|i5 : source g                    |
|                                 |
|o5 = cokernel | x y z |          |
|                                 |
|                            1    |
|o5 : R-module, quotient of R     |
+---------------------------------+

Ways to use this method:
========================

  * source(Matrix) -- find the source module of
    matrix

source(RingMap) -- find the source ring for a map of rings
**********************************************************

Synopsis
========

  * Function: source,
  * Usage:
        source f
  * Inputs:
      * f
  * Outputs:
      * the source ring of the map

Description
===========

+-------------------------------+
|i1 : S = ZZ/10007[x, y, z];    |
+-------------------------------+
|i2 : R = ZZ/10007[t];          |
+-------------------------------+
|i3 : f = map(R,S,{t^3,t^4,t^5})|
|                               |
|                  3   4   5    |
|o3 = map (R, S, {t , t , t })  |
|                               |
|o3 : RingMap R <-- S           |
+-------------------------------+
|i4 : source f                  |
|                               |
|o4 = S                         |
|                               |
|o4 : PolynomialRing            |
+-------------------------------+

Ways to use this method:
========================

  * source(RingMap) -- find the source ring for a
    map of rings

span -- construct smallest interval
***********************************

Description
===========

Returns the smallest interval containing the inputs (which can include
intervals).  Typically, the returned interval is not empty.  See
span(Sequence), and span(List),

See also
========

  * interval -- construct an interval
  * span(Sequence) -- construct smallest interval
  * span(List) -- construct smallest interval
  * toRRi -- construct an interval

Ways to use span:
=================

  * span(List) -- construct smallest interval
  * span(Sequence) -- construct smallest interval

For the programmer
==================

The object span, is a method function with a single argument.

span(List) -- construct smallest interval
*****************************************

Synopsis
========

  * Function: span,
  * Usage:
        I = span(L)
        I = span(L,Precision => prec)
  * Inputs:
      * L, a list, containing Number, (including
        RRi)
  * Optional inputs,:
      * Precision => an integer, default value -1, specifies the
        desired precision of the output, a value of -1 uses the minimum
        precision of the inputs.
  * Outputs:
      * I, a real interval,

Description
===========

Returns the smallest interval containing the inputs (which can include
intervals).  Typically, the returned interval is not empty.

See also
========

  * interval -- construct an interval
  * span(Sequence) -- construct smallest interval
  * toRRi -- construct an interval

Ways to use this method:
========================

  * span(List) -- construct smallest interval

span(Sequence) -- construct smallest interval
*********************************************

Synopsis
========

  * Function: span,
  * Usage:
        I = span(S)
        I = span(S,Precision => prec)
  * Inputs:
      * S, a sequence, containing Number,
        (including RRi)
  * Optional inputs,:
      * Precision => an integer, default value -1, specifies the
        desired precision of the output, a value of -1 uses the minimum
        precision of the inputs.
  * Outputs:
      * I, a real interval,

Description
===========

Returns the smallest interval containing the inputs (which can include
intervals).  Typically, the returned interval is not empty.

See also
========

  * interval -- construct an interval
  * span(List) -- construct smallest interval
  * toRRi -- construct an interval

Ways to use this method:
========================

  * span(Sequence) -- construct smallest interval

SparseMonomialVectorExpression -- the class of all sparse monomial vector expressions
*************************************************************************************

Description
===========

SparseMonomialVectorExpression is a type of Expression,
representing a sparse monomial vector.

The difference between this and SparseVectorExpression,
is that the basis vectors are treated like variables
for printing purposes.

For the programmer
==================

The object SparseMonomialVectorExpression,
is a header type, with
ancestor classes Expression, < BasicList <
Thing.

SparseVectorExpression -- the class of all sparse vector expressions
********************************************************************

Description
===========

SparseVectorExpression is a type of Expression, representing
a sparse vector.

For the programmer
==================

The object SparseVectorExpression, is a
header type, with ancestor classes Expression, <
BasicList < Thing.

splice -- remove subsequences from a sequence or list
*****************************************************

Synopsis
========

  * Usage:
        splice X
  * Inputs:
      * X, a basic list,
  * Outputs:
      * Y, a basic list, the new list resulting from
        replacing each element of X that is a sequence with its elements

Description
===========

Unlike the function deepSplice, which recursively flattens
subsequences at all levels, splice removes the outermost nested level of
subsequences only.

+------------------------------------------------------+
|i1 : X = {(), (0, (1, 2, (3, 4))), (5, (6, 7)), 8, 9};|
+------------------------------------------------------+
|i2 : splice X                                         |
|                                                      |
|o2 = {0, (1, 2, (3, 4)), 5, (6, 7), 8, 9}             |
|                                                      |
|o2 : List                                             |
+------------------------------------------------------+
|i3 : deepSplice X                                     |
|                                                      |
|o3 = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}                   |
|                                                      |
|o3 : List                                             |
+------------------------------------------------------+

splice does not alter elements that are lists, arrays, or anything other than
sequences.

+------------------------------------------------------+
|i4 : Z = {(), {0, {1, 2, (3, 4)}}, [5, [6, 7]], 8, 9};|
+------------------------------------------------------+
|i5 : splice Z                                         |
|                                                      |
|o5 = {{0, {1, 2, (3, 4)}}, [5, [6, 7]], 8, 9}         |
|                                                      |
|o5 : List                                             |
+------------------------------------------------------+

splice works on sequences, too, and all other objects of class,
BasicList. The output matches the class of the input.

+--------------------------------------------------------+
|i6 : splice ((), (0, (1, 2, (3, 4))), (5, (6, 7)), 8, 9)|
|                                                        |
|o6 = (0, (1, 2, (3, 4)), 5, (6, 7), 8, 9)               |
|                                                        |
|o6 : Sequence                                           |
+--------------------------------------------------------+
|i7 : splice [(), (0, (1, 2, (3, 4))), (5, (6, 7)), 8, 9]|
|                                                        |
|o7 = [0, (1, 2, (3, 4)), 5, (6, 7), 8, 9]               |
|                                                        |
|o7 : Array                                              |
+--------------------------------------------------------+

Even if X is a MutableList, splice returns a new list
rather than altering the definition of X.

+-------------------------------+
|i8 : M = new MutableList from X|
|                               |
|o8 = MutableList{...5...}      |
|                               |
|o8 : MutableList               |
+-------------------------------+
|i9 : splice M                  |
|                               |
|o9 = MutableList{...6...}      |
|                               |
|o9 : MutableList               |
+-------------------------------+
|i10 : M                        |
|                               |
|o10 = MutableList{...5...}     |
|                               |
|o10 : MutableList              |
+-------------------------------+

See also
========

  * deepSplice -- remove all levels of subsequences from a
    sequence or list
  * flatten -- flatten a nested list or a matrix
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use splice:
===================

  * "splice(BasicList)"

For the programmer
==================

The object splice, is a compiled function.

splitWWW -- separate an http response into header and body
**********************************************************

Synopsis
========

  * Usage:
        (head, body) = splitWWW str
  * Inputs:
      * str, a string, an http response, such as that returned
        by getWWW.
  * Outputs:
      * head, a string, the header of the response
      * body, a string, the response body, which has been
        'unchunked', if the response type is chunked.

Description
===========

The format of chunked data is described here (see https://www.w3.org/Protocols/
).

The following is an example obtaining 5 examples from the Kreuzer-Skarke
database for 4 dimensional reflexive polytopes.  We retrieve 5 examples each
having the anti-canonical divisor a Calabi-Yau with $h^{(1,1)} = 10$.

+-----------------------------------------------------------------------------+
|i1 : str = getWWW "http://quark.itp.tuwien.ac.at/cgi-bin/cy/cydata.cgi?h11=10|
|-----------------------------------------------------------------------------|
|&L=5";                                                                       |
+-----------------------------------------------------------------------------+
|i2 : (head,body) = splitWWW str;                                             |
+-----------------------------------------------------------------------------+
|i3 : head                                                                    |
|                                                                             |
|o3 = HTTP/1.1 200 OK                                                         |
|     Date: Thu, 23 Jun 2016 12:10:58 GMT                                     |
|     Server: Apache/2.2                                                      |
|     Vary: Accept-Encoding                                                   |
|     Connection: close                                                       |
|     Transfer-Encoding: chunked                                              |
|     Content-Type: text/html; charset=UTF-8                                  |
+-----------------------------------------------------------------------------+
|i4 : body                                                                    |
|                                                                             |
|o4 = <head><title>SEARCH RESULTS</title></head>                              |
|     <body><pre><b>Search command:</b>                                       |
|     class.x -di x -He EH10:MVNFL5                                           |
|                                                                             |
|     <b>Result:</b>                                                          |
|     4 9  M:22 9 N:14 8 H:10,18 [-16]                                        |
|        1   0   1   0   2   0  -2  -2  -2                                    |
|        0   1   0   0  -1   1   1  -1   1                                    |
|        0   0   2   0   1   1  -3  -1  -4                                    |
|        0   0   0   1   1   1  -1  -1  -2                                    |
|     4 10  M:23 10 N:15 10 H:10,18 [-16]                                     |
|         1    0    0    0   -1    1   -2    2    0   -1                      |
|         0    1    0    0    1   -1    2   -1   -2    0                      |
|         0    0    1    0   -1    1   -1    0    2   -2                      |
|         0    0    0    1    1   -1    0   -2   -1    2                      |
|     4 9  M:24 9 N:14 8 H:10,20 [-20]                                        |
|        1   0   1   0   1  -1  -2   1  -2                                    |
|        0   1   0   0   0   2  -2  -1   2                                    |
|        0   0   2   0  -1  -1   0  -2  -2                                    |
|        0   0   0   1  -1  -1   1  -1  -1                                    |
|     4 11  M:25 11 N:15 10 H:10,20 [-20]                                     |
|        1   0   0   0   2  -2   0   2  -2  -2   2                            |
|        0   1   0   0  -1   1   1  -1   0   1  -2                            |
|        0   0   1   0  -1   1  -1   0   2   0  -2                            |
|        0   0   0   1  -1   1   1  -2   1   0  -1                            |
|     4 10  M:25 10 N:15 10 H:10,20 [-20]                                     |
|         1    0    0    0   -1    0   -1   -1    2    1                      |
|         0    1    0    0    0    0    2    0   -1   -2                      |
|         0    0    1    0    0   -2    2    2   -2   -2                      |
|         0    0    0    1    0   -1    0    2    0   -2                      |
|     Exceeded limit of 5                                                     |
|     </pre></body>                                                           |
+-----------------------------------------------------------------------------+

See also
========

  * getWWW -- get a web page

Ways to use splitWWW:
=====================

  * "splitWWW(String)"

For the programmer
==================

The object splitWWW, is a method function.

sqrt -- square root function
****************************

Synopsis
========

  * Usage:
        sqrt x
        sqrt I
  * Inputs:
      * x, a real number,
      * I, a real interval,
  * Outputs:
      * the square root of x
      * a real interval, an interval containing the square roots of
        the points of I

Description
===========

+------------------------------------------------------------------+
|i1 : sqrt 2p200                                                   |
|                                                                  |
|o1 = 1.41421356237309504880168872420969807856967187537694807317668|
|                                                                  |
|o1 : RR (of precision 200)                                        |
+------------------------------------------------------------------+
|i2 : sqrt (+ii)                                                   |
|                                                                  |
|o2 = .7071067811865476+.7071067811865475*ii                       |
|                                                                  |
|o2 : CC (of precision 53)                                         |
+------------------------------------------------------------------+

Ways to use sqrt:
=================

  * "sqrt(CC)"
  * "sqrt(RR)"
  * "sqrt(RRi)"

For the programmer
==================

The object sqrt, is a method function.

Standard -- the standard top level printing method
**************************************************

Description
===========

This symbol is used (tentatively) as the first element of a pair to specify
various top level interpreter methods.

See also
========

  * TeXmacs -- the TeXmacs top level printing method
  * Print -- top level method for printing results
  * NoPrint -- top level method for non-printing results
  * BeforePrint -- top level method applied before printing
    results
  * AfterPrint -- top level method applied after printing
  * AfterNoPrint -- top level method applied after not
    printing

For the programmer
==================

The object Standard, is a symbol.

standardForm -- convert to standard form
****************************************

Synopsis
========

  * Usage:
        standardForm f
  * Outputs:
      * a hash table, the polynomial or monomial in a form
        involving hash tables.

Description
===========

A polynomial is represented by hash tables in which the keys are hash tables
representing the monomials and the values are the coefficients. The monomials
themselves are represented by hash tables in which the keys are the variables
and the values are the corresponding exponents.

+------------------------------------------+
|i1 : R = ZZ/101[x,y,z];                   |
+------------------------------------------+
|i2 : standardForm (x^2 - 7 + x*y*z^11 + y)|
|                                          |
|o2 = HashTable{HashTable{} => -7      }   |
|               HashTable{0 => 1 } => 1    |
|                         1 => 1           |
|                         2 => 11          |
|               HashTable{0 => 2} => 1     |
|               HashTable{1 => 1} => 1     |
|                                          |
|o2 : HashTable                            |
+------------------------------------------+

Code
====

../../../../../Macaulay2/m2/monoids.m2:146:30-150:86: --source code:
standardForm RingElement   := f -> (
    R := ring f;
    k := coefficientRing R;
    (cc, mm) := rawPairs(raw k, raw f);
    new HashTable from toList apply(cc, mm, (c, m) -> (standardForm m, new k
-------------------------------------------------------------------------------
from c)))

See also
========

  * listForm -- convert to list form
  * content -- the content of a polynomial
  * coefficients -- monomials and their coefficients
  * exponents -- the exponents of a polynomial
  * monomials -- matrix of monomials in a ring element or
    matrix

Ways to use standardForm:
=========================

  * "standardForm(MonoidElement)"
  * "standardForm(RingElement)"

For the programmer
==================

The object standardForm, is a method function.

standardPairs -- find the standard pairs of a monomial ideal
************************************************************

Synopsis
========

  * Usage:
        standardPairs I
  * Inputs:
      * I, a monomial ideal,
  * Outputs:
      * a List, of standard pairs for I

Description
===========

The standard monomials of a monomial ideal I (those monomials that are not in
I) can be enumerated as follows.  Given a monomial m and a subset F of the
variables, the pair (m,F) indexes the set of monomials of the form mm' where
the monomial m' is supported on F.  A List, of pairs (m, F) form
standard pairs for the monomial ideal I if it satisfies the following three
conditions:
  * for each pair, the monomial m is supported on the complement of F;
  * all of the monomials represented by a pair are standard;
  * the pairs index disjoint sets of monomials.
+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = monomialIdeal(x*y^3*z, x*y^2*z^2, y^3*z^2, y^2*z^3)                 |
|                                                                             |
|                       3      2 2   3 2   2 3                                |
|o2 = monomialIdeal (x*y z, x*y z , y z , y z )                               |
|                                                                             |
|o2 : MonomialIdeal of R                                                      |
+-----------------------------------------------------------------------------+
|i3 : standardPairs I                                                         |
|                                                                             |
|                                                         2           2 2     |
|o3 = {{1, {x, z}}, {y, {x, z}}, {1, {x, y}}, {z, {y}}, {y z, {x}}, {y z ,    |
|     ------------------------------------------------------------------------|
|     {}}}                                                                    |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

The standard pairs are computed with Algorithm 3.2.5 in Gröbner Deformations of
Hypergeometric Differential Equations, by Mutsumi Saito, Bernd Sturmfels and
Nobuki Takayama; Algorithms and Computation in Mathematics 6, Springer-Verlag,
2000. Implemented by Gregory G. Smith.

For more information, see the Monomial ideals chapter in Computations in
algebraic geometry with Macaulay2, edited by David Eisenbud, Daniel R. Grayson,
Michael E. Stillman, and Bernd Sturmfels, Algorithms and Computations in
Mathematics 8, Springer-Verlag, 2001.

Ways to use standardPairs:
==========================

  * "standardPairs(MonomialIdeal)"
  * "standardPairs(MonomialIdeal,List)"

For the programmer
==================

The object standardPairs, is a method function.

stashValue -- stash values of functions in their arguments
**********************************************************

Synopsis
========

  * Usage:
        ((stashValue KEY) f) x
  * Inputs:
      * KEY
      * f, a function,
      * x, a mutable hash table, an argument for f
  * Outputs:
      * The value of f x is returned, but the value is saved in x#KEY and not
        recomputed later. However, if the value found in x#KEY is an a cache function,
        such as is returned by (stashValue KEY)
        f, then the value of x#KEY x is returned instead, after first removing
        x#KEY from x.

Description
===========

+--------------------------------------------------+
|i1 : x = new MutableHashTable from { val => 1000 }|
|                                                  |
|o1 = MutableHashTable{...1...}                    |
|                                                  |
|o1 : MutableHashTable                             |
+--------------------------------------------------+
|i2 : f = (t -> (print "hi there"; t.val^4))       |
|                                                  |
|o2 = f                                            |
|                                                  |
|o2 : FunctionClosure                              |
+--------------------------------------------------+
|i3 : h = (stashValue VALUE) f                     |
|                                                  |
|o3 = -*a cache function*-                         |
|                                                  |
|o3 : CacheFunction                                |
+--------------------------------------------------+
|i4 : h x                                          |
|hi there                                          |
|                                                  |
|o4 = 1000000000000                                |
+--------------------------------------------------+
|i5 : h x                                          |
|                                                  |
|o5 = 1000000000000                                |
+--------------------------------------------------+
|i6 : peek x                                       |
|                                                  |
|o6 = MutableHashTable{val => 1000           }     |
|                      VALUE => 1000000000000      |
+--------------------------------------------------+

Code
====

../../../../../Macaulay2/m2/methods.m2:695:13-703:28: --source code:
stashValue = key -> f -> new CacheFunction from (x -> (
          if x#?key then (
               val := x#key;
               if class val === CacheFunction then (
                    remove(x,key);
                    x#key = val x)
               else val
               )
          else x#key = f x))

See also
========

  * cacheValue -- cache values of functions in their
    arguments

For the programmer
==================

The object stashValue, is a function closure.

status -- status of a resolution computation
********************************************

Description
===========

status C -- displays the status of the computation of a chain complex C
constructed by application of resolution, to a module,
provided the resolution has been constructed in the engine; in particular, the
module should be homogeneous and the ultimate coefficient ring of its ring
should be a field.  The display has the same shape as the display produced by
betti, but the number(s) displayed in each degree differ.

Options:
  * TotalPairs -- display the total number of S-pairs,
    default value true
  * PairsRemaining -- display the number of S-pairs
    remaining, default value false
  * Monomials -- display the number of monomials, default
    value false
+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..d]                                                            |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : D = res coker random(R^2,R^{4:-2})                                      |
|                                                                             |
|      2      4      4      2                                                 |
|o2 = R  <-- R  <-- R  <-- R  <-- 0                                           |
|                                                                             |
|     0      1      2      3      4                                           |
|                                                                             |
|o2 : ChainComplex                                                            |
+-----------------------------------------------------------------------------+
|i3 : status(D, TotalPairs => true, PairsRemaining => true, Monomials => true)|
|                                                                             |
|o3 = (total pairs,pairs remaining,monomials)                                 |
|                                                                             |
|     total: (2,0,0) (4,0,549) (20,0,1156) (8,0,410)                          |
|         0: (2,0,0)     .          .          .                              |
|         1:    .    (4,0,74)   (2,0,12)       .                              |
|         2:    .    (0,0,51)   (2,0,36)       .                              |
|         3:    .    (0,0,79)   (4,0,48)   (2,0,22)                           |
|         4:    .    (0,0,210)  (8,0,405)  (4,0,79)                           |
|         5:    .    (0,0,135)  (4,0,655)  (2,0,309)                          |
+-----------------------------------------------------------------------------+

Ways to use status:
===================

  * "status(ChainComplex)"
  * "status(GroebnerBasis)"
  * "status(Resolution)"
  * status(ProgramRun) -- get the return status
    of a program run

For the programmer
==================

The object status, is a method function with options.

status(ProgramRun) -- get the return status of a program run
************************************************************

Synopsis
========

  * Function: status,
  * Usage:
        status pr
  * Inputs:
      * pr, an instance of the type ProgramRun,
  * Optional inputs,:
      * Monomials, => ..., default value false, status of a
        resolution computation
      * PairsRemaining, => ..., default value false, status of a
        resolution computation
      * TotalPairs, => ..., default value true, status of a
        resolution computation
  * Outputs:
      * an integer,

Description
===========

Get the return status of a program run.  Usually, 0 means that it was
successful.

+---------------------------------------------+
|i1 : normaliz = findProgram "normaliz"       |
|                                             |
|o1 = normaliz                                |
|                                             |
|o1 : Program                                 |
+---------------------------------------------+
|i2 : status runProgram(normaliz, "--version")|
|                                             |
|o2 = 0                                       |
+---------------------------------------------+

See also
========

  * findProgram -- load external program
  * runProgram -- run an external program

Ways to use this method:
========================

  * status(ProgramRun) -- get the return status
    of a program run

stderr -- the standard error output file
****************************************

Synopsis
========

  * Usage:
        stderr
  * Outputs:
      * the standard error output file

Description
===========

Macaulay2 uses this file to display error messages on the user's screen.  In
unix, it corresponds to file descriptor 2.  The user may use this file to
display warning messages.

See also
========

  * stdio -- the standard input output file

For the programmer
==================

The object stderr, is a file.

stdio -- the standard input output file
***************************************

Synopsis
========

  * Usage:
        stdio
  * Outputs:
      * the standard input output file

Description
===========

Use this file to get input from the terminal, or to display information on the
user's screen.  This is the file always used by print, and
<<, if it is not explicitly given a file.

+--------------------------+
|i1 : << "hi" << endl      |
|hi                        |
|                          |
|o1 = stdio                |
|                          |
|o1 : File                 |
+--------------------------+
|i2 : stdio << "hi" << endl|
|hi                        |
|                          |
|o2 = stdio                |
|                          |
|o2 : File                 |
+--------------------------+

See also
========

  * stderr -- the standard error output file
  * File << Thing -- print to a file

For the programmer
==================

The object stdio, is a file.

step -- step by single lines in the debugger
********************************************

Synopsis
========

  * Usage:
        step n
  * Inputs:
      * n, an integer,
  * Consequences:
      * This command is active within the debugger.  The current expression is
        executed and execution is continued until n lines of source code whose
        load depth is as large as errorDepth, have been
        encountered.  If n is omitted, then 1 is used.  If n is negative then
        instead, n microsteps in the inner interpreter are executed and traced.

Description
===========

One useful way to debug code suspected of being in error is to insert an
explicit error message, such as error "debug me", and start stepping from
there, as in the following demonstration.

+-----------------------------------------------------------------------------+
|i1 : load "Macaulay2Doc/demo2.m2"                                            |
+-----------------------------------------------------------------------------+
|i2 : code f                                                                  |
|                                                                             |
|o2 = /usr/local/share/Macaulay2/Macaulay2Doc/                                |
|     demo2.m2:6:4-12:6: --source code:                                       |
|     f = t -> (                                                              |
|          x := 1;                                                            |
|          error "debug me";                                                  |
|          y := t+1;                                                          |
|          z := 1/t;                                                          |
|          w := x+t;                                                          |
|          )                                                                  |
+-----------------------------------------------------------------------------+
|i3 : f 0                                                                     |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:8:10:(3):[1]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:8:10:(3):[1]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:                            |
|8:5-8:21: --source code:                                                     |
|     error "debug me";                                                       |
|-----------------------------------------------------------------------------|
|error: debug me                                                              |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
|ii4 : return                                                                 |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:9:11:(3):[1]: --stepping    |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:9:11:(3):[1]: --entering    |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:                            |
|9:5-9:13: --source code:                                                     |
|     y := t+1;                                                               |
|-----------------------------------------------------------------------------|
|limit reached                                                                |
|debugger (type help to see debugger commands)                                |
+-----------------------------------------------------------------------------+
|ii5 : current                                                                |
|                                                                             |
|oo5 = local-assign 2 0 2-OP + local-fetch 0 0                                |
|                              1                                              |
|                                                                             |
|oo5 : PseudocodeClosure                                                      |
+-----------------------------------------------------------------------------+
|ii6 : disassemble oo                                                         |
|                                                                             |
|oo6 = (local-assign 2 0 (2-OP + (local-fetch 0 0) 1))                        |
+-----------------------------------------------------------------------------+
|ii7 : step(-3)                                                               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:9:11:(3):[1]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:9:11:(3):[1]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:9:10:(3):[1]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:9:12:(3):[1]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:9:12:(3):[1]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:                            |
|9:12-9:13: --source code:                                                    |
|     y := t+1;                                                               |
|-----------------------------------------------------------------------------|
|--evaluating: (local-assign 2 0 (2-OP + (local-fetch 0 0) 1))                |
|--evaluating: (2-OP + (local-fetch 0 0) 1)                                   |
|--evaluating: (local-fetch 0 0)                                              |
|--stepping limit reached                                                     |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
|ii8 : step                                                                   |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:10:11:(3):[1]: --stepping   |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:10:11:(3):[1]: --entering   |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:                            |
|10:5-10:13: --source code:                                                   |
|     z := 1/t;                                                               |
|-----------------------------------------------------------------------------|
|limit reached                                                                |
|debugger (type help to see debugger commands)                                |
+-----------------------------------------------------------------------------+
|ii9 : step                                                                   |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:10:11:(3):[1]:              |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:10:11:(3):[1]:              |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo2.m2:                            |
|10:10-10:13: --source code:                                                  |
|     z := 1/t;                                                               |
|-----------------------------------------------------------------------------|
|error: division by zero                                                      |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
|ii10 : t                                                                     |
|                                                                             |
|oo10 = 0                                                                     |
+-----------------------------------------------------------------------------+

See also
========

  * debugging

For the programmer
==================

The object step, is a keyword.

stopIfError -- whether to stop the program when an error occurs
***************************************************************

Description
===========

This can be useful for showing code in documentation examples that results in
an error being raised.  For an example, see assert.

For the programmer
==================

The object stopIfError, is a Boolean value.

StopIteration -- stop iteration
*******************************

Description
===========

This symbol is returned by next, to signal that iteration is
complete.

+------------------------------+
|i1 : iter = iterator {1, 2, 3}|
|                              |
|o1 = iter                     |
|                              |
|o1 : Iterator                 |
+------------------------------+
|i2 : next iter                |
|                              |
|o2 = 1                        |
+------------------------------+
|i3 : next iter                |
|                              |
|o3 = 2                        |
+------------------------------+
|i4 : next iter                |
|                              |
|o4 = 3                        |
+------------------------------+
|i5 : next iter                |
|                              |
|o5 = StopIteration            |
|                              |
|o5 : Symbol                   |
+------------------------------+

See also
========

  * Iterator -- class for iterators
  * iterator -- get an iterator
  * next -- get the next object from an iterator

For the programmer
==================

The object StopIteration, is a symbol.

store -- store the value of an atomic integer
*********************************************

Synopsis
========

  * Usage:
        store(x, y)
  * Inputs:
      * x, an atomic integer,
      * y, an integer,

Description
===========

The value of y is stored in x and null, is returned.  This
operation occurs atomically and is thread safe.

+----------------------+
|i1 : x = new AtomicInt|
|                      |
|o1 = 0                |
|                      |
|o1 : AtomicInt        |
+----------------------+
|i2 : store(x, 5)      |
+----------------------+
|i3 : x                |
|                      |
|o3 = 5                |
|                      |
|o3 : AtomicInt        |
+----------------------+

Ways to use store:
==================

  * "store(AtomicInt,ZZ)"

For the programmer
==================

The object store, is a method function.

String .. String -- a sequence of consecutive strings
*****************************************************

Synopsis
========

  * Operator: ..,
  * Usage:
        s .. t
  * Inputs:
      * s
      * t
  * Outputs:
      * the sequence of consecutive strings of the same length, from s to t, in
        lexicographic order, inclusive

Description
===========

+-----------------------------------------------------------------------------+
|i1 : "a" .. "z"                                                              |
|                                                                             |
|o1 = (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x,|
|     ------------------------------------------------------------------------|
|     y, z)                                                                   |
|                                                                             |
|o1 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i2 : "aa" .. "ce"                                                            |
|                                                                             |
|o2 = (aa, ab, ac, ad, ae, ba, bb, bc, bd, be, ca, cb, cc, cd, ce)            |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i3 : "aaa" .. "abc"                                                          |
|                                                                             |
|o3 = (aaa, aab, aac, aba, abb, abc)                                          |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i4 : "佖" .. "佥"                                                              |
|                                                                             |
|o4 = (佖, 佗, 佘, 余, 佚, 佛, 作, 佝, 佞, 佟, 你, 佡, 佢, 佣, 佤, 佥)                        |
|                                                                             |
|o4 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * String ..< String -- a sequence of
    consecutive strings, not including the endpoint

Ways to use this method:
========================

  * String .. String -- a sequence of consecutive
    strings

String ..< String -- a sequence of consecutive strings, not including the endpoint
**********************************************************************************

Synopsis
========

  * Operator: ..<,
  * Usage:
        s ..< t
  * Inputs:
      * s
      * t
  * Outputs:
      * the sequence of consecutive strings of the same length, from s to t, in
        lexicographic order, inclusive

Description
===========

+-----------------------------------------------------------------------------+
|i1 : "a" ..< "z"                                                             |
|                                                                             |
|o1 = (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x,|
|     ------------------------------------------------------------------------|
|     y)                                                                      |
|                                                                             |
|o1 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i2 : "aa" ..< "ce"                                                           |
|                                                                             |
|o2 = (aa, ab, ac, ad, ba, bb, bc, bd)                                        |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i3 : "aaa" ..< "bcd"                                                         |
|                                                                             |
|o3 = (aaa, aab, aac, aba, abb, abc)                                          |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i4 : "佖" ..< "佥"                                                             |
|                                                                             |
|o4 = (佖, 佗, 佘, 余, 佚, 佛, 作, 佝, 佞, 佟, 你, 佡, 佢, 佣, 佤)                           |
|                                                                             |
|o4 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * String .. String -- a sequence of consecutive
    strings

Ways to use this method:
========================

  * String ..< String -- a sequence of
    consecutive strings, not including the endpoint

String ^ Sequence -- vertically stacked copies of a string
**********************************************************

Synopsis
========

  * Operator: ^,
  * Usage:
        s^(height,depth)
  * Inputs:
      * s
      * (height,depth), a pair of integers
  * Outputs:
      * a net, height + depth copies of s, stacked vertically.
        There are depth lines below the base line

Description
===========

+-------------------------------+
|i1 : s = "|"                   |
|                               |
|o1 = |                         |
+-------------------------------+
|i2 : s^(4,3)                   |
|                               |
|     |                         |
|     |                         |
|     |                         |
|o2 = |                         |
|     |                         |
|     |                         |
|     |                         |
+-------------------------------+
|i3 : n = net(x_0)              |
|                               |
|o3 = x                         |
|      0                        |
+-------------------------------+
|i4 : n0 = s^(height n, depth n)|
|                               |
|o4 = |                         |
|     |                         |
+-------------------------------+
|i5 : n0|n|n0                   |
|                               |
|o5 = |x |                      |
|     | 0|                      |
+-------------------------------+

See also
========

  * strings and nets -- an overview of strings and
    nets in Macaulay2
  * height -- height of a net
  * depth -- depth of a net

Ways to use this method:
========================

  * String ^ Sequence -- vertically stacked copies of
    a string

String _ Ring -- get a ring variable by name
********************************************

Synopsis
========

  * Operator: _,
  * Usage:
        "x"_R
  * Inputs:
      * R
      * "x", a string,
  * Outputs:
      * a ring element, the variable of R whose name is x

Description
===========

+-------------------+
|i1 : R = ZZ[x,y,z];|
+-------------------+
|i2 : use R;        |
+-------------------+
|i3 : S = ZZ[x,t];  |
+-------------------+
|i4 : x             |
|                   |
|o4 = x             |
|                   |
|o4 : S             |
+-------------------+
The symbol x now refers to the variable x in the ring S. There are several ways
of now referring to x in the ring R.
+-----------+
|i5 : R_0   |
|           |
|o5 = x     |
|           |
|o5 : R     |
+-----------+
|i6 : "x"_R |
|           |
|o6 = x     |
|           |
|o6 : R     |
+-----------+
|i7 : use R;|
+-----------+
|i8 : x     |
|           |
|o8 = x     |
|           |
|o8 : R     |
+-----------+

See also
========

  * Ring _ ZZ -- get a ring variable by index
  * Symbol _ Ring -- get a ring variable by name
  * use(Ring) -- install ring variables and ring
    operations

Ways to use this method:
========================

  * String _ Ring -- get a ring variable by name

sublists -- process interspersed subsequences of a visible list
***************************************************************

Synopsis
========

  * Usage:
        sublists(L, f, g, h)
  * Inputs:
      * L, a visible list,
      * f, a function, returning Boolean values
      * g, a function, which acts on VisibleLists, applied to
        sublists of L with f(i) true for each i in the sublist
      * h, a function, which acts on elements of L, applied to
        the elements i of L with f(i) false
  * Outputs:
      * a list, the result obtained by applying g to each of the
        maximal nonempty sequences of consecutive elements with f true, and
        applying h to the other elements

Description
===========

In the first example, consecutive odd elements are grouped into sublists, while
each even element is negated.

+-----------------------------------------------------------------+
|i1 : L = {1,2,3,5,7,8,10,12,13,17,18,20,21};                     |
+-----------------------------------------------------------------+
|i2 : sublists(L, odd, toList, minus)                             |
|                                                                 |
|o2 = {{1}, -2, {3, 5, 7}, -8, -10, -12, {13, 17}, -18, -20, {21}}|
|                                                                 |
|o2 : List                                                        |
+-----------------------------------------------------------------+

If g or h is omitted, the identity, function is used in its
place.

+-----------------------------------------------------------+
|i3 : sublists(L, odd, toList)                              |
|                                                           |
|o3 = {{1}, 2, {3, 5, 7}, 8, 10, 12, {13, 17}, 18, 20, {21}}|
|                                                           |
|o3 : List                                                  |
+-----------------------------------------------------------+
|i4 : sublists(L, odd)                                      |
|                                                           |
|o4 = {{1}, 2, {3, 5, 7}, 8, 10, 12, {13, 17}, 18, 20, {21}}|
|                                                           |
|o4 : List                                                  |
+-----------------------------------------------------------+

The sublists will belong to the same class as L.

+--------------------------------------------------+
|i5 : L = (1,2,3,5,7,8,10,12,13,17,18,20,21);      |
+--------------------------------------------------+
|i6 : sublists(L, isPrime, , e -> 0)               |
|                                                  |
|o6 = {0, (2, 3, 5, 7), 0, 0, 0, (13, 17), 0, 0, 0}|
|                                                  |
|o6 : List                                         |
+--------------------------------------------------+

Note that g acts on the sublists, not their elements.

+---------------------------------------+
|i7 : sublists(L, isPrime, plus, e -> 0)|
|                                       |
|o7 = {0, 17, 0, 0, 0, 30, 0, 0, 0}     |
|                                       |
|o7 : List                              |
+---------------------------------------+

Because of the grouping of consecutive elements that return true when input to
f, sublists(L, f, g, h) is NOT the same as applying g to elements returning
true, and applying h to elements returning false. This could be achieved with a
simple if,-then-else loop, or with apply.

+-----------------------------------------------------------------+
|i8 : a = for l in L list if isPrime l then l else -10*l          |
|                                                                 |
|o8 = {-10, 2, 3, 5, 7, -80, -100, -120, 13, 17, -180, -200, -210}|
|                                                                 |
|o8 : List                                                        |
+-----------------------------------------------------------------+
|i9 : b = apply(L, l -> if isPrime l then l else -10*l)           |
|                                                                 |
|o9 = (-10, 2, 3, 5, 7, -80, -100, -120, 13, 17, -180, -200, -210)|
|                                                                 |
|o9 : Sequence                                                    |
+-----------------------------------------------------------------+

On the other hand, if we want to group both "true" and "false" elements into
sublists, we can achieve this with a second call to sublists, selecting those
elements not already grouped by the first sublists command, as long as the
original list was not nested.

+------------------------------------------------------------------+
|i10 : X = {1, 3, 5, 2, 4, 7, 1, 3, 4, 4, 5, 4, 7, 9, 13};         |
+------------------------------------------------------------------+
|i11 : sublists(sublists(X, odd), i -> not instance(i, List))      |
|                                                                  |
|o11 = {{1, 3, 5}, {2, 4}, {7, 1, 3}, {4, 4}, {5}, {4}, {7, 9, 13}}|
|                                                                  |
|o11 : List                                                        |
+------------------------------------------------------------------+

See also
========

  * apply -- apply a function to each element
  * partition -- partition a set or list by values of a
    function
  * positions -- which elements of a list satisfy a condition
  * select -- select from a list, hash table, or string
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use sublists:
=====================

  * "sublists(VisibleList,Function)"
  * "sublists(VisibleList,Function,Function)"
  * "sublists(VisibleList,Function,Function,Function)"
  * "sublists(VisibleList,Function,Function,Nothing)"
  * "sublists(VisibleList,Function,Nothing)"
  * "sublists(VisibleList,Function,Nothing,Function)"
  * "sublists(VisibleList,Function,Nothing,Nothing)"

For the programmer
==================

The object sublists, is a method function.

submatrix
*********

Ways to use submatrix:
======================

  * submatrix(Matrix,VisibleList),
    -- select columns
  * "submatrix(MutableMatrix,VisibleList)" -- see
    submatrix(Matrix,VisibleList), --
    select columns
  * submatrix(Matrix,VisibleList,VisibleList)
    -- select part of a
    matrix
  * "submatrix(MutableMatrix,VisibleList,VisibleList)" -- see
    submatrix(Matrix,VisibleList,VisibleList),
    -- select part of a
    matrix

For the programmer
==================

The object submatrix, is a method function.

submatrix' -- exclude rows and/or columns of a matrix
*****************************************************

Synopsis
========

  * Usage:
        submatrix'(f, rows, cols)
        submatrix'(f,,cols)
        submatrix'(f,cols)
        submatrix'(f,rows,)
  * Inputs:
      * f, a map between free modules
      * rows, a visible list, a list of integers denoting
        the choice of rows to exclude. If omitted, exclude no rows
      * cols, a visible list, a list of integers denoting
        the choice of columns to exclude. If omitted, exclude no columns
  * Outputs:
      * a matrix, the submatrix of f with rows and cols left out

Description
===========

Each list of integers may contain ranges and repetitions, as in {3, 5..7, 3:0}.
Excluding a row or column more than once is allowed but has no extra effect.

+------------------------------------+
|i1 : R = ZZ/101[a .. o];            |
+------------------------------------+
|i2 : f = genericMatrix(R, a, 3, 5)  |
|                                    |
|o2 = | a d g j m |                  |
|     | b e h k n |                  |
|     | c f i l o |                  |
|                                    |
|             3      5               |
|o2 : Matrix R  <-- R                |
+------------------------------------+
|i3 : submatrix'(f, {1}, {2})        |
|                                    |
|o3 = | a d j m |                    |
|     | c f l o |                    |
|                                    |
|             2      4               |
|o3 : Matrix R  <-- R                |
+------------------------------------+
|i4 : submatrix'(f, {1}, {2,3,3,2,2})|
|                                    |
|o4 = | a d m |                      |
|     | c f o |                      |
|                                    |
|             2      3               |
|o4 : Matrix R  <-- R                |
+------------------------------------+

+----------------------------+
|i5 : submatrix'(f, {1,3}, ) |
|                            |
|o5 = | a d g j m |          |
|     | c f i l o |          |
|                            |
|             2      5       |
|o5 : Matrix R  <-- R        |
+----------------------------+
|i6 : submatrix'(f, , {1,3} )|
|                            |
|o6 = | a g m |              |
|     | b h n |              |
|     | c i o |              |
|                            |
|             3      3       |
|o6 : Matrix R  <-- R        |
+----------------------------+
|i7 : submatrix'(f, {1,3} )  |
|                            |
|o7 = | a g m |              |
|     | b h n |              |
|     | c i o |              |
|                            |
|             3      3       |
|o7 : Matrix R  <-- R        |
+----------------------------+

See also
========

  * submatrix

Ways to use submatrix':
=======================

  * "submatrix'(Matrix,Nothing,Nothing)"
  * "submatrix'(Matrix,Nothing,VisibleList)"
  * "submatrix'(Matrix,VisibleList)"
  * "submatrix'(Matrix,VisibleList,Nothing)"
  * "submatrix'(Matrix,VisibleList,VisibleList)"

For the programmer
==================

The object submatrix', is a method function.

submatrixByDegrees -- submatrix consisting of rows and columns in an interval or box of degrees
***********************************************************************************************

Synopsis
========

  * Usage:
        submatrixByDegrees(m, targetBox, sourceBox)
  * Inputs:
      * m, a matrix, A matrix between free modules
      * targetBox, a sequence, A sequence of 2 degree vectors,
        (lodegree, hidegree).  All rows whose multi-degree is greater than or
        equal (in each component) to lodegree, and less than or equal to
        hidegree, are selected
      * sourceBox, a sequence, Same as targetBox, except this
        governs which columns are selected
  * Outputs:
      * a matrix, The submatrix of m consisting of those rows
        (respectively columns) whose (multi-)degree lie in the box targetBox,
        (respectively columnBox)

Description
===========

If only one degree (as integer, or list of integers) is given for targetBox or
sourceBox, then only rows or columns that match that exact degree are used.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..d];                                                           |
+-----------------------------------------------------------------------------+
|i2 : I = ideal"a2b-c3,abc-d3,ac2-bd2-cd2,abcd-c4"                            |
|                                                                             |
|             2     3           3     2      2      2     4                   |
|o2 = ideal (a b - c , a*b*c - d , a*c  - b*d  - c*d , - c  + a*b*c*d)        |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : C = res I;                                                              |
+-----------------------------------------------------------------------------+
|i4 : m = C.dd_2                                                              |
|                                                                             |
|o4 = {3} | ac2-bd2-cd2 0           -abc+d3 0        -a3c+a2cd                |
|     {3} | 0           ac2-bd2-cd2 a2b-c3  -acd+cd2 a4-a3d-acd2+cd3          |
|     {3} | -a2b+c3     -abc+d3     0       abd-bd2  -a2c2+ac2d-acd2+cd3      |
|     {4} | 0           0           0       b2+bc-cd a3-bcd-c2d-cd2           |
|     ------------------------------------------------------------------------|
|     -a3c+a2cd                                                               |
|     a4-a3d+a2cd-3acd2-ad3+2cd3+d4                                           |
|     -a2c2-a2bd+ac2d+2abd2-acd2-bd3+cd3                                      |
|     a3-ab2+b2d+acd-c2d-2cd2-d3                                              |
|     ------------------------------------------------------------------------|
|     -a3c+a2cd                                                               |
|     a4-a3d+a2cd-3acd2-ad3+2cd3+d4                                           |
|     -a2c2-a2bd+ac2d+2abd2-acd2-ad3-bd3+cd3+d4                               |
|     a3-ab2+ac2+b2d+acd-c2d-bd2-3cd2-d3                                      |
|     ------------------------------------------------------------------------|
|     -a2bc+a2cd-acd2+d4                        a2cd-acd2            |        |
|     a3b-a3d+abcd+ac2d+a2d2-2bcd2-c2d2-bd3-cd3 -a3d+ac2d+a2d2-c2d2  |        |
|     -abc2-ab2d-abcd+ac2d+b2d2-c2d2+cd3+d4     -abcd+ac2d+bcd2-c2d2 |        |
|     a2b-b3-b2c+bc2-a2d+bcd                    -b2c+c3-a2d+c2d      |        |
|                                                                             |
|             4      9                                                        |
|o4 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i5 : submatrixByDegrees(m, 3, 6)                                             |
|                                                                             |
|o5 = {3} | ac2-bd2-cd2 0           -abc+d3 0        |                        |
|     {3} | 0           ac2-bd2-cd2 a2b-c3  -acd+cd2 |                        |
|     {3} | -a2b+c3     -abc+d3     0       abd-bd2  |                        |
|                                                                             |
|             3      4                                                        |
|o5 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i6 : submatrixByDegrees(m, (3,3), (6,7))                                     |
|                                                                             |
|o6 = {3} | ac2-bd2-cd2 0           -abc+d3 0        -a3c+a2cd                |
|     {3} | 0           ac2-bd2-cd2 a2b-c3  -acd+cd2 a4-a3d-acd2+cd3          |
|     {3} | -a2b+c3     -abc+d3     0       abd-bd2  -a2c2+ac2d-acd2+cd3      |
|     ------------------------------------------------------------------------|
|     -a3c+a2cd                                                               |
|     a4-a3d+a2cd-3acd2-ad3+2cd3+d4                                           |
|     -a2c2-a2bd+ac2d+2abd2-acd2-bd3+cd3                                      |
|     ------------------------------------------------------------------------|
|     -a3c+a2cd                                                               |
|     a4-a3d+a2cd-3acd2-ad3+2cd3+d4                                           |
|     -a2c2-a2bd+ac2d+2abd2-acd2-ad3-bd3+cd3+d4                               |
|     ------------------------------------------------------------------------|
|     -a2bc+a2cd-acd2+d4                        a2cd-acd2            |        |
|     a3b-a3d+abcd+ac2d+a2d2-2bcd2-c2d2-bd3-cd3 -a3d+ac2d+a2d2-c2d2  |        |
|     -abc2-ab2d-abcd+ac2d+b2d2-c2d2+cd3+d4     -abcd+ac2d+bcd2-c2d2 |        |
|                                                                             |
|             3      9                                                        |
|o6 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i7 : submatrixByDegrees(m, (4,4), (7,7))                                     |
|                                                                             |
|o7 = {4} | a3-bcd-c2d-cd2 a3-ab2+b2d+acd-c2d-2cd2-d3                         |
|     ------------------------------------------------------------------------|
|     a3-ab2+ac2+b2d+acd-c2d-bd2-3cd2-d3 a2b-b3-b2c+bc2-a2d+bcd               |
|     ------------------------------------------------------------------------|
|     -b2c+c3-a2d+c2d |                                                       |
|                                                                             |
|             1      5                                                        |
|o7 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+

For multidegrees, the interval is a box.

+--------------------------------------------------------------+
|i8 : S = QQ[a..d, Degrees=>{2:{1,0},2:{0,1}}];                |
+--------------------------------------------------------------+
|i9 : I = ideal(a*d^4, b^3, a^2*d^2, a*b*c*d^3)                |
|                                                              |
|               4   3   2 2         3                          |
|o9 = ideal (a*d , b , a d , a*b*c*d )                         |
|                                                              |
|o9 : Ideal of S                                               |
+--------------------------------------------------------------+
|i10 : C = res I                                               |
|                                                              |
|       1      4      6      4      1                          |
|o10 = S  <-- S  <-- S  <-- S  <-- S  <-- 0                    |
|                                                              |
|      0      1      2      3      4      5                    |
|                                                              |
|o10 : ChainComplex                                            |
+--------------------------------------------------------------+
|i11 : m = C.dd_2                                              |
|                                                              |
|o11 = {3, 0} | 0   -a2d2 0    0   -acd3 -ad4 |                |
|      {2, 2} | -d2 b3    -bcd 0   0     0    |                |
|      {1, 4} | a   0     0    -bc 0     b3   |                |
|      {2, 4} | 0   0     a    d   b2    0    |                |
|                                                              |
|              4      6                                        |
|o11 : Matrix S  <-- S                                         |
+--------------------------------------------------------------+
|i12 : degrees target m                                        |
|                                                              |
|o12 = {{3, 0}, {2, 2}, {1, 4}, {2, 4}}                        |
|                                                              |
|o12 : List                                                    |
+--------------------------------------------------------------+
|i13 : degrees source m                                        |
|                                                              |
|o13 = {{2, 4}, {5, 2}, {3, 4}, {2, 5}, {4, 4}, {4, 4}}        |
|                                                              |
|o13 : List                                                    |
+--------------------------------------------------------------+
|i14 : submatrixByDegrees(C.dd_2, ({2,2},{2,4}), ({2,2},{5,4}))|
|                                                              |
|o14 = {2, 2} | -d2 b3 -bcd 0  0 |                             |
|      {2, 4} | 0   0  a    b2 0 |                             |
|                                                              |
|              2      5                                        |
|o14 : Matrix S  <-- S                                         |
+--------------------------------------------------------------+

Caveat
======

The degrees are taken from the target and source free modules, not from the
matrix entries themselves.

See also
========

  * submatrix

Ways to use submatrixByDegrees:
===============================

  * "submatrixByDegrees(Matrix,List,List)"
  * "submatrixByDegrees(Matrix,Sequence,Sequence)"
  * "submatrixByDegrees(Matrix,ZZ,ZZ)"

For the programmer
==================

The object submatrixByDegrees, is a method function.

submatrix(Matrix,VisibleList) -- select columns
***********************************************

Synopsis
========

  * Function: submatrix,
  * Usage:
        submatrix(f, cols)
  * Inputs:
      * f, a map between free modules
      * cols, a list of integers denoting the choice of columns
  * Outputs:
      * a matrix, the submatrix of f corresponding to the
        columns cols

Description
===========

Yields an r by c matrix, where r is the number of rows of f, and c is the
length of the list of integers cols. The (i,j)-th entry of the result is f_(i,
cols_j).

The list of integers, cols, may contain ranges and repetitions, as in {3, 5..7,
3:0}

If the list of column indices is a permutation of 0 .. n-1, where n is the
number of columns, then the result is the corresponding permutation of the
columns of f.
+----------------------------------+
|i1 : R = ZZ/101[a .. o];          |
+----------------------------------+
|i2 : f = genericMatrix(R, a, 3, 5)|
|                                  |
|o2 = | a d g j m |                |
|     | b e h k n |                |
|     | c f i l o |                |
|                                  |
|             3      5             |
|o2 : Matrix R  <-- R              |
+----------------------------------+
|i3 : submatrix(f, {1..3,0})       |
|                                  |
|o3 = | d g j a |                  |
|     | e h k b |                  |
|     | f i l c |                  |
|                                  |
|             3      4             |
|o3 : Matrix R  <-- R              |
+----------------------------------+

See also
========

  * submatrix' -- exclude rows and/or columns of a matrix
  * Matrix _ List -- select columns
  * Matrix ^ List -- select rows
  * Matrix _ Array -- component of map corresponding
    to summand of source
  * Matrix ^ Array -- component of map corresponding to
    summand of target

Ways to use this method:
========================

  * submatrix(Matrix,VisibleList),
    -- select columns
  * "submatrix(MutableMatrix,VisibleList)"

submatrix(Matrix,VisibleList,VisibleList) -- select part of a matrix
********************************************************************

Synopsis
========

  * Function: submatrix,
  * Usage:
        submatrix(f, rows, cols)
        submatrix(f,,cols)
        submatrix(f,rows,)
  * Inputs:
      * f, a map between free modules
      * rows, a list of integers denoting the choice of rows. If omitted, use
        all rows
      * cols, a list of integers denoting the choice of columns. If omitted,
        use all columns
  * Outputs:
      * a matrix, the submatrix of f corresponding to the lists
        rows and cols

Description
===========

Yields an r by c matrix, where r is the length of the list of integers rows,
and c is the length of the list of integers cols. The (i,j)-th entry of the
result is f_(rows_i, cols_j).

Each list of integers may contain ranges and repetitions, as in {3, 5..7, 3:0}

If rows or cols is omitted, all the corresponding indices are used.

Both rows and/or cols may contain duplicate values, in which case the result
will contain duplicate rows and/or columns.
+-------------------------------------+
|i1 : R = ZZ/101[a .. o];             |
+-------------------------------------+
|i2 : f = genericMatrix(R, a, 3, 5)   |
|                                     |
|o2 = | a d g j m |                   |
|     | b e h k n |                   |
|     | c f i l o |                   |
|                                     |
|             3      5                |
|o2 : Matrix R  <-- R                 |
+-------------------------------------+
|i3 : submatrix(f, {1,2,0}, {0..2, 4})|
|                                     |
|o3 = | b e h n |                     |
|     | c f i o |                     |
|     | a d g m |                     |
|                                     |
|             3      4                |
|o3 : Matrix R  <-- R                 |
+-------------------------------------+

+--------------------------+
|i4 : submatrix(f, {1,2}, )|
|                          |
|o4 = | b e h k n |        |
|     | c f i l o |        |
|                          |
|             2      5     |
|o4 : Matrix R  <-- R      |
+--------------------------+
submatrix(f,,cols) can be written as submatrix(f,cols), or f_cols.
+------------------------+
|i5 : submatrix(f,,{0,1})|
|                        |
|o5 = | a d |            |
|     | b e |            |
|     | c f |            |
|                        |
|             3      2   |
|o5 : Matrix R  <-- R    |
+------------------------+
|i6 : f_{0,1}            |
|                        |
|o6 = | a d |            |
|     | b e |            |
|     | c f |            |
|                        |
|             3      2   |
|o6 : Matrix R  <-- R    |
+------------------------+

See also
========

  * submatrix' -- exclude rows and/or columns of a matrix
  * Matrix _ List -- select columns
  * Matrix ^ List -- select rows
  * submatrix(Matrix,VisibleList),
    -- select columns
  * Matrix _ Array -- component of map corresponding
    to summand of source
  * Matrix ^ Array -- component of map corresponding to
    summand of target
  * null -- the unique member of the empty class

Ways to use this method:
========================

  * submatrix(Matrix,VisibleList,VisibleList)
    -- select part of a
    matrix
  * "submatrix(MutableMatrix,VisibleList,VisibleList)"

Matrix _ List -- select columns
*******************************

Synopsis
========

  * Operator: _,
  * Usage:
        f_cols
  * Inputs:
      * f, a matrix between free modules
      * cols, a list of integers denoting the choice of columns
  * Outputs:
      * the submatrix of f corresponding to the columns cols.

Description
===========

This is the same as calling submatrix(f,cols).
+---------------------------------+
|i1 : R = QQ[a..f];               |
+---------------------------------+
|i2 : p = matrix {{a,b,c},{d,e,f}}|
|                                 |
|o2 = | a b c |                   |
|     | d e f |                   |
|                                 |
|             2      3            |
|o2 : Matrix R  <-- R             |
+---------------------------------+
|i3 : p_{1}                       |
|                                 |
|o3 = | b |                       |
|     | e |                       |
|                                 |
|             2      1            |
|o3 : Matrix R  <-- R             |
+---------------------------------+
|i4 : p_{1,2,0}                   |
|                                 |
|o4 = | b c a |                   |
|     | e f d |                   |
|                                 |
|             2      3            |
|o4 : Matrix R  <-- R             |
+---------------------------------+

See also
========

  * submatrix
  * Matrix ^ List -- select rows

Ways to use this method:
========================

  * Matrix _ List -- select columns

Matrix ^ List -- select rows
****************************

Synopsis
========

  * Operator: ^,
  * Usage:
        f_rows
  * Inputs:
      * f, a matrix between free modules
      * rows, a list of integers denoting the choice of rows
  * Outputs:
      * the submatrix of f corresponding to the rows in the list rows.

Description
===========

This is the same as calling submatrix(f,rows,).
+---------------------------------+
|i1 : R = QQ[a..f];               |
+---------------------------------+
|i2 : p = matrix {{a,b,c},{d,e,f}}|
|                                 |
|o2 = | a b c |                   |
|     | d e f |                   |
|                                 |
|             2      3            |
|o2 : Matrix R  <-- R             |
+---------------------------------+
|i3 : p^{1}                       |
|                                 |
|o3 = | d e f |                   |
|                                 |
|             1      3            |
|o3 : Matrix R  <-- R             |
+---------------------------------+
|i4 : p^{1,0}                     |
|                                 |
|o4 = | d e f |                   |
|     | a b c |                   |
|                                 |
|             2      3            |
|o4 : Matrix R  <-- R             |
+---------------------------------+

See also
========

  * submatrix
  * Matrix _ List -- select columns

Ways to use this method:
========================

  * Matrix ^ List -- select rows

Matrix _ Array -- component of map corresponding to summand of source
*********************************************************************

Synopsis
========

  * Operator: _,
  * Usage:
        F_[i,j,...,k]
  * Inputs:
      * F, or a chain complex map, or a graded module map,
      * [i,j,...,k], an array of indices
  * Outputs:
      * a matrix, a chain complex map,
        or a graded module map,

Description
===========

The source of the module or chain complex F should be a direct sum, and the
result is the component of this map corresponding to the sum of the components
numbered or named i, j, ..., k.  Free modules are regarded as direct sums of
modules. In otherwords, this routine returns the map given by certain blocks of
columns.
+----------------------------------------------------+
|i1 : R = ZZ[a..d];                                  |
+----------------------------------------------------+
|i2 : F = (vars R) ++ ((vars R) ++ matrix{{a-1,b-3}})|
|                                                    |
|o2 = | a b c d 0 0 0 0 0   0   |                    |
|     | 0 0 0 0 a b c d 0   0   |                    |
|     | 0 0 0 0 0 0 0 0 a-1 b-3 |                    |
|                                                    |
|             3      10                              |
|o2 : Matrix R  <-- R                                |
+----------------------------------------------------+
|i3 : F_[1]                                          |
|                                                    |
|o3 = | 0 0 0 0 0   0   |                            |
|     | a b c d 0   0   |                            |
|     | 0 0 0 0 a-1 b-3 |                            |
|                                                    |
|             3      6                               |
|o3 : Matrix R  <-- R                                |
+----------------------------------------------------+
|i4 : F_[1]^[1]                                      |
|                                                    |
|o4 = | a b c d 0   0   |                            |
|     | 0 0 0 0 a-1 b-3 |                            |
|                                                    |
|             2      6                               |
|o4 : Matrix R  <-- R                                |
+----------------------------------------------------+

If the components have been given names (see directSum), use
those instead.

+-----------------------------------------------------------------------------+
|i5 : N = (a=>vars R) ++ (b=>vars R)                                          |
|                                                                             |
|o5 = | a b c d 0 0 0 0 |                                                     |
|     | 0 0 0 0 a b c d |                                                     |
|                                                                             |
|             2      8                                                        |
|o5 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i6 : N_[a]                                                                   |
|                                                                             |
|o6 = | a b c d |                                                             |
|     | 0 0 0 0 |                                                             |
|                                                                             |
|             2      4                                                        |
|o6 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i7 : N = directSum(x1 => matrix{{a,b-1}}, x2 => matrix{{a-3,b-17,c-35}}, x3  |
|                                                                             |
|o7 = | a b-1 0   0    0    0 0 0 0 |                                         |
|     | 0 0   a-3 b-17 c-35 0 0 0 0 |                                         |
|     | 0 0   0   0    0    a b c d |                                         |
|                                                                             |
|             3      9                                                        |
|o7 : Matrix R  <-- R                                                         |
|-----------------------------------------------------------------------------|
|=> vars R)                                                                   |
+-----------------------------------------------------------------------------+
|i8 : N_[x1,x3]                                                               |
|                                                                             |
|o8 = | a b-1 0 0 0 0 |                                                       |
|     | 0 0   0 0 0 0 |                                                       |
|     | 0 0   a b c d |                                                       |
|                                                                             |
|             3      6                                                        |
|o8 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+

This works the same way for maps between chain complexes.

See also
========

  * Matrix ^ Array -- component of map corresponding to
    summand of target
  * Module _ Array -- inclusion from summand
  * directSum -- direct sum of modules or maps

Ways to use this method:
========================

  * "ChainComplexMap _ Array"
  * "GradedModuleMap _ Array"
  * Matrix _ Array -- component of map corresponding
    to summand of source

Matrix ^ Array -- component of map corresponding to summand of target
*********************************************************************

Synopsis
========

  * Operator: ^,
  * Usage:
        F^[i,j,...,k]
  * Inputs:
      * F, or a chain complex map, or a graded module map,
      * [i,j,...,k], an array of indices
  * Outputs:
      * a matrix, a chain complex map,
        or a graded module map,

Description
===========

The target of the module or chain complex F should be a direct sum, and the
result is the component of this map corresponding to the sum of the components
numbered or named i, j, ..., k.  Free modules are regarded as direct sums of
modules. In otherwords, this routine returns the map given by certain blocks of
columns.
+----------------------------------------------------------+
|i1 : R = ZZ[a..d];                                        |
+----------------------------------------------------------+
|i2 : F = (vars R) ++ ((vars R) ++ matrix{{a-1,b-3},{c,d}})|
|                                                          |
|o2 = | a b c d 0 0 0 0 0   0   |                          |
|     | 0 0 0 0 a b c d 0   0   |                          |
|     | 0 0 0 0 0 0 0 0 a-1 b-3 |                          |
|     | 0 0 0 0 0 0 0 0 c   d   |                          |
|                                                          |
|             4      10                                    |
|o2 : Matrix R  <-- R                                      |
+----------------------------------------------------------+
|i3 : F^[1]                                                |
|                                                          |
|o3 = | 0 0 0 0 a b c d 0   0   |                          |
|     | 0 0 0 0 0 0 0 0 a-1 b-3 |                          |
|     | 0 0 0 0 0 0 0 0 c   d   |                          |
|                                                          |
|             3      10                                    |
|o3 : Matrix R  <-- R                                      |
+----------------------------------------------------------+
|i4 : F_[1]^[1]                                            |
|                                                          |
|o4 = | a b c d 0   0   |                                  |
|     | 0 0 0 0 a-1 b-3 |                                  |
|     | 0 0 0 0 c   d   |                                  |
|                                                          |
|             3      6                                     |
|o4 : Matrix R  <-- R                                      |
+----------------------------------------------------------+

If the components have been given names (see directSum), use
those instead.

+-----------------------------------------------------------------------------+
|i5 : G = (a=>R^2) ++ (b=>R^1)                                                |
|                                                                             |
|      3                                                                      |
|o5 = R                                                                       |
|                                                                             |
|o5 : R-module, free                                                          |
+-----------------------------------------------------------------------------+
|i6 : N = map(G,R^2, (i,j) -> (i+37*j)_R)                                     |
|                                                                             |
|o6 = | 0 37 |                                                                |
|     | 1 38 |                                                                |
|     | 2 39 |                                                                |
|                                                                             |
|             3      2                                                        |
|o6 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i7 : N^[a]                                                                   |
|                                                                             |
|o7 = | 0 37 |                                                                |
|     | 1 38 |                                                                |
|                                                                             |
|             2      2                                                        |
|o7 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i8 : N^[b]                                                                   |
|                                                                             |
|o8 = | 2 39 |                                                                |
|                                                                             |
|             1      2                                                        |
|o8 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i9 : N = directSum(x1 => matrix{{a,b-1}}, x2 => matrix{{a-3,b-17,c-35}}, x3  |
|                                                                             |
|o9 = | a b-1 0   0    0    0 0 0 0 |                                         |
|     | 0 0   a-3 b-17 c-35 0 0 0 0 |                                         |
|     | 0 0   0   0    0    a b c d |                                         |
|                                                                             |
|             3      9                                                        |
|o9 : Matrix R  <-- R                                                         |
|-----------------------------------------------------------------------------|
|=> vars R)                                                                   |
+-----------------------------------------------------------------------------+
|i10 : N^[x1,x3]                                                              |
|                                                                             |
|o10 = | a b-1 0 0 0 0 0 0 0 |                                                |
|      | 0 0   0 0 0 a b c d |                                                |
|                                                                             |
|              2      9                                                       |
|o10 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+

This works the same way for maps between chain complexes.

See also
========

  * Matrix ^ Array -- component of map corresponding to
    summand of target
  * Module _ Array -- inclusion from summand
  * directSum -- direct sum of modules or maps

Ways to use this method:
========================

  * "ChainComplexMap ^ Array"
  * "GradedModuleMap ^ Array"
  * Matrix ^ Array -- component of map corresponding to
    summand of target

subquotient -- make a subquotient module
****************************************

Synopsis
========

  * Usage:
        subquotient(g,r)
        subquotient(M,g,r)
  * Inputs:
      * g, the matrix of generators
      * r, the matrix of relations, with the same target as g
      * M, a module, if given, must be the common target of g
        and r
  * Outputs:
      * the image of g in the cokernel of r

Description
===========

If g is omitted, then the identity map on the target of r is used as g, and the
cokernel of r is returned. If r is omitted (but not the comma), then a zero map
to the target of g is used as r, and the image of g is returned. If both are
omitted, then M is returned.

See subquotient modules, for an overview of
subquotient modules in Macaulay2.

The general form in which modules are represented in Macaulay2 is as
subquotients, and subquotient modules are often returned as values of
computations, as in the example below.

+---------------------------------------------------------------+
|i1 : R = ZZ/101[a..d]                                          |
|                                                               |
|o1 = R                                                         |
|                                                               |
|o1 : PolynomialRing                                            |
+---------------------------------------------------------------+
|i2 : M = kernel vars R ++ cokernel vars R                      |
|                                                               |
|o2 = subquotient ({1} | -b 0  -c 0  0  -d 0 |, {1} | 0 0 0 0 |)|
|                  {1} | a  -c 0  0  -d 0  0 |  {1} | 0 0 0 0 | |
|                  {1} | 0  b  a  -d 0  0  0 |  {1} | 0 0 0 0 | |
|                  {1} | 0  0  0  c  b  a  0 |  {1} | 0 0 0 0 | |
|                  {0} | 0  0  0  0  0  0  1 |  {0} | a b c d | |
|                                                               |
|                               5                               |
|o2 : R-module, subquotient of R                                |
+---------------------------------------------------------------+
|i3 : generators M                                              |
|                                                               |
|o3 = {1} | -b 0  -c 0  0  -d 0 |                               |
|     {1} | a  -c 0  0  -d 0  0 |                               |
|     {1} | 0  b  a  -d 0  0  0 |                               |
|     {1} | 0  0  0  c  b  a  0 |                               |
|     {0} | 0  0  0  0  0  0  1 |                               |
|                                                               |
|             5      7                                          |
|o3 : Matrix R  <-- R                                           |
+---------------------------------------------------------------+
|i4 : relations M                                               |
|                                                               |
|o4 = {1} | 0 0 0 0 |                                           |
|     {1} | 0 0 0 0 |                                           |
|     {1} | 0 0 0 0 |                                           |
|     {1} | 0 0 0 0 |                                           |
|     {0} | a b c d |                                           |
|                                                               |
|             5      4                                          |
|o4 : Matrix R  <-- R                                           |
+---------------------------------------------------------------+
|i5 : M === subquotient(generators M, relations M)              |
|                                                               |
|o5 = true                                                      |
+---------------------------------------------------------------+
|i6 : prune M,                                                  |
|                                                               |
|o6 = (cokernel {2} | 0 0 0 0 c  0  0  d  |, )                  |
|               {2} | 0 0 0 0 a  d  0  0  |                     |
|               {2} | 0 0 0 0 -b 0  d  0  |                     |
|               {2} | 0 0 0 0 0  b  a  0  |                     |
|               {2} | 0 0 0 0 0  -c 0  a  |                     |
|               {2} | 0 0 0 0 0  0  -c -b |                     |
|               {0} | d c b a 0  0  0  0  |                     |
|                                                               |
|o6 : Sequence                                                  |
+---------------------------------------------------------------+

See also
========

  * subquotient modules -- the way Macaulay2
    represents modules
  * isSubquotient -- check whether a
    module is a subquotient of another
  * ambient -- ambient free module of a subquotient, or ambient
    ring
  * generators -- provide matrix or list of generators
  * relations -- the defining relations
  * prune -- prune, e.g., compute a minimal presentation

Ways to use subquotient:
========================

  * "subquotient(Matrix,Matrix)"
  * "subquotient(Matrix,Nothing)"
  * "subquotient(Module,Matrix,Matrix)"
  * "subquotient(Module,Matrix,Nothing)"
  * "subquotient(Module,Nothing,Matrix)"
  * "subquotient(Module,Nothing,Nothing)"
  * "subquotient(Nothing,Matrix)"

For the programmer
==================

The object subquotient, is a method function.

SubringLimit -- stop after finding enough elements of a subring
***************************************************************

Description
===========

SubringLimit -- an option for  kernel, and gb, which
can stop the computation after a certain number of basis elements in a subring
have been found.

See also
========

  * Gröbner bases

Functions with optional argument named SubringLimit:
====================================================

  * "gb(...,SubringLimit=>...)" -- see gb, -- compute a Gröbner basis
  * kernel(...,SubringLimit=>...)

For the programmer
==================

The object SubringLimit, is a symbol.

Subscript -- the class of all subscript expressions
***************************************************

Description
===========

Subscript is a type of Expression, representing a subscripted
expression.

Methods that use a subscript expression:
========================================

  * "baseName(Subscript)" -- see baseName, -- the base name of
    a generator

For the programmer
==================

The object Subscript, is a header type,
with ancestor classes Expression, < BasicList
< Thing.

subscript -- specify the function in a scripted functor for a subscript
***********************************************************************

Description
===========

subscript -- a key used in scripted functors under which is stored the function
of one variable that accepts the subscript and returns a scripted functor that
accepts the arguments.

See also
========

  * ScriptedFunctor -- the class of all scripted
    functors

For the programmer
==================

The object subscript, is a symbol.

subsets -- produce the subsets of a set or list
***********************************************

Synopsis
========

  * Usage:
        subsets(A)
        subsets(A, n)
  * Inputs:
      * A, a list, , sequence, set or integer
      * n, an integer, optional input to specify subsets of a
        particular size
  * Outputs:
      * L, a list, of subsets (of size n if given)

Description
===========

If A is an integer, subsets(A) lists the subsets of \{0, 1, ..., A-1\}.

+-----------------------------------------------------------------------------+
|i1 : subsets(3)                                                              |
|                                                                             |
|o1 = {{}, {0}, {1}, {0, 1}, {2}, {0, 2}, {1, 2}, {0, 1, 2}}                  |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+
|i2 : subsets(5, 3)                                                           |
|                                                                             |
|o2 = {{0, 1, 2}, {0, 1, 3}, {0, 2, 3}, {1, 2, 3}, {0, 1, 4}, {0, 2, 4}, {1,  |
|     ------------------------------------------------------------------------|
|     2, 4}, {0, 3, 4}, {1, 3, 4}, {2, 3, 4}}                                 |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

A can be a list, sequence, or set. The elements need not be of the same type.

+-----------------------------------------------------------------------------+
|i3 : subsets({"apple", "banana", {1,2,3}, 7.1}, 3)                           |
|                                                                             |
|o3 = {{apple, banana, {1, 2, 3}}, {apple, banana, 7.1}, {apple, {1, 2, 3},   |
|     ------------------------------------------------------------------------|
|     7.1}, {banana, {1, 2, 3}, 7.1}}                                         |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

If a list contains repetitions, so will the subsets of that list. Since a
Set, has no repetitions, neither do its subsets. Also, the subsets of a
set will again be sets (while the subsets of a list are lists).

+-----------------------------------------------------------------------------+
|i4 : subsets({"apple", "apple", "banana"})                                   |
|                                                                             |
|o4 = {{}, {apple}, {apple}, {apple, apple}, {banana}, {apple, banana},       |
|     ------------------------------------------------------------------------|
|     {apple, banana}, {apple, apple, banana}}                                |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : subsets(set{"apple", "apple", "banana"})                                |
|                                                                             |
|o5 = {set {}, set {banana}, set {apple}, set {banana, apple}}                |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

The subsets of a Sequence are lists, not sequences. Also, a subset size must be
specified when calling subsets on a sequence.

See also
========

  * partition -- partition a set or list by values of a
    function
  * set -- make a set
  * sublists -- process interspersed subsequences of a visible
    list
  * substring -- extract part of a string
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use subsets:
====================

  * "subsets(List)"
  * "subsets(List,ZZ)"
  * "subsets(Sequence,ZZ)"
  * "subsets(Set)"
  * "subsets(Set,ZZ)"
  * "subsets(ZZ)"
  * "subsets(ZZ,ZZ)"

For the programmer
==================

The object subsets, is a method function.

substituting values for variables
*********************************

Once a ring is defined that has variables, values can be given to these
variables using substitute.  We give an example.
+------------------------------------+
|i1 : R = ZZ/101[x,y,z];             |
+------------------------------------+
|i2 : f = x^3+3*y^2*z+2*z^3;         |
+------------------------------------+
|i3 : substitute(f,matrix{{-1,2,5}}) |
|                                    |
|o3 = 309                            |
+------------------------------------+
|i4 : substitute(f,{x=>-1,y=>2,z=>5})|
|                                    |
|o4 = 6                              |
|                                    |
|      ZZ                            |
|o4 : ---                            |
|     101                            |
+------------------------------------+
The same command works for putting values into ideals or matrices.  Also, it is
not required that the values be elements from the coefficient ring, nor do you
have to give a value for every variable.
+----------------------------------------------+
|i5 : M = matrix{{x^2,x-y},{x-z,z^2},{y-z,y^2}}|
|                                              |
|o5 = | x2  x-y |                              |
|     | x-z z2  |                              |
|     | y-z y2  |                              |
|                                              |
|             3      2                         |
|o5 : Matrix R  <-- R                          |
+----------------------------------------------+
|i6 : substitute(M,matrix{{-1,2,x+y}})         |
|                                              |
|o6 = | 1      -3        |                     |
|     | -x-y-1 x2+2xy+y2 |                     |
|     | -x-y+2 4         |                     |
|                                              |
|             3      2                         |
|o6 : Matrix R  <-- R                          |
+----------------------------------------------+
|i7 : I = ideal M                              |
|                                              |
|             2                        2   2   |
|o7 = ideal (x , x - z, y - z, x - y, z , y )  |
|                                              |
|o7 : Ideal of R                               |
+----------------------------------------------+
|i8 : substitute(I,{x=>-1,y=>2})               |
|                                              |
|                                      2       |
|o8 = ideal (1, - z - 1, - z + 2, -3, z , 4)   |
|                                              |
|o8 : Ideal of R                               |
+----------------------------------------------+

subtable -- extract a subtable from a table
*******************************************

Synopsis
========

  * Usage:
        subtable(a, b, T)
  * Inputs:
      * a, a list, of rows to extract
      * b, a list, of columns to extract
  * Outputs:
      * S, the subtable of $T$ defined by restricting to rows in the list $a$
        and columns in the list $b$

Description
===========

+---------------------------------------------------+
|i1 : t = table({1,3,5,7}, {0,1,2,4}, (i,j) -> i^j);|
+---------------------------------------------------+
|i2 : netList t                                     |
|                                                   |
|     +-+-+--+----+                                 |
|o2 = |1|1|1 |1   |                                 |
|     +-+-+--+----+                                 |
|     |1|3|9 |81  |                                 |
|     +-+-+--+----+                                 |
|     |1|5|25|625 |                                 |
|     +-+-+--+----+                                 |
|     |1|7|49|2401|                                 |
|     +-+-+--+----+                                 |
+---------------------------------------------------+
|i3 : s1 = subtable({0,2}, {1,3}, t);               |
+---------------------------------------------------+
|i4 : netList s1                                    |
|                                                   |
|     +-+---+                                       |
|o4 = |1|1  |                                       |
|     +-+---+                                       |
|     |5|625|                                       |
|     +-+---+                                       |
+---------------------------------------------------+
|i5 : s2 = subtable(toList(0..3), {1}, t);          |
+---------------------------------------------------+
|i6 : netList s2                                    |
|                                                   |
|     +-+                                           |
|o6 = |1|                                           |
|     +-+                                           |
|     |3|                                           |
|     +-+                                           |
|     |5|                                           |
|     +-+                                           |
|     |7|                                           |
|     +-+                                           |
+---------------------------------------------------+

See also
========

  * applyTable -- apply a function to each element of a
    table
  * isTable -- whether something is a list of lists of equal
    length
  * positions -- which elements of a list satisfy a condition
  * table -- make a table from a binary function
  * select -- select from a list, hash table, or string
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

For the programmer
==================

The object subtable, is a function closure.

Sum -- the class of all sum expressions
***************************************

Description
===========

Sum is a type of Expression, representing a sum.

Methods that use a sum expression:
==================================

  * RingMap Sum (missing documentation)

For the programmer
==================

The object Sum, is a wrapper type, with ancestor
classes AssociativeExpression, < Expression
< BasicList < Thing.

sum -- compute the sum
**********************

Description
===========

sum provides the sum of the members of a list, set, or chain complex,
optionally with a function applied to each one.

Ways to use sum:
================

  * sum(ChainComplex) -- direct sum of the
    components of a chain complex
  * sum(ChainComplexMap) -- direct sum of the
    components of a chain map
  * sum(List) -- sum the elements of a list
  * sum(Set) -- sum of elements
  * sum(VirtualTally) -- sum of elements
  * sum(VisibleList,Function) -- sum
    results of applying a function
  * sum(VisibleList,VisibleList,Function)
    -- sum results of applying a
    function pairwise
  * sum(ZZ,Function) -- sum consecutive values
    of a function

For the programmer
==================

The object sum, is a method function.

sum(ChainComplex) -- direct sum of the components of a chain complex
********************************************************************

Synopsis
========

  * Function: sum,

Description
===========

sum C -- yields the sum of the modules in a chain complex.

The degrees of the components are preserved.
+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a..d];                                                       |
+-----------------------------------------------------------------------------+
|i2 : C = res coker vars R                                                    |
|                                                                             |
|      1      4      6      4      1                                          |
|o2 = R  <-- R  <-- R  <-- R  <-- R  <-- 0                                    |
|                                                                             |
|     0      1      2      3      4      5                                    |
|                                                                             |
|o2 : ChainComplex                                                            |
+-----------------------------------------------------------------------------+
|i3 : sum C                                                                   |
|                                                                             |
|      16                                                                     |
|o3 = R                                                                       |
|                                                                             |
|o3 : R-module, free, degrees {0..1, 3:1, 6:2, 4:3, 4}                        |
+-----------------------------------------------------------------------------+
|i4 : degrees oo                                                              |
|                                                                             |
|o4 = {{0}, {1}, {1}, {1}, {1}, {2}, {2}, {2}, {2}, {2}, {2}, {3}, {3}, {3},  |
|     ------------------------------------------------------------------------|
|     {3}, {4}}                                                               |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * sum -- compute the sum
  * sum(ChainComplexMap) -- direct sum of the
    components of a chain map

Ways to use this method:
========================

  * sum(ChainComplex) -- direct sum of the
    components of a chain complex

sum(ChainComplexMap) -- direct sum of the components of a chain map
*******************************************************************

Synopsis
========

  * Function: sum,

Description
===========

sum C -- yields the sum of the modules in a chain complex map.

The degrees of the components are preserved.
+----------------------------------+
|i1 : R = ZZ/101[a..c];            |
+----------------------------------+
|i2 : C = res coker vars R         |
|                                  |
|      1      3      3      1      |
|o2 = R  <-- R  <-- R  <-- R  <-- 0|
|                                  |
|     0      1      2      3      4|
|                                  |
|o2 : ChainComplex                 |
+----------------------------------+
|i3 : sum C.dd                     |
|                                  |
|o3 = {0} | 0 a b c 0  0  0  0  |  |
|     {1} | 0 0 0 0 -b -c 0  0  |  |
|     {1} | 0 0 0 0 a  0  -c 0  |  |
|     {1} | 0 0 0 0 0  a  b  0  |  |
|     {2} | 0 0 0 0 0  0  0  c  |  |
|     {2} | 0 0 0 0 0  0  0  -b |  |
|     {2} | 0 0 0 0 0  0  0  a  |  |
|     {3} | 0 0 0 0 0  0  0  0  |  |
|                                  |
|             8      8             |
|o3 : Matrix R  <-- R              |
+----------------------------------+
|i4 : betti oo                     |
|                                  |
|            0 1                   |
|o4 = total: 8 8                   |
|        -1: . 1                   |
|         0: 1 3                   |
|         1: 3 3                   |
|         2: 3 1                   |
|         3: 1 .                   |
|                                  |
|o4 : BettiTally                   |
+----------------------------------+

See also
========

  * sum -- compute the sum
  * sum(ChainComplex) -- direct sum of the
    components of a chain complex

Ways to use this method:
========================

  * sum(ChainComplexMap) -- direct sum of the
    components of a chain map

sum(List) -- sum the elements of a list
***************************************

Synopsis
========

  * Function: sum,

Description
===========

sum v yields the sum of the elements in the list v.

+--------------------+
|i1 : sum {1,2,3,4,5}|
|                    |
|o1 = 15             |
+--------------------+

The sum of an empty list is the integer 0.

+-------------+
|i2 : sum {}  |
|             |
|o2 = 0       |
+-------------+
|i3 : class oo|
|             |
|o3 = ZZ      |
|             |
|o3 : Ring    |
+-------------+

When summing a possibly empty list of elements from a ring, one may use
promote, to ensure the result is always in the same ring.

+---------------------------------------------------------+
|i4 : R = QQ[x_1 .. x_10];                                |
+---------------------------------------------------------+
|i5 : f = n -> sum for i from 1 to n list x_i;            |
+---------------------------------------------------------+
|i6 : f 4                                                 |
|                                                         |
|o6 = x  + x  + x  + x                                    |
|      1    2    3    4                                   |
|                                                         |
|o6 : R                                                   |
+---------------------------------------------------------+
|i7 : f 0                                                 |
|                                                         |
|o7 = 0                                                   |
+---------------------------------------------------------+
|i8 : class oo                                            |
|                                                         |
|o8 = ZZ                                                  |
|                                                         |
|o8 : Ring                                                |
+---------------------------------------------------------+
|i9 : g = n -> promote(sum for i from 1 to n list x_i, R);|
+---------------------------------------------------------+
|i10 : g 10                                               |
|                                                         |
|o10 = x  + x  + x  + x  + x  + x  + x  + x  + x  + x     |
|       1    2    3    4    5    6    7    8    9    10   |
|                                                         |
|o10 : R                                                  |
+---------------------------------------------------------+
|i11 : g 0                                                |
|                                                         |
|o11 = 0                                                  |
|                                                         |
|o11 : R                                                  |
+---------------------------------------------------------+
|i12 : class oo                                           |
|                                                         |
|o12 = R                                                  |
|                                                         |
|o12 : PolynomialRing                                     |
+---------------------------------------------------------+

See also
========

  * sum -- compute the sum

Ways to use this method:
========================

  * sum(List) -- sum the elements of a list

sum(Set) -- sum of elements
***************************

Synopsis
========

  * Function: sum,

Description
===========

sum v yields the sum of the elements in the set v.

+-------------------------+
|i1 : a = set{1,100,10000}|
|                         |
|o1 = set {10000, 100, 1} |
|                         |
|o1 : Set                 |
+-------------------------+
|i2 : sum a               |
|                         |
|o2 = 10101               |
+-------------------------+

See also
========

  * sum -- compute the sum

Ways to use this method:
========================

  * sum(Set) -- sum of elements

sum(VirtualTally) -- sum of elements
************************************

Synopsis
========

  * Function: sum,

Description
===========

sum v yields the sum of the elements in the tally v.

+------------------------------------------+
|i1 : a = tally{1,1,1,1,1,10,10,10,100,100}|
|                                          |
|o1 = Tally{1 => 5  }                      |
|           10 => 3                        |
|           100 => 2                       |
|                                          |
|o1 : Tally                                |
+------------------------------------------+
|i2 : sum a                                |
|                                          |
|o2 = 235                                  |
+------------------------------------------+

See also
========

  * product

Ways to use this method:
========================

  * sum(VirtualTally) -- sum of elements

sum(VisibleList,Function) -- sum results of applying a function
***************************************************************

Synopsis
========

  * Function: sum,

Description
===========

sum(v,f) yields the sum of the expressions obtained by applying f to each of
the elements of the list or sequence v.

+---------------------------+
|i1 : sum(1 .. 10, i -> i^2)|
|                           |
|o1 = 385                   |
+---------------------------+

See also
========

  * sum -- compute the sum

Ways to use this method:
========================

  * sum(VisibleList,Function) -- sum
    results of applying a function

sum(VisibleList,VisibleList,Function) -- sum results of applying a function pairwise
************************************************************************************

Synopsis
========

  * Function: sum,

Description
===========

sum(v,w,f) yields the sum of the results obtained by applying f to each of the
pairs (i,j) of elements from the lists or sequences v and w, which should be of
the same length.

+------------------------------------+
|i1 : R = ZZ[x,y,z];                 |
+------------------------------------+
|i2 : sum({2,3,4},{x,y,z},(i,j)->j^i)|
|                                    |
|      4    3    2                   |
|o2 = z  + y  + x                    |
|                                    |
|o2 : R                              |
+------------------------------------+

See also
========

  * sum -- compute the sum

Ways to use this method:
========================

  * sum(VisibleList,VisibleList,Function)
    -- sum results of applying a
    function pairwise

sum(ZZ,Function) -- sum consecutive values of a function
********************************************************

Synopsis
========

  * Function: sum,

Description
===========

sum(n,f) computes the sum f(0) + f(1) + ... + f(n-1).

+----------------------+
|i1 : sum(10, i -> i^2)|
|                      |
|o1 = 285              |
+----------------------+

See also
========

  * product
  * plus -- addition
  * times -- multiplication

Ways to use this method:
========================

  * sum(ZZ,Function) -- sum consecutive values
    of a function

super -- get the ambient module
*******************************

Description
===========

super M -- yields the module that the module M is a submodule of.
super f -- if f is a map whose target is a submodule of M, yields the composite
of f with the inclusion into M.

See also
========

  * cover -- get the covering free module
  * ambient -- ambient free module of a subquotient, or ambient
    ring

Ways to use super:
==================

  * "super(GradedModule)"
  * "super(Matrix)"
  * "super(Module)"
  * "super(Vector)"
  * super(CoherentSheaf) (missing documentation)
  * super(SheafMap) (missing documentation)

For the programmer
==================

The object super, is a method function.

Superscript -- the class of all superscript expressions
*******************************************************

Description
===========

Superscript is a type of Expression, representing a
superscripted expression.

For the programmer
==================

The object Superscript, is a header type,
with ancestor classes Expression, < BasicList
< Thing.

superscript -- specify the function in a scripted functor for a superscript
***************************************************************************

Description
===========

superscript -- a key used in scripted functors under which is stored the
function of one variable that accepts the superscript and returns a scripted
functor that accepts the arguments.

See also
========

  * ScriptedFunctor -- the class of all scripted
    functors

For the programmer
==================

The object superscript, is a symbol.

support -- list of variables occurring in a polynomial or matrix
****************************************************************

Synopsis
========

  * Usage:
        support f
  * Inputs:
      * f, a ring element, or a matrix,over a
        polynomial ring
  * Outputs:
      * a list, of ring elements, the
        variables occurring in f

Description
===========

+---------------------------------+
|i1 : R = QQ[a..g]                |
|                                 |
|o1 = R                           |
|                                 |
|o1 : PolynomialRing              |
+---------------------------------+
|i2 : f = a^3+b^2*c+3*f^10*d-1+e-e|
|                                 |
|         10    3    2            |
|o2 = 3d*f   + a  + b c - 1       |
|                                 |
|o2 : R                           |
+---------------------------------+
|i3 : support f                   |
|                                 |
|o3 = {a, b, c, d, f}             |
|                                 |
|o3 : List                        |
+---------------------------------+
+--------------------------------+
|i4 : M = matrix"a+b2,c+g2;c,a-1"|
|                                |
|o4 = | b2+a g2+c |              |
|     | c    a-1  |              |
|                                |
|             2      2           |
|o4 : Matrix R  <-- R            |
+--------------------------------+
|i5 : support M                  |
|                                |
|o5 = {a, b, c, g}               |
|                                |
|o5 : List                       |
+--------------------------------+
If the ring is a polynomial ring over another polynomial ring, then the support
contains all of the variables, even the ones in the coefficient ring. The  ring
of each of these is the ring of f.
+-----------------------------------------------------------+
|i6 : A = ZZ[a,b]; B = A[r,s,t]; C = B[x,y,z,w];            |
+-----------------------------------------------------------+
|i9 : f = (a+r+z+1)^2+y                                     |
|                                                           |
|      2                         2                2         |
|o9 = z  + y + (2r + 2a + 2)z + r  + (2a + 2)r + a  + 2a + 1|
|                                                           |
|o9 : C                                                     |
+-----------------------------------------------------------+
|i10 : S = support f                                        |
|                                                           |
|o10 = {y, z, r, a}                                         |
|                                                           |
|o10 : List                                                 |
+-----------------------------------------------------------+
|i11 : ring S_2 === ring f                                  |
|                                                           |
|o11 = true                                                 |
+-----------------------------------------------------------+
Here is one way to select only the top level variables.
+-----------------------------------------+
|i12 : select(S, x -> index x < numgens C)|
|                                         |
|o12 = {y, z}                             |
|                                         |
|o12 : List                               |
+-----------------------------------------+
To obtain a list of the integer indices of the variables one can use either
indices(RingElement), or apply index,
to each variable.
+-----------------------------+
|i13 : indices f              |
|                             |
|o13 = {1, 2, 4, 7}           |
|                             |
|o13 : List                   |
+-----------------------------+
|i14 : apply(support f, index)|
|                             |
|o14 = {1, 2, 4, 7}           |
|                             |
|o14 : List                   |
+-----------------------------+

See also
========

  * index -- numeric index of a ring variable
  * indices(RingElement) -- indices of
    variables occurring in a polynomial
  * indices(Matrix) -- indices of variables
    occurring in a polynomial
  * Ring _ ZZ -- get a ring variable by index

Ways to use support:
====================

  * "support(Matrix)"
  * "support(RingElement)"
  * support(Ideal) -- list of variables occurring in
    the generators of an ideal

For the programmer
==================

The object support, is a method function.

support(Ideal) -- list of variables occurring in the generators of an ideal
***************************************************************************

Synopsis
========

  * Function: support,
  * Usage:
        support I
  * Inputs:
      * I, an ideal in a polynomial ring
  * Outputs:
      * a list, of ring elements, the
        variables occurring in the generators of the ideal

Description
===========

+------------------------+
|i1 : R = QQ[a..g]       |
|                        |
|o1 = R                  |
|                        |
|o1 : PolynomialRing     |
+------------------------+
|i2 : I = ideal(b,c,e+f) |
|                        |
|o2 = ideal (b, c, e + f)|
|                        |
|o2 : Ideal of R         |
+------------------------+
|i3 : support I          |
|                        |
|o3 = {b, c, e, f}       |
|                        |
|o3 : List               |
+------------------------+

Ways to use this method:
========================

  * support(Ideal) -- list of variables occurring in
    the generators of an ideal

SVD -- singular value decomposition of a matrix
***********************************************

Synopsis
========

  * Usage:
        (S,U,Vt) = SVD M
  * Inputs:
      * M, a matrix,  over RR, or CC, of
        size m by n
  * Optional inputs,:
      * DivideConquer, =>
        ..., default value true, Use the lapack divide and conquer SVD
        algorithm
  * Outputs:
      * S, a vertical list, the list of singular values
      * U, a matrix, an orthogonal (unitary) matrix of size m by
        m
      * Vt, a matrix, an orthogonal (unitary) matrix of size n
        by n

Description
===========

If Sigma is the diagonal m by n matrix whose (i,i) entry is the i-th element of
S, then M = U Sigma Vt.  This is the singular value decomposition of M.  The
entries of S are (up to roundoff error) the eigenvalues of the Hermitian matrix
M * (conjugate transpose M)

M may also be a MutableMatrix, in which case the returned
values U and Vt are also mutable matrices.

If M is over CC, then U and Vt are unitary matrices over CC.
If M is over RR, U and Vt are orthogonal over RR.
+-------------------------------------------------------------------+
|i1 : printingPrecision=2;                                          |
+-------------------------------------------------------------------+
|i2 : M = map(RR^3, RR^5, (i,j) -> (i+1)^j * 1.0)                   |
|                                                                   |
|o2 = | 1 1 1 1  1  |                                               |
|     | 1 2 4 8  16 |                                               |
|     | 1 3 9 27 81 |                                               |
|                                                                   |
|                3         5                                        |
|o2 : Matrix RR    <-- RR                                           |
|              53        53                                         |
+-------------------------------------------------------------------+
|i3 : (S,U,V) = SVD(M)                                              |
|                                                                   |
|o3 = ({88 }, | -.016 -.4  -.92  |, | -.014 -.038 -.11 -.32 -.94  |)|
|      {3.9}  | -.21  -.89 .4    |  | -.28  -.41  -.57 -.59 .29   | |
|      {.8 }  | -.98  .2   -.068 |  | -.74  -.41  .066 .51  -.15  | |
|                                   | .084  .33   -.81 .47  -.081 | |
|                                   | -.61  .74   .077 -.27 .062  | |
|                                                                   |
|o3 : Sequence                                                      |
+-------------------------------------------------------------------+
|i4 : M' = (transpose U) * M * (transpose V)                        |
|                                                                   |
|o4 = | 88      -3.1e-15 1.3e-14  -3.9e-15 -8.9e-16 |               |
|     | 4.9e-15 3.9      -6.8e-15 -5.8e-16 -2.2e-15 |               |
|     | 7.7e-15 1.2e-14  .8       2.6e-16  6.1e-16  |               |
|                                                                   |
|                3         5                                        |
|o4 : Matrix RR    <-- RR                                           |
|              53        53                                         |
+-------------------------------------------------------------------+
We can clean the small entries from the result above with clean.
+---------------------------------------+
|i5 : e = 1e-10;                        |
+---------------------------------------+
|i6 : clean_e M'                        |
|                                       |
|o6 = | 88 0   0  0 0 |                 |
|     | 0  3.9 0  0 0 |                 |
|     | 0  0   .8 0 0 |                 |
|                                       |
|                3         5            |
|o6 : Matrix RR    <-- RR               |
|              53        53             |
+---------------------------------------+
|i7 : clean_e norm (1 - U * transpose U)|
|                                       |
|o7 = 0                                 |
|                                       |
|o7 : RR (of precision 53)              |
+---------------------------------------+
Alternatively, if the only issue is display of the matrix, we may set the
printing accuracy.
+---------------------------+
|i8 : printingAccuracy = 2  |
|                           |
|o8 = 2                     |
+---------------------------+
|i9 : M'                    |
|                           |
|o9 = | 88 -0  0  -0 -0 |   |
|     | 0  3.9 -0 -0 -0 |   |
|     | 0  0   .8 0  0  |   |
|                           |
|                3         5|
|o9 : Matrix RR    <-- RR   |
|              53        53 |
+---------------------------+
Now let's try the divide and conquer algorithm and compare answers.
+---------------------------------------------------------------+
|i10 : (S', U', V') = SVD(M, DivideConquer => true)             |
|                                                               |
|o10 = ({88 }, | -.02 -.4  -.92 |, | -.01 -.04 -.11 -.32 -.94 |)|
|       {3.9}  | -.21 -.89 .4   |  | -.28 -.41 -.57 -.59 .29  | |
|       {.8 }  | -.98 .2   -.07 |  | -.74 -.41 .07  .51  -.15 | |
|                                  | .08  .33  -.81 .47  -.08 | |
|                                  | -.61 .74  .08  -.27 .06  | |
|                                                               |
|o10 : Sequence                                                 |
+---------------------------------------------------------------+
|i11 : norm \ ({S', U', V'}-{S, U, V})                          |
|                                                               |
|o11 = {0, 0, 0}                                                |
|                                                               |
|o11 : List                                                     |
+---------------------------------------------------------------+
The SVD routine calls on the SVD algorithms in the lapack and eigen libraries.

See also
========

  * eigenvalues -- find eigenvalues of a matrix
  * eigenvectors -- find eigenvectors of a matrix over RR
    or CC
  * norm
  * clean -- Set to zero elements that are approximately zero
  * printingAccuracy -- current accuracy for printing
    numbers
  * printingPrecision -- current precision for
    printing numbers

Ways to use SVD:
================

  * "SVD(Matrix)"
  * "SVD(MutableMatrix)"

For the programmer
==================

The object SVD, is a method function with options.

SVD(...,DivideConquer=>...) -- Use the lapack divide and conquer SVD algorithm
******************************************************************************

Synopsis
========

  * Usage:
        SVD(M, DivideConquer=>true)

Description
===========

For large matrices, this algorithm is often much faster.
+-------------------------------------------------------+
|i1 : M = random(RR^200, RR^200);                       |
|                                                       |
|                200         200                        |
|o1 : Matrix RR      <-- RR                             |
|              53          53                           |
+-------------------------------------------------------+
|i2 : time SVD(M);                                      |
| -- used 0.0552616s (cpu); 0.0116789s (thread); 0s (gc)|
+-------------------------------------------------------+
|i3 : time SVD(M, DivideConquer=>true);                 |
| -- used 0.0544741s (cpu); 0.0110288s (thread); 0s (gc)|
+-------------------------------------------------------+

Further information
===================

  * Default value: true,
  * Function: SVD, -- singular value decomposition of a matrix
  * Option key: DivideConquer, -- an optional argument

Functions with optional argument named DivideConquer:
=====================================================

  * SVD(...,DivideConquer=>...)
    -- Use the lapack divide and
    conquer SVD algorithm

switch -- copy a list, switching two elements
*********************************************

Synopsis
========

  * Usage:
        switch(i, j, L)
  * Inputs:
      * i, an integer,
      * j, an integer,
      * L, a basic list,
  * Outputs:
      * L2, a basic list, a copy of the list L, with the
        elements in positions i and j interchanged.

Description
===========

A negative value of i or j is taken relative to the end of the list.

+---------------------------------------+
|i1 : L = 0..10;                        |
+---------------------------------------+
|i2 : switch(3, 9, L)                   |
|                                       |
|o2 = (0, 1, 2, 9, 4, 5, 6, 7, 8, 3, 10)|
|                                       |
|o2 : Sequence                          |
+---------------------------------------+
|i3 : switch(0, -1, L)                  |
|                                       |
|o3 = (10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0)|
|                                       |
|o3 : Sequence                          |
+---------------------------------------+
|i4 : switch(-1, -2, L)                 |
|                                       |
|o4 = (0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 9)|
|                                       |
|o4 : Sequence                          |
+---------------------------------------+

See also
========

  * insert -- copy a list, inserting an element
  * reverse -- reverse a list, sequence, or string
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use switch:
===================

  * "switch(ZZ,ZZ,BasicList)"

For the programmer
==================

The object switch, is a method function.

Symbol -- the class of all symbols
**********************************

Description
===========

Symbols are entered as an alphabetic character followed by a sequence of
alphanumeric characters; case is significant. The single symbol character ' is
regarded as alphabetic, so that symbols such as x' may be used.

Symbols are used as names for values to be preserved, as indeterminates in
polynomial rings, and as keys in hash tables.  They may have global scope,
meaning they are visible from every line of code, or local scope, with
visibility restricted to a single file or function body.
+-----------+
|i1 : x     |
|           |
|o1 = x     |
|           |
|o1 : Symbol|
+-----------+
|i2 : ab12  |
|           |
|o2 = ab12  |
|           |
|o2 : Symbol|
+-----------+

See also
========

  * _colon_= -- assignment of method or new local variable

Types of symbol:
================

  * Keyword -- the class of all keywords

Functions and methods returning a symbol:
=========================================

  * Dictionary # String (missing documentation)
  * global -- get a global symbol
  * local -- get a local symbol
  * symbol -- get a symbol

Methods that use a symbol:
==========================

  * "Symbol ? IndexedVariable" -- see ?, -- comparison operator
  * ? Symbol -- view brief documentation of a symbol
  * "about(Symbol)" -- see about, -- search the documentation
  * "addHook(Symbol,Function)" -- see addHook, -- add a hook
    function to an object for later processing
  * "autoload(Symbol,String)" -- see autoload, -- arrange for a
    function to be loaded automatically
  * "baseName(Symbol)" -- see baseName, -- the base name of a
    generator
  * "code(Symbol)" -- see code, -- display source code
  * "concatenate(Symbol)" -- see concatenate, -- join
    strings
  * "dictionary(Symbol)" -- see dictionary, -- determine the
    dictionary to which a symbol belongs
  * "File << Symbol" -- see File << Thing, -- print to a
    file
  * findSynonyms(Symbol) -- find synonyms of
    symbols
  * "frames(Symbol)" -- see frames, -- get the frames associated
    to a closure
  * "help(Symbol)" -- see help, -- view documentation nodes
  * "hooks(Symbol)" -- see hooks, -- list hooks attached to a key
  * "installAssignmentMethod(Symbol,HashTable,Function)" -- see
    installAssignmentMethod, -- install methods
    assignment to the value of an operator
  * "installAssignmentMethod(Symbol,HashTable,HashTable,Function)" -- see
    installAssignmentMethod, -- install methods
    assignment to the value of an operator
  * "installAssignmentMethod(Symbol,HashTable,HashTable,Option)" -- see
    installAssignmentMethod, -- install methods
    assignment to the value of an operator
  * "installAssignmentMethod(Symbol,HashTable,Option)" -- see
    installAssignmentMethod, -- install methods
    assignment to the value of an operator
  * "localDictionaries(Symbol)" -- see localDictionaries,
    -- get local dictionaries
  * "locate(Symbol)" -- see locate, -- locate source code
  * "methods(Symbol)" -- see methods, -- list methods
  * "package(Symbol)" -- see package, -- get containing package
  * "runHooks(Symbol,Thing)" -- see runHooks, -- run the hook
    functions stored in an object
  * Symbol .. Symbol -- sequences of consecutive
    symbols
  * Symbol ..< Symbol -- sequences of consecutive
    symbols
  * Symbol == Symbol (missing documentation)
  * Symbol _ Ring -- get a ring variable by name
  * Symbol _ Thing -- index variable
  * Symbol _ Thing = Thing -- assignment to an
    indexed variable
  * value(Symbol) -- retrieve the value of a symbol

For the programmer
==================

The object Symbol, is a type, with ancestor class
Thing.

symbol -- get a symbol
**********************

Description
===========

symbol s provides the symbol s, even if s currently has a value.

+---------------+
|i1 : num       |
|               |
|o1 = num       |
|               |
|o1 : Symbol    |
+---------------+
|i2 : num = 5   |
|               |
|o2 = 5         |
+---------------+
|i3 : num       |
|               |
|o3 = 5         |
+---------------+
|i4 : symbol num|
|               |
|o4 = num       |
|               |
|o4 : Symbol    |
+---------------+

If s is an operator, then the corresponding symbol is provided.  This symbol is
used by the interpreter in constructing keys for methods associated to the
symbol.
+-------------+
|i5 : symbol +|
|             |
|o5 = +       |
|             |
|o5 : Keyword |
+-------------+

See also
========

  * local -- get a local symbol
  * global -- get a global symbol
  * value -- evaluate

For the programmer
==================

The object symbol, is a keyword.

Symbol .. Symbol -- sequences of consecutive symbols
****************************************************

Synopsis
========

  * Operator: ..,
  * Usage:
        s .. t
  * Inputs:
      * s
      * t
  * Outputs:
      * the sequence of consecutive symbols useful as variables in polynomial
        rings, from s to t, inclusive, as determined by the vars(ZZ),

Description
===========

+-----------------------+
|i1 : x .. z            |
|                       |
|o1 = (x, y, z)         |
|                       |
|o1 : Sequence          |
+-----------------------+
|i2 : x .. C            |
|                       |
|o2 = (x, y, z, A, B, C)|
|                       |
|o2 : Sequence          |
+-----------------------+

Ways to use this method:
========================

  * Symbol .. Symbol -- sequences of consecutive
    symbols

Symbol ..< Symbol -- sequences of consecutive symbols
*****************************************************

Synopsis
========

  * Operator: ..<,
  * Usage:
        s ..< t
  * Inputs:
      * s
      * t
  * Outputs:
      * the sequence of consecutive symbols useful as variables in polynomial
        rings, from s to t, not including the endpoint, as determined by the
        vars(ZZ),

Description
===========

+--------------------+
|i1 : x ..< z        |
|                    |
|o1 = (x, y)         |
|                    |
|o1 : Sequence       |
+--------------------+
|i2 : x ..< C        |
|                    |
|o2 = (x, y, z, A, B)|
|                    |
|o2 : Sequence       |
+--------------------+

Ways to use this method:
========================

  * Symbol ..< Symbol -- sequences of consecutive
    symbols

Symbol _ Ring -- get a ring variable by name
********************************************

Synopsis
========

  * Operator: _,
  * Usage:
        x_R
  * Inputs:
      * x, or a ring element,
      * R
  * Outputs:
      * a ring element, the variable of R whose name is x

Description
===========

+-------------------+
|i1 : R = ZZ[x,y,z];|
+-------------------+
|i2 : use R;        |
+-------------------+
|i3 : S = ZZ[x,t];  |
+-------------------+
|i4 : x             |
|                   |
|o4 = x             |
|                   |
|o4 : S             |
+-------------------+
The symbol x now refers to the variable x in the ring S. There are various ways
of now referring to x in the ring R.
+-------------+
|i5 : R_0     |
|             |
|o5 = x       |
|             |
|o5 : R       |
+-------------+
|i6 : symbol x|
|             |
|o6 = x       |
|             |
|o6 : Symbol  |
+-------------+
|i7 : oo_R    |
|             |
|o7 = x       |
|             |
|o7 : R       |
+-------------+
|i8 : use R;  |
+-------------+
|i9 : x       |
|             |
|o9 = x       |
|             |
|o9 : R       |
+-------------+

See also
========

  * Ring _ ZZ -- get a ring variable by index
  * String _ Ring -- get a ring variable by name
  * use(Ring) -- install ring variables and ring
    operations

Ways to use this method:
========================

  * Symbol _ Ring -- get a ring variable by name

Symbol _ Thing -- index variable
********************************

Synopsis
========

  * Operator: _,
  * Usage:
        s_v
  * Inputs:
      * s
      * v
  * Outputs:
      * an indexed variable,

Description
===========

The subscript can be anything, even a mutable object.  Often, the subscripts
are numbers or sequences. Sequences usually print nicer than lists.
+--------------------+
|i1 : x_(1,3)        |
|                    |
|o1 = x              |
|      1,3           |
|                    |
|o1 : IndexedVariable|
+--------------------+
|i2 : x_{1,3}        |
|                    |
|o2 = x              |
|      {1, 3}        |
|                    |
|o2 : IndexedVariable|
+--------------------+
Indexed variables can be used for ring variables.
+-----------------------------------------------------------------+
|i3 : R = ZZ[x_(1,1)..x_(2,3),y_a..y_f]                           |
|                                                                 |
|o3 = R                                                           |
|                                                                 |
|o3 : PolynomialRing                                              |
+-----------------------------------------------------------------+
|i4 : gens R                                                      |
|                                                                 |
|o4 = {x   , x   , x   , x   , x   , x   , y , y , y , y , y , y }|
|       1,1   1,2   1,3   2,1   2,2   2,3   a   b   c   d   e   f |
|                                                                 |
|o4 : List                                                        |
+-----------------------------------------------------------------+

Ways to use this method:
========================

  * Symbol _ Thing -- index variable

Symbol _ Thing = Thing -- assignment to an indexed variable
***********************************************************

Synopsis
========

  * Operator: _,
  * Usage:
        x_a = v
  * Inputs:
      * x
      * a
      * v
  * Outputs:
      * v
  * Consequences:
      * the indexed variable x_a is assigned the value v.

Description
===========

+--------------------+
|i1 : x_a            |
|                    |
|o1 = x              |
|      a             |
|                    |
|o1 : IndexedVariable|
+--------------------+
|i2 : x_a = b        |
|                    |
|o2 = b              |
|                    |
|o2 : Symbol         |
+--------------------+
|i3 : x_a            |
|                    |
|o3 = b              |
|                    |
|o3 : Symbol         |
+--------------------+
|i4 : x_c            |
|                    |
|o4 = x              |
|      c             |
|                    |
|o4 : IndexedVariable|
+--------------------+
|i5 : x_c = d        |
|                    |
|o5 = d              |
|                    |
|o5 : Symbol         |
+--------------------+
|i6 : x_c            |
|                    |
|o6 = d              |
|                    |
|o6 : Symbol         |
+--------------------+
The source code explains how it works, behind the scenes.
    -- code for method: Symbol _ Thing
    ../../../../../Macaulay2/m2/variables.m2:49:18-49:57: --source code:
    Symbol _ Thing := (X,i) -> new IndexedVariable from {X,i}
    ---------------------------------------------------------------------------
    -- code for method: Symbol _ Thing = Thing
    ../../../../../Macaulay2/m2/variables.m2:57:17-60:14: --source code:
    Symbol _ Thing = (x,i,e) -> (
         x' := value x;
         if not instance(x',IndexedVariableTable) then x' = new IndexedVariable
         x'_i = e)
-------------------------------------------------------------------------------
-----

Table from x;
+---------------------------------------+
|i7 : peek x                            |
|                                       |
|o7 = IndexedVariableTable{a => b      }|
|                          c => d       |
|                          symbol$ => x |
+---------------------------------------+

See also
========

  * IndexedVariable -- the class of all indexed
    variables

Ways to use this method:
========================

  * Symbol _ Thing = Thing -- assignment to an
    indexed variable

symbolBody -- symbol bodies
***************************

Description
===========

A Macaulay2 symbol is much like a function closure, in that it comes equipped
with a pointer to a frame that contains a value for it.  That value can be
recovered with the function value, as follows.

+----------------------+
|i1 : f = x -> symbol x|
|                      |
|o1 = f                |
|                      |
|o1 : FunctionClosure  |
+----------------------+
|i2 : s = f 1          |
|                      |
|o2 = x                |
|                      |
|o2 : Symbol           |
+----------------------+
|i3 : t = f 2          |
|                      |
|o3 = x                |
|                      |
|o3 : Symbol           |
+----------------------+

The two symbols created in the example above have something in common -- they
are created by the same bit of code (the function f), but they have different
values.

+------------+
|i4 : value s|
|            |
|o4 = 1      |
+------------+
|i5 : value t|
|            |
|o5 = 2      |
+------------+

To allow the user to determine whether two symbols are created by the same bit
of code, Macaulay2 has the notion of symbol body, which parallel to the notion
of function body.  It's essentially the symbol, but without the pointer to the
frame that contains the value.

+----------------------------------+
|i6 : symbolBody s                 |
|                                  |
|o6 = x                            |
|                                  |
|o6 : SymbolBody                   |
+----------------------------------+
|i7 : symbolBody t                 |
|                                  |
|o7 = x                            |
|                                  |
|o7 : SymbolBody                   |
+----------------------------------+
|i8 : symbolBody s === symbolBody t|
|                                  |
|o8 = true                         |
+----------------------------------+

All such symbol bodies are members of the class SymbolBody.

+-----------------------+
|i9 : class symbolBody s|
|                       |
|o9 = SymbolBody        |
|                       |
|o9 : Type              |
+-----------------------+

For the programmer
==================

The object symbolBody, is a compiled function.

symbols used as the name or value of an optional argument
*********************************************************

Symbols used as an option name or value

Symbols used as an option name

Symbols used as an option value

Syzygies -- an optional argument
********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Syzygies:
================================================

  * "gb(...,Syzygies=>...)" -- see gb, -- compute a Gröbner basis

For the programmer
==================

The object Syzygies, is a symbol.

Threads -- an optional argument
*******************************

Description
===========

A symbol used as the name of an optional argument.

For the programmer
==================

The object Threads, is a symbol.

Strategy -- an optional argument
********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Strategy:
================================================

  * "addHook(...,Strategy=>...)" -- see addHook, -- add a hook
    function to an object for later processing
  * adjoint(...,Strategy=>...) (missing documentation)
  * "annihilator(...,Strategy=>...)" -- see annihilator (Saturation),
    -- the annihilator ideal
  * "associatedPrimes(...,Strategy=>...)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "basis(...,Strategy=>...)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * canonicalBundle(...,Strategy=>...) (missing documentation)
  * "mingens(...,Strategy=>...)" -- see Complement, -- a
    Strategy option value
  * "trim(...,Strategy=>...)" -- see Complement, -- a
    Strategy option value
  * "compose(Module,Module,Module,Strategy=>...)" -- see compose,
    -- composition as a pairing on Hom-modules
  * cotangentSheaf(...,Strategy=>...) (missing documentation)
  * determinant(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * dual(ChainComplex,Strategy=>...) (missing documentation)
  * dual(Matrix,Strategy=>...) (missing documentation)
  * "dual(MonomialIdeal,List,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...),
  * "dual(MonomialIdeal,RingElement,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...),
  * dual(MonomialIdeal,Strategy=>...)
  * dual(SheafMap,Strategy=>...) (missing documentation)
  * "End(...,Strategy=>...)" -- see End, -- module of endomorphisms
  * exteriorPower(...,Strategy=>...)
    -- choose between
    Bareiss, Cofactor and Dynamic algorithms
  * "gb(...,Strategy=>...)" -- see gb, -- compute a Gröbner basis
  * gcdLLL(...,Strategy=>...) (missing documentation)
  * "GF(...,Strategy=>...)" -- see GF, -- make a finite field
  * "groebnerBasis(...,Strategy=>...)" -- see groebnerBasis,
    -- Gröbner basis, as a matrix
  * hermite(...,Strategy=>...) (missing documentation)
  * "Hom(...,Strategy=>...)" -- see Hom, -- module of homomorphisms
  * "homomorphism'(...,Strategy=>...)" -- see homomorphism',
    -- get the element of Hom from a homomorphism
  * "hooks(...,Strategy=>...)" -- see hooks, -- list hooks
    attached to a key
  * "idealizer(...,Strategy=>...)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * integralClosure(...,Strategy=>...) (IntegralClosure),
    --
    control the algorithm used
  * "intersect(Ideal,Ideal,Strategy=>...)" -- see intersect(Ideal,Ideal),
    -- compute an intersection of a sequence of
    ideals or modules
  * "intersect(Module,Module,Strategy=>...)" -- see
    intersect(Ideal,Ideal), -- compute an
    intersection of a sequence of ideals or modules
  * "intersectInP(...,Strategy=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "isPrimary(...,Strategy=>...)" -- see isPrimary (PrimaryDecomposition),
    -- determine whether a submodule is
    primary
  * "isPrime(Ideal,Strategy=>...)" -- see isPrime(Ideal) (MinimalPrimes),
    -- whether an ideal is prime
  * LLL(...,Strategy=>...) (LLLBases)
    -- choose among
    different algorithms
  * "localize(...,Strategy=>...)" -- see localize (PrimaryDecomposition),
    -- localize an ideal at a prime ideal
  * "match(...,Strategy=>...)" -- see match, -- regular expression
    matching
  * "decompose(Ideal,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * minors(...,Strategy=>...)
    -- choose between Bareiss,
    Cofactor and Dynamic algorithms
  * "parallelApply(...,Strategy=>...)" -- see parallelApply,
    -- apply a function to each element in parallel
  * "primaryComponent(...,Strategy=>...)" -- see primaryComponent (PrimaryDecomposition),
    -- find a primary component
    corresponding to an associated prime
  * pushForward(...,Strategy=>...) (missing documentation)
  * quotient(...,Strategy=>...) (Saturation)
  * "radical(...,Strategy=>...)" -- see radical (MinimalPrimes),
    -- the radical of an ideal
  * "radicalContainment(...,Strategy=>...)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * "analyticSpread(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "associatedGradedRing(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "distinguished(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isLinearType(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isReduction(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "minimalReduction(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "multiplicity(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(Ideal,RingElement,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(Ideal,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "reesAlgebra(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * reesIdeal(...,Strategy=>...) (ReesAlgebra)
    -- Choose a
    strategy for the saturation step
  * "specialFiber(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "specialFiberIdeal(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "regSeqInIdeal(...,Strategy=>...)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * resolution(...,Strategy=>...)
  * saturate(...,Strategy=>...) (Saturation)
  * sheafHom(...,Strategy=>...) (missing documentation)
  * "primaryDecomposition(...,Strategy=>...)" -- see strategies for computing primary decomposition (PrimaryDecomposition),
  * "syz(...,Strategy=>...)" -- see syz(Matrix), --
    compute the syzygy matrix
  * "tangentCone(...,Strategy=>...)" -- see tangentCone(Ideal) (TangentCone),
  * tangentSheaf(...,Strategy=>...) (missing documentation)

For the programmer
==================

The object Strategy, is a symbol.

BasisElementLimit -- an optional argument
*****************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named BasisElementLimit:
=========================================================

  * "gb(...,BasisElementLimit=>...)" -- see gb, -- compute a Gröbner
    basis
  * intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "analyticSpread(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...) (ReesAlgebra),
    -- Bound the number of Groebner basis elements to compute in the
    saturation step
  * "associatedGradedRing(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...) (ReesAlgebra),
    -- Bound the number of Groebner basis elements to compute in the
    saturation step
  * "distinguished(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...) (ReesAlgebra),
    -- Bound the number of Groebner basis elements to compute in the
    saturation step
  * "isLinearType(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...) (ReesAlgebra),
    -- Bound the number of Groebner basis elements to compute in the
    saturation step
  * "isReduction(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...) (ReesAlgebra),
    -- Bound the number of Groebner basis elements to compute in the
    saturation step
  * minimalReduction(...,BasisElementLimit=>...) (ReesAlgebra)
    -- Bound the number of Groebner basis elements to compute in the
    saturation step
  * "multiplicity(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...) (ReesAlgebra),
    -- Bound the number of Groebner basis elements to compute in the
    saturation step
  * "normalCone(Ideal,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...) (ReesAlgebra),
    -- Bound the number of Groebner basis elements to compute in the
    saturation step
  * "normalCone(Ideal,RingElement,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...) (ReesAlgebra),
    -- Bound the number of Groebner basis elements to compute in the
    saturation step
  * "reesAlgebra(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...) (ReesAlgebra),
    -- Bound the number of Groebner basis elements to compute in the
    saturation step
  * "reesIdeal(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...) (ReesAlgebra),
    -- Bound the number of Groebner basis elements to compute in the
    saturation step
  * "specialFiber(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...) (ReesAlgebra),
    -- Bound the number of Groebner basis elements to compute in the
    saturation step
  * "specialFiberIdeal(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...) (ReesAlgebra),
    -- Bound the number of Groebner basis elements to compute in the
    saturation step
  * quotient(...,BasisElementLimit=>...) (Saturation)
  * "saturate(...,BasisElementLimit=>...)" -- see
    quotient(...,BasisElementLimit=>...) (Saturation),
  * "syz(...,BasisElementLimit=>...)" -- see syz(Matrix),
    -- compute the syzygy matrix

For the programmer
==================

The object BasisElementLimit, is a symbol.

DegreeLimit -- an optional argument
***********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named DegreeLimit:
===================================================

  * adjoint(...,DegreeLimit=>...) (missing documentation)
  * "compose(Module,Module,Module,DegreeLimit=>...)" -- see compose,
    -- composition as a pairing on Hom-modules
  * dual(ChainComplex,DegreeLimit=>...) (missing documentation)
  * dual(Matrix,DegreeLimit=>...) (missing documentation)
  * dual(SheafMap,DegreeLimit=>...) (missing documentation)
  * "End(...,DegreeLimit=>...)" -- see End, -- module of
    endomorphisms
  * "gb(...,DegreeLimit=>...)" -- see gb, -- compute a Gröbner basis
  * "Hom(...,DegreeLimit=>...)" -- see Hom, -- module of
    homomorphisms
  * "homomorphism'(...,DegreeLimit=>...)" -- see homomorphism',
    -- get the element of Hom from a homomorphism
  * "intersectInP(...,DegreeLimit=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "minimalBetti(...,DegreeLimit=>...)" -- see minimalBetti,
    -- minimal betti numbers of (the minimal free resolution of)
    a homogeneous ideal or module
  * "pushForward(...,DegreeLimit=>...)" -- see
    pushForward(RingMap,Module),
  * quotient(...,DegreeLimit=>...) (Saturation)
  * "saturate(...,DegreeLimit=>...)" -- see
    quotient(...,DegreeLimit=>...) (Saturation),
  * "analyticSpread(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "associatedGradedRing(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "distinguished(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "isLinearType(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "isReduction(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "minimalReduction(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "multiplicity(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "normalCone(Ideal,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "normalCone(Ideal,RingElement,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "reesAlgebra(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * reesIdeal(...,DegreeLimit=>...) (ReesAlgebra)
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "specialFiber(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * "specialFiberIdeal(...,DegreeLimit=>...)" -- see
    reesIdeal(...,DegreeLimit=>...) (ReesAlgebra),
    -- Bound
    the degrees considered in the saturation step. Defaults to infinity
  * resolution(...,DegreeLimit=>...)
    -- compute only up to
    this degree
  * sheafHom(...,DegreeLimit=>...) (missing documentation)
  * "syz(...,DegreeLimit=>...)" -- see syz(Matrix), --
    compute the syzygy matrix

For the programmer
==================

The object DegreeLimit, is a symbol.

PairLimit -- an optional argument
*********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named PairLimit:
=================================================

  * "gb(...,PairLimit=>...)" -- see gb, -- compute a Gröbner basis
  * "intersectInP(...,PairLimit=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "pushForward(...,PairLimit=>...)" -- see pushForward(RingMap,Module),
  * quotient(...,PairLimit=>...) (Saturation)
  * "saturate(...,PairLimit=>...)" -- see quotient(...,PairLimit=>...) (Saturation),
  * "analyticSpread(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "associatedGradedRing(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "distinguished(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "isLinearType(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "isReduction(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "minimalReduction(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "multiplicity(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "normalCone(Ideal,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "normalCone(Ideal,RingElement,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "reesAlgebra(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * reesIdeal(...,PairLimit=>...) (ReesAlgebra)
    -- Bound the
    number of s-pairs considered in the saturation step
  * "specialFiber(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * "specialFiberIdeal(...,PairLimit=>...)" -- see
    reesIdeal(...,PairLimit=>...) (ReesAlgebra),
    -- Bound the
    number of s-pairs considered in the saturation step
  * resolution(...,PairLimit=>...)
    -- stop when this number
    of pairs has been handled
  * "syz(...,PairLimit=>...)" -- see syz(Matrix), --
    compute the syzygy matrix

For the programmer
==================

The object PairLimit, is a symbol.

DegreeGroup -- an optional argument
***********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named DegreeGroup:
===================================================

  * findHeft(...,DegreeGroup=>...) (missing documentation)
  * monoid(...,DegreeGroup=>...) (missing documentation)
  * newRing(...,DegreeGroup=>...) (missing documentation)
  * symmetricAlgebra(...,DegreeGroup=>...) (missing documentation)
  * tensor(Monoid,Monoid,DegreeGroup=>...) (missing documentation)
  * tensor(PolynomialRing,PolynomialRing,DegreeGroup=>...) (missing
    documentation)
  * tensor(PolynomialRing,QuotientRing,DegreeGroup=>...) (missing
    documentation)
  * tensor(QuotientRing,PolynomialRing,DegreeGroup=>...) (missing
    documentation)
  * tensor(QuotientRing,QuotientRing,DegreeGroup=>...) (missing documentation)
  * tensor(Ring,Ring,DegreeGroup=>...) (missing documentation)

For the programmer
==================

The object DegreeGroup, is a symbol.

Variables -- an optional argument
*********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Variables:
=================================================

  * "basis(...,Variables=>...)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "coefficients(...,Variables=>...)" -- see coefficients,
    -- monomials and their coefficients
  * monoid(...,Variables=>...)
    -- specify the names of the
    indeterminates
  * monomials(...,Variables=>...)
    -- specify variables
  * "newRing(...,Variables=>...)" -- see newRing, -- make a copy
    of a ring, with some features changed
  * "symmetricAlgebra(...,Variables=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Variables=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Variables=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

For the programmer
==================

The object Variables, is a symbol.

DegreeLift -- an optional argument
**********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named DegreeLift:
==================================================

  * "map(...,DegreeLift=>...)" -- see map(Ring,Ring,Matrix),
    -- make a ring map
  * monoid(...,DegreeLift=>...)
    -- specify maps between
    degree groups
  * "newRing(...,DegreeLift=>...)" -- see newRing, -- make a
    copy of a ring, with some features changed
  * "symmetricAlgebra(...,DegreeLift=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,DegreeLift=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,DegreeLift=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

For the programmer
==================

The object DegreeLift, is a symbol.

VariableBaseName -- an optional argument
****************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named VariableBaseName:
========================================================

  * "graphIdeal(...,VariableBaseName=>...)" -- see graphIdeal(RingMap),
    -- the ideal of the graph of the regular map
    corresponding to a ring map
  * "graphRing(...,VariableBaseName=>...)" -- see graphRing(RingMap),
    -- the coordinate ring of the graph of the regular
    map corresponding to a ring map
  * "monoid(...,VariableBaseName=>...)" -- see
    monoid(...,Variables=>...),
    -- specify the names of the indeterminates
  * "newRing(...,VariableBaseName=>...)" -- see newRing, -- make
    a copy of a ring, with some features changed
  * "polarize(...,VariableBaseName=>...)" -- see polarize, --
    given a monomial ideal, computes the squarefree monomial ideal obtained via
    polarization
  * "symmetricAlgebra(...,VariableBaseName=>...)" -- see
    symmetricAlgebra, -- the symmetric algebra of a module
  * "symmetricAlgebraIdeal(...,VariableBaseName=>...)" -- see
    symmetricAlgebraIdeal (ReesAlgebra), -- Ideal of the
    symmetric algebra of an ideal or module
  * "tensor(Monoid,Monoid,VariableBaseName=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids
  * "tensor(Ring,Ring,VariableBaseName=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids

For the programmer
==================

The object VariableBaseName, is a symbol.

DegreeRank -- an optional argument
**********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named DegreeRank:
==================================================

  * "findHeft(...,DegreeRank=>...)" -- see findHeft, -- find a
    heft vector for a list of degrees
  * "monoid(...,DegreeRank=>...)" -- see monoid(...,Degrees=>...),
    -- specify the degrees of the
    variables
  * "newRing(...,DegreeRank=>...)" -- see newRing, -- make a
    copy of a ring, with some features changed
  * "symmetricAlgebra(...,DegreeRank=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,DegreeRank=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,DegreeRank=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

For the programmer
==================

The object DegreeRank, is a symbol.

Inverses -- an optional argument
********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Inverses:
================================================

  * monoid(...,Inverses=>...)
    -- allow negative exponents in
    monomials
  * "newRing(...,Inverses=>...)" -- see newRing, -- make a copy
    of a ring, with some features changed
  * "symmetricAlgebra(...,Inverses=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Inverses=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Inverses=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

For the programmer
==================

The object Inverses, is a symbol.

Degrees -- an optional argument
*******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Degrees:
===============================================

  * monoid(...,Degrees=>...),
    -- specify the degrees of the variables
  * "newRing(...,Degrees=>...)" -- see newRing, -- make a copy
    of a ring, with some features changed
  * "symmetricAlgebra(...,Degrees=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Degrees=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Degrees=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

For the programmer
==================

The object Degrees, is a symbol.

Join -- an optional argument
****************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Join:
============================================

  * monoid(...,Join=>...), --
    specify how to handle degrees in the coefficient ring
  * "newRing(...,Join=>...)" -- see newRing, -- make a copy of a
    ring, with some features changed
  * "symmetricAlgebra(...,Join=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Join=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Join=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

For the programmer
==================

The object Join, is a symbol.

MonomialSize -- an optional argument
************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named MonomialSize:
====================================================

  * "graphIdeal(...,MonomialSize=>...)" -- see graphIdeal(RingMap),
    -- the ideal of the graph of the regular map
    corresponding to a ring map
  * "graphRing(...,MonomialSize=>...)" -- see graphRing(RingMap),
    -- the coordinate ring of the graph of the regular
    map corresponding to a ring map
  * monoid(...,MonomialSize=>...)
    -- specify the bit-length
    of monomial exponents in the ring
  * "newRing(...,MonomialSize=>...)" -- see newRing, -- make a
    copy of a ring, with some features changed
  * "symmetricAlgebra(...,MonomialSize=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,MonomialSize=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids
  * "tensor(Ring,Ring,MonomialSize=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

For the programmer
==================

The object MonomialSize, is a symbol.

Local -- an optional argument
*****************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Local:
=============================================

  * monoid(...,Local=>...), --
    specify local or global monomial order
  * "newRing(...,Local=>...)" -- see newRing, -- make a copy of
    a ring, with some features changed
  * "symmetricAlgebra(...,Local=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Local=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Local=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

For the programmer
==================

The object Local, is a symbol.

Heft -- an optional argument
****************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Heft:
============================================

  * monoid(...,Heft=>...), --
    specify a heft vector
  * "newRing(...,Heft=>...)" -- see newRing, -- make a copy of a
    ring, with some features changed
  * "symmetricAlgebra(...,Heft=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,Heft=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,Heft=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

For the programmer
==================

The object Heft, is a symbol.

Constants -- an optional argument
*********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Constants:
=================================================

  * monoid(...,Constants=>...) (missing documentation)
  * newRing(...,Constants=>...) (missing documentation)
  * symmetricAlgebra(...,Constants=>...) (missing documentation)
  * tensor(Monoid,Monoid,Constants=>...) (missing documentation)
  * tensor(PolynomialRing,PolynomialRing,Constants=>...) (missing
    documentation)
  * tensor(PolynomialRing,QuotientRing,Constants=>...) (missing documentation)
  * tensor(QuotientRing,PolynomialRing,Constants=>...) (missing documentation)
  * tensor(QuotientRing,QuotientRing,Constants=>...) (missing documentation)
  * tensor(Ring,Ring,Constants=>...) (missing documentation)

For the programmer
==================

The object Constants, is a symbol.

SkewCommutative -- an optional argument
***************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named SkewCommutative:
=======================================================

  * monoid(...,SkewCommutative=>...)
    -- specify Skew
    commuting variables in the ring
  * "newRing(...,SkewCommutative=>...)" -- see newRing, -- make
    a copy of a ring, with some features changed
  * "symmetricAlgebra(...,SkewCommutative=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,SkewCommutative=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids
  * "tensor(Ring,Ring,SkewCommutative=>...)" -- see
    tensor(Monoid,Monoid), -- tensor product of
    monoids

For the programmer
==================

The object SkewCommutative, is a symbol.

DegreeMap -- an optional argument
*********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named DegreeMap:
=================================================

  * "map(...,DegreeMap=>...)" -- see map(Ring,Ring,Matrix),
    -- make a ring map
  * "monoid(...,DegreeMap=>...)" -- see monoid(...,DegreeLift=>...),
    -- specify maps between
    degree groups
  * "newRing(...,DegreeMap=>...)" -- see newRing, -- make a copy
    of a ring, with some features changed
  * "symmetricAlgebra(...,DegreeMap=>...)" -- see symmetricAlgebra,
    -- the symmetric algebra of a module
  * "tensor(Monoid,Monoid,DegreeMap=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tensor(Ring,Ring,DegreeMap=>...)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids

For the programmer
==================

The object DegreeMap, is a symbol.

Verbosity -- an optional argument
*********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Verbosity:
=================================================

  * icFracP(...,Verbosity=>...) (IntegralClosure)
    -- Prints
    out the conductor element and the number of intermediate modules it
    computed.
  * "idealizer(...,Verbosity=>...)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * integralClosure(...,Verbosity=>...) (IntegralClosure),
    --
    display a certain amount of detail about the computation
  * "isPrime(Ideal,Verbosity=>...)" -- see isPrime(Ideal) (MinimalPrimes),
    -- whether an ideal is prime
  * "makeS2(...,Verbosity=>...)" -- see makeS2 (IntegralClosure),
    -- compute the S2ification of a reduced ring
  * "decompose(Ideal,Verbosity=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,Verbosity=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "ringFromFractions(...,Verbosity=>...)" -- see ringFromFractions (IntegralClosure),
    -- find presentation for f.g. ring

For the programmer
==================

The object Verbosity, is a symbol.

Generic -- an optional argument
*******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Generic:
===============================================

  * codim(CoherentSheaf,Generic=>...) (missing documentation)
  * codim(Ideal,Generic=>...)
  * "codim(Module,Generic=>...)" -- see codim(Ideal,Generic=>...),
  * "codim(PolynomialRing,Generic=>...)" -- see
    codim(Ideal,Generic=>...),
  * "codim(QuotientRing,Generic=>...)" -- see codim(Ideal,Generic=>...),
  * codim(MonomialIdeal,Generic=>...) (missing documentation)
  * codim(Variety,Generic=>...) (missing documentation)

For the programmer
==================

The object Generic, is a symbol.

CodimensionLimit -- an optional argument
****************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named CodimensionLimit:
========================================================

  * "associatedPrimes(...,CodimensionLimit=>...)" -- see
    associatedPrimes (PrimaryDecomposition), -- find
    associated primes
  * "gb(...,CodimensionLimit=>...)" -- see gb, -- compute a Gröbner
    basis
  * "decompose(Ideal,CodimensionLimit=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,CodimensionLimit=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal

For the programmer
==================

The object CodimensionLimit, is a symbol.

Verify -- an optional argument
******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Verify:
==============================================

  * ^(Number,Ring,Verify=>...) (missing documentation)
  * "extend(...,Verify=>...)" -- see
    extend(ChainComplex,ChainComplex,Matrix),
    -- extend a module map to
    a chain map, if possible
  * inducedMap(...,Verify=>...)
    -- verify that a map is
    well-defined
  * "lift(...,Verify=>...)" -- see lift, -- lift to another ring

For the programmer
==================

The object Verify, is a symbol.

CoefficientRing -- an optional argument
***************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named CoefficientRing:
=======================================================

  * flattenRing(...,CoefficientRing=>...)
    -- optionally
    specify the desired coefficient ring of the flattened ring
  * "generators(...,CoefficientRing=>...)" -- see generators(Ring),
    -- the list of generators of a ring
  * "Grassmannian(...,CoefficientRing=>...)" -- see Grassmannian(ZZ,ZZ),
    -- the Grassmannian of linear subspaces of a
    vector space
  * "Schubert(...,CoefficientRing=>...)" -- see
    Schubert(ZZ,ZZ,VisibleList), -- find
    the Plücker ideal of a Schubert variety

For the programmer
==================

The object CoefficientRing, is a symbol.

FollowLinks -- an optional argument
***********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named FollowLinks:
===================================================

  * "copyDirectory(...,FollowLinks=>...)" -- see
    copyDirectory(String,String),
  * "findFiles(...,FollowLinks=>...)" -- see findFiles, --
    find files recursively
  * "symlinkDirectory(...,FollowLinks=>...)" -- see
    symlinkDirectory(String,String), --
    make symbolic links for all files in a directory tree

For the programmer
==================

The object FollowLinks, is a symbol.

Exclude -- an optional argument
*******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Exclude:
===============================================

  * "copyDirectory(...,Exclude=>...)" -- see
    copyDirectory(String,String),
  * "findFiles(...,Exclude=>...)" -- see findFiles, -- find
    files recursively
  * "minimalPresentation(...,Exclude=>...)" -- see
    minimalPresentation(Ring), -- compute a
    minimal presentation of a quotient ring
  * "prune(...,Exclude=>...)" -- see minimalPresentation(Ring),
    -- compute a minimal presentation of a
    quotient ring
  * "symlinkDirectory(...,Exclude=>...)" -- see
    symlinkDirectory(String,String), --
    make symbolic links for all files in a directory tree

For the programmer
==================

The object Exclude, is a symbol.

InstallPrefix -- an optional argument
*************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named InstallPrefix:
=====================================================

  * "installPackage(...,InstallPrefix=>...)" -- see installPackage,
    -- load and install a package and its documentation
  * "uninstallPackage(...,InstallPrefix=>...)" -- see uninstallPackage,
    -- uninstall a package and remove its documentation

For the programmer
==================

The object InstallPrefix, is a symbol.

SyzygyMatrix -- an optional argument
************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named SyzygyMatrix:
====================================================

  * forceGB(...,SyzygyMatrix=>...)
    -- specify the syzygy
    matrix
  * "markedGB(...,SyzygyMatrix=>...)" -- see markedGB(Matrix,Matrix),
    -- make a marked Gröbner basis

For the programmer
==================

The object SyzygyMatrix, is a symbol.

ChangeMatrix -- an optional argument
************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named ChangeMatrix:
====================================================

  * forceGB(...,ChangeMatrix=>...)
    -- inform Macaulay2 about
    the change of basis matrix from GB to generators
  * "gb(...,ChangeMatrix=>...)" -- see gb, -- compute a Gröbner basis
  * hermite(...,ChangeMatrix=>...) (missing documentation)
  * LLL(...,ChangeMatrix=>...) (LLLBases)
    -- also find change
    of basis matrix
  * "markedGB(...,ChangeMatrix=>...)" -- see markedGB(Matrix,Matrix),
    -- make a marked Gröbner basis
  * "smithNormalForm(...,ChangeMatrix=>...)" -- see
    smithNormalForm(Matrix), -- smith normal form
    for a matrix over ZZ or a PID

For the programmer
==================

The object ChangeMatrix, is a symbol.

MinimalMatrix -- an optional argument
*************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named MinimalMatrix:
=====================================================

  * forceGB(...,MinimalMatrix=>...)
    -- specify the minimal
    generator matrix
  * "markedGB(...,MinimalMatrix=>...)" -- see markedGB(Matrix,Matrix),
    -- make a marked Gröbner basis

For the programmer
==================

The object MinimalMatrix, is a symbol.

SyzygyLimit -- an optional argument
***********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named SyzygyLimit:
===================================================

  * "gb(...,SyzygyLimit=>...)" -- see gb, -- compute a Gröbner basis
  * resolution(...,SyzygyLimit=>...)
    -- stop when this
    number of syzygies is reached
  * "syz(...,SyzygyLimit=>...)" -- see syz(Matrix), --
    compute the syzygy matrix

For the programmer
==================

The object SyzygyLimit, is a symbol.

StopBeforeComputation -- an optional argument
*********************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named StopBeforeComputation:
=============================================================

  * "gb(...,StopBeforeComputation=>...)" -- see gb, -- compute a
    Gröbner basis
  * "pushForward(...,StopBeforeComputation=>...)" -- see
    pushForward(RingMap,Module),
  * resolution(...,StopBeforeComputation=>...)
    -- whether to
    stop the computation immediately
  * "syz(...,StopBeforeComputation=>...)" -- see syz(Matrix),
    -- compute the syzygy matrix

For the programmer
==================

The object StopBeforeComputation, is a
symbol.

DivideConquer -- an optional argument
*************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named DivideConquer:
=====================================================

  * SVD(...,DivideConquer=>...)
    -- Use the lapack divide and
    conquer SVD algorithm

For the programmer
==================

The object DivideConquer, is a symbol.

Hermitian -- an optional argument
*********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Hermitian:
=================================================

  * eigenvalues(...,Hermitian=>...)
    -- Hermitian=>true means
    assume the matrix is symmetric or Hermitian
  * eigenvectors(...,Hermitian=>...)
    -- Hermitian=>true
    means assume the matrix is symmetric or Hermitian

For the programmer
==================

The object Hermitian, is a symbol.

Limit -- an optional argument
*****************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Limit:
=============================================

  * "basis(...,Limit=>...)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * hermite(...,Limit=>...) (missing documentation)
  * icFracP(...,Limit=>...) (IntegralClosure)
    -- Limits the
    number of computed intermediate modules.
  * "independentSets(...,Limit=>...)" -- see independentSets,
    -- some size-maximal independent subsets of variables
    modulo an ideal
  * integralClosure(...,Limit=>...) (IntegralClosure)
    -- do a
    partial integral closure
  * kernelLLL(...,Limit=>...) (missing documentation)
  * LLL(...,Limit=>...) (missing documentation)
  * "minors(...,Limit=>...)" -- see minors(ZZ,Matrix),
    -- ideal generated by minors
  * "oeis(...,Limit=>...)" -- see oeis (OnlineLookup), -- OEIS
    lookup
  * "simpleDocFrob(...,Limit=>...)" -- see simpleDocFrob (SimpleDoc),
    -- a sample documentation node

For the programmer
==================

The object Limit, is a symbol.

SourceRing -- an optional argument
**********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named SourceRing:
==================================================

  * "basis(...,SourceRing=>...)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module

For the programmer
==================

The object SourceRing, is a symbol.

Truncate -- an optional argument
********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Truncate:
================================================

  * "basis(...,Truncate=>...)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module

For the programmer
==================

The object Truncate, is a symbol.

Body -- an optional argument
****************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Body:
============================================

  * "about(...,Body=>...)" -- see about, -- search the
    documentation

For the programmer
==================

The object Body, is a symbol.

StopWithMinimalGenerators -- an optional argument
*************************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named StopWithMinimalGenerators:
=================================================================

  * "gb(...,StopWithMinimalGenerators=>...)" -- see gb, -- compute a
    Gröbner basis

For the programmer
==================

The object StopWithMinimalGenerators, is a
symbol.

MaxReductionCount -- an optional argument
*****************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named MaxReductionCount:
=========================================================

  * "gb(...,MaxReductionCount=>...)" -- see gb, -- compute a Gröbner
    basis
  * "syz(...,MaxReductionCount=>...)" -- see syz(Matrix),
    -- compute the syzygy matrix

For the programmer
==================

The object MaxReductionCount, is a symbol.

GBDegrees -- an optional argument
*********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named GBDegrees:
=================================================

  * "gb(...,GBDegrees=>...)" -- see gb, -- compute a Gröbner basis
  * "syz(...,GBDegrees=>...)" -- see syz(Matrix), --
    compute the syzygy matrix

For the programmer
==================

The object GBDegrees, is a symbol.

Algorithm -- an optional argument
*********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Algorithm:
=================================================

  * discriminant(...,Algorithm=>...) (missing documentation)
  * "gb(...,Algorithm=>...)" -- see gb, -- compute a Gröbner basis
  * resultant(...,Algorithm=>...) (missing documentation)
  * "syz(...,Algorithm=>...)" -- see syz(Matrix), --
    compute the syzygy matrix

For the programmer
==================

The object Algorithm, is a symbol.

SyzygyRows -- an optional argument
**********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named SyzygyRows:
==================================================

  * "gb(...,SyzygyRows=>...)" -- see gb, -- compute a Gröbner basis
  * "syz(...,SyzygyRows=>...)" -- see syz(Matrix), --
    compute the syzygy matrix

For the programmer
==================

The object SyzygyRows, is a symbol.

Hilbert -- an optional argument
*******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Hilbert:
===============================================

  * "gb(...,Hilbert=>...)" -- see gb, -- compute a Gröbner basis

For the programmer
==================

The object Hilbert, is a symbol.

Undo -- an optional argument
****************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Undo:
============================================

  * "symlinkDirectory(...,Undo=>...)" -- see
    symlinkDirectory(String,String), --
    make symbolic links for all files in a directory tree

For the programmer
==================

The object Undo, is a symbol.

Height -- an optional argument
******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Height:
==============================================

  * "fillMatrix(...,Height=>...)" -- see fillMatrix, -- fill
    a mutable matrix with random numbers
  * "random(...,Height=>...)" -- see random(ZZ,Ring),
    -- get a random homogeneous element from a graded
    ring

For the programmer
==================

The object Height, is a symbol.

MaximalRank -- an optional argument
***********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named MaximalRank:
===================================================

  * "random(...,MaximalRank=>...)" -- see random(Module,Module),
    -- get a random map of module
  * "solve(...,MaximalRank=>...)" -- see solve, -- solve linear
    equation(s)

For the programmer
==================

The object MaximalRank, is a symbol.

Density -- an optional argument
*******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Density:
===============================================

  * "fillMatrix(...,Density=>...)" -- see fillMatrix, -- fill
    a mutable matrix with random numbers
  * "random(...,Density=>...)" -- see random(Module,Module),
    -- get a random map of module

For the programmer
==================

The object Density, is a symbol.

UpperTriangular -- an optional argument
***************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named UpperTriangular:
=======================================================

  * "fillMatrix(...,UpperTriangular=>...)" -- see fillMatrix,
    -- fill a mutable matrix with random numbers
  * "random(...,UpperTriangular=>...)" -- see random(Module,Module),
    -- get a random map of module

For the programmer
==================

The object UpperTriangular, is a symbol.

UserMode -- an optional argument
********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named UserMode:
================================================

  * "capture(...,UserMode=>...)" -- see capture, -- evaluate
    Macaulay2 code and capture the output
  * "check(...,UserMode=>...)" -- see check, -- perform tests of a
    package
  * "installPackage(...,UserMode=>...)" -- see installPackage,
    -- load and install a package and its documentation

For the programmer
==================

The object UserMode, is a symbol.

Dense -- an optional argument
*****************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Dense:
=============================================

  * "mutableIdentity(...,Dense=>...)" -- see mutableIdentity(Ring,ZZ),
    -- make a mutable identity matrix
  * "mutableMatrix(...,Dense=>...)" -- see mutableMatrix,
    -- make a mutable matrix
  * "randomMutableMatrix(...,Dense=>...)" -- see
    randomMutableMatrix(ZZ,ZZ,RR,ZZ),
    -- a random mutable matrix of
    integers

For the programmer
==================

The object Dense, is a symbol.

LoadDocumentation -- an optional argument
*****************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named LoadDocumentation:
=========================================================

  * "loadPackage(...,LoadDocumentation=>...)" -- see loadPackage,
    -- load a package
  * "needsPackage(...,LoadDocumentation=>...)" -- see needsPackage,
    -- load a package if not already loaded

For the programmer
==================

The object LoadDocumentation, is a symbol.

Configuration -- an optional argument
*************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Configuration:
=====================================================

  * "loadPackage(...,Configuration=>...)" -- see loadPackage,
    -- load a package
  * "needsPackage(...,Configuration=>...)" -- see needsPackage,
    -- load a package if not already loaded
  * "newPackage(...,Configuration=>...)" -- see newPackage,
    -- the preamble of a package

For the programmer
==================

The object Configuration, is a symbol.

FileName -- an optional argument
********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named FileName:
================================================

  * "installPackage(...,FileName=>...)" -- see installPackage,
    -- load and install a package and its documentation
  * "loadPackage(...,FileName=>...)" -- see loadPackage, --
    load a package
  * "needsPackage(...,FileName=>...)" -- see needsPackage,
    -- load a package if not already loaded
  * "readPackage(...,FileName=>...)" -- see readPackage, --
    read the package preamble

For the programmer
==================

The object FileName, is a symbol.

Reload -- an optional argument
******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Reload:
==============================================

  * "loadPackage(...,Reload=>...)" -- see loadPackage, --
    load a package
  * "needsPackage(...,Reload=>...)" -- see needsPackage, --
    load a package if not already loaded
  * "newPackage(...,Reload=>...)" -- see newPackage, -- the
    preamble of a package

For the programmer
==================

The object Reload, is a symbol.

DebuggingMode -- an optional argument
*************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named DebuggingMode:
=====================================================

  * "installPackage(...,DebuggingMode=>...)" -- see installPackage,
    -- load and install a package and its documentation
  * "loadPackage(...,DebuggingMode=>...)" -- see loadPackage,
    -- load a package
  * "needsPackage(...,DebuggingMode=>...)" -- see needsPackage,
    -- load a package if not already loaded
  * "newPackage(...,DebuggingMode=>...)" -- see newPackage,
    -- the preamble of a package

For the programmer
==================

The object DebuggingMode, is a symbol.

PackageExports -- an optional argument
**************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named PackageExports:
======================================================

  * "capture(...,PackageExports=>...)" -- see capture, --
    evaluate Macaulay2 code and capture the output
  * "newPackage(...,PackageExports=>...)" -- see newPackage,
    -- the preamble of a package

For the programmer
==================

The object PackageExports, is a symbol.

Invertible -- an optional argument
**********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Invertible:
==================================================

  * solve(...,Invertible=>...) (missing documentation)

For the programmer
==================

The object Invertible, is a symbol.

ClosestFit -- an optional argument
**********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named ClosestFit:
==================================================

  * "solve(...,ClosestFit=>...)" -- see solve, -- solve linear
    equation(s)

For the programmer
==================

The object ClosestFit, is a symbol.

SizeLimit -- an optional argument
*********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named SizeLimit:
=================================================

  * "GF(...,SizeLimit=>...)" -- see GF, -- make a finite field

For the programmer
==================

The object SizeLimit, is a symbol.

UseHilbertFunction -- an optional argument
******************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named UseHilbertFunction:
==========================================================

  * "pushForward(...,UseHilbertFunction=>...)" -- see
    pushForward(RingMap,Module),

For the programmer
==================

The object UseHilbertFunction, is a symbol.

SeparateExec -- an optional argument
************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named SeparateExec:
====================================================

  * "installPackage(...,SeparateExec=>...)" -- see installPackage,
    -- load and install a package and its documentation

For the programmer
==================

The object SeparateExec, is a symbol.

RunExamples -- an optional argument
***********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named RunExamples:
===================================================

  * "installPackage(...,RunExamples=>...)" -- see installPackage,
    -- load and install a package and its documentation

For the programmer
==================

The object RunExamples, is a symbol.

MakeHTML -- an optional argument
********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named MakeHTML:
================================================

  * "installPackage(...,MakeHTML=>...)" -- see installPackage,
    -- load and install a package and its documentation

For the programmer
==================

The object MakeHTML, is a symbol.

RemakeAllDocumentation -- an optional argument
**********************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named RemakeAllDocumentation:
==============================================================

  * "installPackage(...,RemakeAllDocumentation=>...)" -- see
    installPackage, -- load and install a package and its
    documentation

For the programmer
==================

The object RemakeAllDocumentation, is a
symbol.

MakeInfo -- an optional argument
********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named MakeInfo:
================================================

  * "installPackage(...,MakeInfo=>...)" -- see installPackage,
    -- load and install a package and its documentation

For the programmer
==================

The object MakeInfo, is a symbol.

RerunExamples -- an optional argument
*************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named RerunExamples:
=====================================================

  * "installPackage(...,RerunExamples=>...)" -- see installPackage,
    -- load and install a package and its documentation

For the programmer
==================

The object RerunExamples, is a symbol.

IgnoreExampleErrors -- an optional argument
*******************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named IgnoreExampleErrors:
===========================================================

  * "installPackage(...,IgnoreExampleErrors=>...)" -- see installPackage,
    -- load and install a package and its documentation

For the programmer
==================

The object IgnoreExampleErrors, is a symbol.

MakePDF -- an optional argument
*******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named MakePDF:
===============================================

  * "installPackage(...,MakePDF=>...)" -- see installPackage,
    -- load and install a package and its documentation

For the programmer
==================

The object MakePDF, is a symbol.

CacheExampleOutput -- an optional argument
******************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named CacheExampleOutput:
==========================================================

  * "installPackage(...,CacheExampleOutput=>...)" -- see installPackage,
    -- load and install a package and its documentation
  * "newPackage(...,CacheExampleOutput=>...)" -- see newPackage,
    -- the preamble of a package

For the programmer
==================

The object CacheExampleOutput, is a symbol.

MakeLinks -- an optional argument
*********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named MakeLinks:
=================================================

  * "installPackage(...,MakeLinks=>...)" -- see installPackage,
    -- load and install a package and its documentation

For the programmer
==================

The object MakeLinks, is a symbol.

MakeDocumentation -- an optional argument
*****************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named MakeDocumentation:
=========================================================

  * "installPackage(...,MakeDocumentation=>...)" -- see installPackage,
    -- load and install a package and its documentation

For the programmer
==================

The object MakeDocumentation, is a symbol.

CheckDocumentation -- an optional argument
******************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named CheckDocumentation:
==========================================================

  * "installPackage(...,CheckDocumentation=>...)" -- see installPackage,
    -- load and install a package and its documentation

For the programmer
==================

The object CheckDocumentation, is a symbol.

Minimize -- an optional argument
********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Minimize:
================================================

  * betti(...,Minimize=>...),
    -- minimal betti numbers of a non-minimal free resolution

For the programmer
==================

The object Minimize, is a symbol.

Prefix -- an optional argument
******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Prefix:
==============================================

  * "findProgram(...,Prefix=>...)" -- see findProgram, --
    load external program

For the programmer
==================

The object Prefix, is a symbol.

Version -- an optional argument
*******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Version:
===============================================

  * "newPackage(...,Version=>...)" -- see newPackage, -- the
    preamble of a package

For the programmer
==================

The object Version, is a symbol.

Certification -- an optional argument
*************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Certification:
=====================================================

  * "newPackage(...,Certification=>...)" -- see newPackage,
    -- the preamble of a package

For the programmer
==================

The object Certification, is a symbol.

UseCachedExampleOutput -- an optional argument
**********************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named UseCachedExampleOutput:
==============================================================

  * "newPackage(...,UseCachedExampleOutput=>...)" -- see newPackage,
    -- the preamble of a package

For the programmer
==================

The object UseCachedExampleOutput, is a
symbol.

OptionalComponentsPresent -- an optional argument
*************************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named OptionalComponentsPresent:
=================================================================

  * "newPackage(...,OptionalComponentsPresent=>...)" -- see newPackage,
    -- the preamble of a package

For the programmer
==================

The object OptionalComponentsPresent, is a
symbol.

InfoDirSection -- an optional argument
**************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named InfoDirSection:
======================================================

  * "newPackage(...,InfoDirSection=>...)" -- see newPackage,
    -- the preamble of a package

For the programmer
==================

The object InfoDirSection, is a symbol.

PackageImports -- an optional argument
**************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named PackageImports:
======================================================

  * "newPackage(...,PackageImports=>...)" -- see newPackage,
    -- the preamble of a package

For the programmer
==================

The object PackageImports, is a symbol.

Authors -- an optional argument
*******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Authors:
===============================================

  * "newPackage(...,Authors=>...)" -- see newPackage, -- the
    preamble of a package

For the programmer
==================

The object Authors, is a symbol.

Keywords -- an optional argument
********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Keywords:
================================================

  * "newPackage(...,Keywords=>...)" -- see newPackage, -- the
    preamble of a package

For the programmer
==================

The object Keywords, is a symbol.

Date -- an optional argument
****************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Date:
============================================

  * "newPackage(...,Date=>...)" -- see newPackage, -- the
    preamble of a package

For the programmer
==================

The object Date, is a symbol.

AuxiliaryFiles -- an optional argument
**************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named AuxiliaryFiles:
======================================================

  * "newPackage(...,AuxiliaryFiles=>...)" -- see newPackage,
    -- the preamble of a package

For the programmer
==================

The object AuxiliaryFiles, is a symbol.

First -- an optional argument
*****************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named First:
=============================================

  * "minors(...,First=>...)" -- see minors(ZZ,Matrix),
    -- ideal generated by minors

For the programmer
==================

The object First, is a symbol.

Options -- an optional argument
*******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Options:
===============================================

  * "method(...,Options=>...)" -- see method, -- make a new
    method function

For the programmer
==================

The object Options, is a symbol.

Binary -- an optional argument
******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Binary:
==============================================

  * "method(...,Binary=>...)" -- see method, -- make a new method
    function

For the programmer
==================

The object Binary, is a symbol.

KeepZeroes -- an optional argument
**********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named KeepZeroes:
==================================================

  * "smithNormalForm(...,KeepZeroes=>...)" -- see
    smithNormalForm(Matrix), -- smith normal form
    for a matrix over ZZ or a PID

For the programmer
==================

The object KeepZeroes, is a symbol.

Alignment -- an optional argument
*********************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Alignment:
=================================================

  * "netList(...,Alignment=>...)" -- see netList(VisibleList),
    -- a table of boxes

For the programmer
==================

The object Alignment, is a symbol.

VerticalSpace -- an optional argument
*************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named VerticalSpace:
=====================================================

  * "netList(...,VerticalSpace=>...)" -- see netList(VisibleList),
    -- a table of boxes

For the programmer
==================

The object VerticalSpace, is a symbol.

Boxes -- an optional argument
*****************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Boxes:
=============================================

  * "netList(...,Boxes=>...)" -- see netList(VisibleList),
    -- a table of boxes

For the programmer
==================

The object Boxes, is a symbol.

BaseRow -- an optional argument
*******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named BaseRow:
===============================================

  * "netList(...,BaseRow=>...)" -- see netList(VisibleList),
    -- a table of boxes

For the programmer
==================

The object BaseRow, is a symbol.

HorizontalSpace -- an optional argument
***************************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named HorizontalSpace:
=======================================================

  * "netList(...,HorizontalSpace=>...)" -- see netList(VisibleList),
    -- a table of boxes

For the programmer
==================

The object HorizontalSpace, is a symbol.

Reverse -- an optional argument
*******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Reverse:
===============================================

  * "position(...,Reverse=>...)" -- see position, -- the first
    element of a list satisfying a condition

For the programmer
==================

The object Reverse, is a symbol.

Reduce -- an optional argument
******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Reduce:
==============================================

  * hilbertSeries(...,Reduce=>...)
    -- reduce the Hilbert
    series

For the programmer
==================

The object Reduce, is a symbol.

Result -- an optional argument
******************************

Description
===========

A symbol used as the name of an optional argument.

Functions with optional argument named Result:
==============================================

  * flattenRing(...,Result=>...)
    -- optionally specify which
    output(s) to return (see Description for details)

For the programmer
==================

The object Result, is a symbol.

Left -- value of an optional argument
*************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Left, is a symbol.

Prune -- value of an optional argument
**************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Prune, is a symbol.

Binomial -- value of an optional argument
*****************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Binomial, is a symbol.

Test -- value of an optional argument
*************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Test, is a symbol.

Center -- value of an optional argument
***************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Center, is a symbol.

Right -- value of an optional argument
**************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Right, is a symbol.

Flexible -- value of an optional argument
*****************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Flexible, is a symbol.

Postfix -- value of an optional argument
****************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Postfix, is a symbol.

Maintainer -- value of an optional argument
*******************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Maintainer, is a symbol.

Default -- value of an optional argument
****************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Default, is a symbol.

Torsion -- value of an optional argument
****************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Torsion, is a symbol.

Monomial -- value of an optional argument
*****************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Monomial, is a symbol.

Quotient -- value of an optional argument
*****************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Quotient, is a symbol.

Unmixed -- value of an optional argument
****************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

Functions with optional argument named Unmixed:
===============================================

  * "radical(...,Unmixed=>...)" -- see radical (MinimalPrimes),
    -- the radical of an ideal

For the programmer
==================

The object Unmixed, is a symbol.

Decompose -- value of an optional argument
******************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Decompose, is a symbol.

CompleteIntersection -- value of an optional argument
*****************************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

Functions with optional argument named CompleteIntersection:
============================================================

  * "radical(...,CompleteIntersection=>...)" -- see radical (MinimalPrimes),
    -- the radical of an ideal

For the programmer
==================

The object CompleteIntersection, is a symbol.

Iterate -- value of an optional argument
****************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Iterate, is a symbol.

Bayer -- value of an optional argument
**************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Bayer, is a symbol.

Linear -- value of an optional argument
***************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Linear, is a symbol.

Intersection -- value of an optional argument
*********************************************

Description
===========

A symbol used as the value of an optional argument or strategy, for some
function(s).

For the programmer
==================

The object Intersection, is a symbol.

symmetricAlgebra -- the symmetric algebra of a module
*****************************************************

Description
===========

Synopsis
========

  * Usage:
        symmetricAlgebra M
  * Inputs:
      * M, a module,
  * Outputs:
      * a ring, the symmetric algebra of M
+--------------------------------------------------+
|i1 : R = QQ[a..d];                                |
+--------------------------------------------------+
|i2 : M = image matrix{{a,b,c}}                    |
|                                                  |
|o2 = image | a b c |                              |
|                                                  |
|                             1                    |
|o2 : R-module, submodule of R                     |
+--------------------------------------------------+
|i3 : symmetricAlgebra M                           |
|                                                  |
|                       R[p ..p ]                  |
|                          0   2                   |
|o3 = ---------------------------------------------|
|     (- b*p  + a*p , - c*p  + b*p , - c*p  + a*p )|
|           0      1       1      2       0      2 |
|                                                  |
|o3 : QuotientRing                                 |
+--------------------------------------------------+
|i4 : symmetricAlgebra(R^{1,2,3})                  |
|                                                  |
|o4 = R[p ..p ]                                    |
|        0   2                                     |
|                                                  |
|o4 : PolynomialRing                               |
+--------------------------------------------------+

Most of the optional arguments for monoids (see Ring Array,
or monoid) are available here as well, as in the following
example.  They apply to the variables that correspond to the generators of the
module.

+-------------------------------------------------------------------+
|i5 : A = symmetricAlgebra(M, Variables=>{x,y,z})                   |
|                                                                   |
|o5 = A                                                             |
|                                                                   |
|o5 : QuotientRing                                                  |
+-------------------------------------------------------------------+
|i6 : describe A                                                    |
|                                                                   |
|                     R[x..z]                                       |
|o6 = ---------------------------------------                       |
|     (- b*x + a*y, - c*y + b*z, - c*x + a*z)                       |
+-------------------------------------------------------------------+
|i7 : B = symmetricAlgebra(M, VariableBaseName=>G, MonomialSize=>16)|
|                                                                   |
|o7 = B                                                             |
|                                                                   |
|o7 : QuotientRing                                                  |
+-------------------------------------------------------------------+
|i8 : describe B                                                    |
|                                                                   |
|                       R[G ..G ]                                   |
|                          0   2                                    |
|o8 = ---------------------------------------------                 |
|     (- b*G  + a*G , - c*G  + b*G , - c*G  + a*G )                 |
|           0      1       1      2       0      2                  |
+-------------------------------------------------------------------+
|i9 : symmetricAlgebra(M, Degrees=> {3:1})                          |
|                                                                   |
|                       R[p ..p ]                                   |
|                          0   2                                    |
|o9 = ---------------------------------------------                 |
|     (- b*p  + a*p , - c*p  + b*p , - c*p  + a*p )                 |
|           0      1       1      2       0      2                  |
|                                                                   |
|o9 : QuotientRing                                                  |
+-------------------------------------------------------------------+

Synopsis
========

  * Usage:
        symmetricAlgebra f
  * Inputs:
      * f, a matrix,
  * Outputs:
      * a ring map, the map between symmetric algebras induced
        by f
+------------------------------------------------------------------+
|i10 : symmetricAlgebra vars R                                     |
|                                                                  |
|o10 = map (R[p ], R[p ..p ], {a*p , b*p , c*p , d*p , a, b, c, d})|
|              0      0   3       0     0     0     0              |
|                                                                  |
|o10 : RingMap R[p ] <-- R[p ..p ]                                 |
|                 0         0   3                                  |
+------------------------------------------------------------------+

Synopsis
========

  * Usage:
        symmetricAlgebra(A,B,f)
  * Inputs:
      * A, a ring, the symmetric algebra of the target of f,
        previously computed.  Optional.
      * B, a ring, the symmetric algebra of the source of f,
        previously computed.  Optional.
      * f, a matrix,
  * Outputs:
      * a ring map, the map between the specified symmetric
        algebras induced by f

This form of functoriality is needed, because various options are available
when computing symmetric algebras.

For a linear map that is an isomorphism, and is known to be so, e.g., by having
had its inverse computed, the inverse of the corresponding map between
symmetric algebras is precomputed and made available.

+------------------------------------------------------------------+
|i11 : symmetricAlgebra vars R                                     |
|                                                                  |
|o11 = map (R[p ], R[p ..p ], {a*p , b*p , c*p , d*p , a, b, c, d})|
|              0      0   3       0     0     0     0              |
|                                                                  |
|o11 : RingMap R[p ] <-- R[p ..p ]                                 |
|                 0         0   3                                  |
+------------------------------------------------------------------+
|i12 : p = symmetricAlgebra(A,B,id_M)                              |
|                                                                  |
|o12 = map (A, B, {x, y, z, a, b, c, d})                           |
|                                                                  |
|o12 : RingMap A <-- B                                             |
+------------------------------------------------------------------+
|i13 : p^-1                                                        |
|                                                                  |
|o13 = map (B, A, {G , G , G , a, b, c, d})                        |
|                   0   1   2                                      |
|                                                                  |
|o13 : RingMap B <-- A                                             |
+------------------------------------------------------------------+
|i14 : p * p^-1 === id_A                                           |
|                                                                  |
|o14 = true                                                        |
+------------------------------------------------------------------+
|i15 : p^-1 * p === id_B                                           |
|                                                                  |
|o15 = true                                                        |
+------------------------------------------------------------------+

Ways to use symmetricAlgebra:
=============================

  * "symmetricAlgebra(Matrix)"
  * "symmetricAlgebra(Module)"
  * "symmetricAlgebra(Nothing,Nothing,Matrix)"
  * "symmetricAlgebra(Nothing,Ring,Matrix)"
  * "symmetricAlgebra(Ring,Nothing,Matrix)"
  * "symmetricAlgebra(Ring,Ring,Matrix)"

For the programmer
==================

The object symmetricAlgebra, is a method function with options.

symmetricPower -- symmetric power
*********************************

Synopsis
========

  * Usage:
        symmetricPower(i,f)
  * Inputs:
      * i, an integer,
      * M, a matrix, or a module,
  * Outputs:
      * a matrix, or a module, the $i$-th
        symmetric power of the matrix or module $f$

Description
===========

There is currently one restriction: if $f$ is a matrix, then it must have only
one row, and be a map of free modules, as in this example.

+--------------------------------------+
|i1 : R = ZZ/101[a..d]                 |
|                                      |
|o1 = R                                |
|                                      |
|o1 : PolynomialRing                   |
+--------------------------------------+
|i2 : symmetricPower(2,vars R)         |
|                                      |
|o2 = | a2 ab ac ad b2 bc bd c2 cd d2 ||
|                                      |
|             1      10                |
|o2 : Matrix R  <-- R                  |
+--------------------------------------+

If G --> F --> M --> 0 is a presentation for the module M = coker(f:G-->F),
then symmetricPower(i,f) is the cokernel of the map symmetricPower(i-1,F) ** G
--> symmetricPower(i,F).

+-----------------------------------+
|i3 : R = ZZ/101[a,b]               |
|                                   |
|o3 = R                             |
|                                   |
|o3 : PolynomialRing                |
+-----------------------------------+
|i4 : symmetricPower(2,image vars R)|
|                                   |
|o4 = cokernel {2} | -b 0  |        |
|              {2} | a  -b |        |
|              {2} | 0  a  |        |
|                                   |
|                            3      |
|o4 : R-module, quotient of R       |
+-----------------------------------+

See also
========

  * exteriorPower -- exterior power
  * basis -- basis or generating set of all or part of a ring,
    ideal or module

Ways to use symmetricPower:
===========================

  * "symmetricPower(ZZ,Matrix)"
  * "symmetricPower(ZZ,Module)"
  * symmetricPower(ZZ,CoherentSheaf) (missing documentation)

For the programmer
==================

The object symmetricPower, is a method function.

synonym -- synonym for members of a class
*****************************************

Synopsis
========

  * Usage:
        synonym X
  * Inputs:
      * X, a type,
  * Outputs:
      * a string, a synonym for members of the class X

Description
===========

A synonym can be installed with the assignment statement X.synonym=t.  The
synonym is used by ofClass.
+--------------------------------------------+
|i1 : synonym ZZ                             |
|                                            |
|o1 = integer                                |
+--------------------------------------------+
|i2 : Stack = new Type of HashTable          |
|                                            |
|o2 = Stack                                  |
|                                            |
|o2 : Type                                   |
+--------------------------------------------+
|i3 : synonym Stack                          |
|                                            |
|o3 = object of class Stack                  |
+--------------------------------------------+
|i4 : Stack.synonym = "Deligne-Mumford stack"|
|                                            |
|o4 = Deligne-Mumford stack                  |
+--------------------------------------------+
|i5 : ofClass Stack                          |
|                                            |
|o5 = a "Deligne-Mumford stack"              |
+--------------------------------------------+

For the programmer
==================

The object synonym, is a function closure.

syz -- the syzygy matrix
************************

Ways to use syz:
================

  * syz(GroebnerBasis) -- retrieve the syzygy
    matrix
  * syz(Matrix) -- compute the syzygy matrix

For the programmer
==================

The object syz, is a method function with options.

syz(GroebnerBasis) -- retrieve the syzygy matrix
************************************************

Synopsis
========

  * Function: syz,
  * Usage:
        syz G
  * Inputs:
      * G, the Gröbner basis of a matrix h
  * Optional inputs,:
      * Algorithm, => ..., default value Inhomogeneous,
        compute the syzygy matrix
      * BasisElementLimit, => ..., default value
        infinity, compute the syzygy matrix
      * DegreeLimit, => ..., default value {}, compute
        the syzygy matrix
      * GBDegrees, => ..., default value null, compute
        the syzygy matrix
      * HardDegreeLimit, => ..., default value null,
        compute the syzygy matrix
      * MaxReductionCount, => ..., default value 10,
        compute the syzygy matrix
      * PairLimit, => ..., default value infinity,
        compute the syzygy matrix
      * StopBeforeComputation, => ..., default value
        false, compute the syzygy matrix
      * Strategy, => ..., default value {}, compute the
        syzygy matrix
      * SyzygyLimit, => ..., default value infinity,
        compute the syzygy matrix
      * SyzygyRows, => ..., default value infinity,
        compute the syzygy matrix
  * Outputs:
      * the matrix of syzygies among the columns of h

Description
===========

Warning: the result may be zero if syzygies were not to be retained during the
calculation, or if the computation was not continued to a high enough degree.

The matrix of syzygies is returned without removing non-minimal syzygies.

+----------------------------------------------------+
|i1 : R = QQ[a..g];                                  |
+----------------------------------------------------+
|i2 : I = ideal"ab2-c3,abc-def,ade-bfg"              |
|                                                    |
|               2    3                               |
|o2 = ideal (a*b  - c , a*b*c - d*e*f, a*d*e - b*f*g)|
|                                                    |
|o2 : Ideal of R                                     |
+----------------------------------------------------+
|i3 : G = gb(I, Syzygies=>true);                     |
+----------------------------------------------------+
|i4 : syz G                                          |
|                                                    |
|o4 = {3} | -abc+def 0        -ade+bfg -d2e2f+b2cfg ||
|     {3} | ab2-c3   -ade+bfg 0        c3de-b3fg    ||
|     {3} | 0        abc-def  ab2-c3   -bc4+b2def   ||
|                                                    |
|             3      4                               |
|o4 : Matrix R  <-- R                                |
+----------------------------------------------------+
There appear to be 4 syzygies, but the last one is a combination of the first
three:
+---------------------------------------+
|i5 : syz gens I                        |
|                                       |
|o5 = {3} | -abc+def 0        -ade+bfg ||
|     {3} | ab2-c3   -ade+bfg 0        ||
|     {3} | 0        abc-def  ab2-c3   ||
|                                       |
|             3      3                  |
|o5 : Matrix R  <-- R                   |
+---------------------------------------+
|i6 : mingens image syz G               |
|                                       |
|o6 = {3} | -abc+def 0        -ade+bfg ||
|     {3} | ab2-c3   -ade+bfg 0        ||
|     {3} | 0        abc-def  ab2-c3   ||
|                                       |
|             3      3                  |
|o6 : Matrix R  <-- R                   |
+---------------------------------------+

See also
========

  * gb -- compute a Gröbner basis
  * mingens -- minimal generator matrix

Ways to use this method:
========================

  * syz(GroebnerBasis) -- retrieve the syzygy
    matrix

syz(Matrix) -- compute the syzygy matrix
****************************************

Synopsis
========

  * Function: syz,
  * Usage:
        syz h
  * Inputs:
      * h, a matrix
  * Optional inputs,:
      * Algorithm => ..., default value Inhomogeneous, see
        gb(...,Algorithm=>...),
      * BasisElementLimit => ..., default value infinity, see
        gb(...,BasisElementLimit=>...),
      * DegreeLimit => ..., default value {}, see
        gb(...,DegreeLimit=>...),
      * GBDegrees => ..., default value null, see gb(...,GBDegrees=>...),
      * HardDegreeLimit => ..., default value null, see
        gb(...,HardDegreeLimit=>...),
      * MaxReductionCount => an integer, default value 10, the
        maximum number of reductions of an S-pair done before requeueing it, if
        the Inhomogeneous algorithm is in use
      * PairLimit => ..., default value infinity, see
        gb(...,PairLimit=>...),
      * StopBeforeComputation => ..., default value false, see
        gb(...,StopBeforeComputation=>...),
      * Strategy => ..., default value {}, see gb(...,Strategy=>...),
      * SyzygyLimit => ..., default value infinity, see
        gb(...,SyzygyLimit=>...),
      * SyzygyRows => ..., default value infinity, see
        gb(...,SyzygyRows=>...),
  * Outputs:
      * a matrix, the matrix of minimal or trimmed generators
        for the syzygies among the columns of h

Description
===========

+----------------------------------------------------+
|i1 : R = QQ[a..g];                                  |
+----------------------------------------------------+
|i2 : I = ideal"ab2-c3,abc-cef,ade-cfg"              |
|                                                    |
|               2    3                               |
|o2 = ideal (a*b  - c , a*b*c - c*e*f, a*d*e - c*f*g)|
|                                                    |
|o2 : Ideal of R                                     |
+----------------------------------------------------+
|i3 : syz gens I                                     |
|                                                    |
|o3 = {3} | -abc+cef 0        -ade+cfg de2f-bcfg  |  |
|     {3} | ab2-c3   -ade+cfg 0        -c2de+b2fg |  |
|     {3} | 0        abc-cef  ab2-c3   bc3-b2ef   |  |
|                                                    |
|             3      4                               |
|o3 : Matrix R  <-- R                                |
+----------------------------------------------------+

See also
========

  * gb -- compute a Gröbner basis

Ways to use this method:
========================

  * syz(Matrix) -- compute the syzygy matrix

syzygyScheme -- construct a syzygy scheme
*****************************************

Description
===========

syzygyScheme(C,i,v) -- produce the syzygy scheme from a map v : R^j ---> C_i
which selects some syzygies from a resolution C.

For the programmer
==================

The object syzygyScheme, is a function closure.

Table -- the class of all table expressions
*******************************************

Description
===========

Table -- a type of Expression, representing a table, i.e., a
list of lists of the same length.

+-------------------------------+
|i1 : Table {{a,b,c},{a,bb,ccc}}|
|                               |
|o1 = a   b   c                 |
|                               |
|     a  bb  ccc                |
|                               |
|o1 : Expression of class Table |
+-------------------------------+
|i2 : value oo                  |
|                               |
|o2 = {{a, b, c}, {a, bb, ccc}} |
|                               |
|o2 : List                      |
+-------------------------------+

See also
========

  * MatrixExpression -- the class of all matrix
    expressions

For the programmer
==================

The object Table, is a header type, with
ancestor classes Expression, < BasicList <
Thing.

table -- make a table from a binary function
********************************************

Synopsis
========

  * Usage:
        table(a, b, f)
        table(m, n, f)
  * Inputs:
      * a, a list,
      * b, a list,
      * m, an integer,
      * n, an integer,
      * f, a function f(i,j) of two variables
  * Outputs:
      * T, a table, or list of lists, where $T_{ij}$ is the value of $f(a_i,
        b_j)$, OR, if using integer arguments $m$ and $n$, $T_{ij}=f(i,j)$ for
        $0\le i < m, 0\le j < n$

Description
===========

The command table(m, n, f) is equivalent to table(0..(m-1), 0..(n-1), f).

+-----------------------------------------------------------------------------+
|i1 : t1 = table({1,3,5,7}, {0,1,2,4}, (i,j) -> i^j)                          |
|                                                                             |
|o1 = {{1, 1, 1, 1}, {1, 3, 9, 81}, {1, 5, 25, 625}, {1, 7, 49, 2401}}        |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+
|i2 : t2 = table(5, 5, (i,j) -> i+j)                                          |
|                                                                             |
|o2 = {{0, 1, 2, 3, 4}, {1, 2, 3, 4, 5}, {2, 3, 4, 5, 6}, {3, 4, 5, 6, 7}, {4,|
|     ------------------------------------------------------------------------|
|     5, 6, 7, 8}}                                                            |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

Tables can be displayed nicely using netList.

+------------------+
|i3 : netList t1   |
|                  |
|     +-+-+--+----+|
|o3 = |1|1|1 |1   ||
|     +-+-+--+----+|
|     |1|3|9 |81  ||
|     +-+-+--+----+|
|     |1|5|25|625 ||
|     +-+-+--+----+|
|     |1|7|49|2401||
|     +-+-+--+----+|
+------------------+

See also
========

  * applyTable -- apply a function to each element of a
    table
  * isTable -- whether something is a list of lists of equal
    length
  * subtable -- extract a subtable from a table
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

For the programmer
==================

The object table, is a function closure.

take -- Take some elements from a list or sequence.
***************************************************

Synopsis
========

  * Usage:
        take(L, i)
        take(L, {j,k})
        take(x, i)
  * Inputs:
      * L, a basic list,
      * x, a thing,
      * i, an integer,
      * j, an integer,
      * k, an integer,
  * Outputs:
      * L2, a basic list, the list or sequence containing the
        first i elements of L, (if i positive), or the last i elements of L (if
        i negative), or, if given the pair j,k, the list or sequence containing
        the elements of L with indices j through k

Description
===========

+---------------------------------+
|i1 : take({a,b,c,d,e,f,g}, 3)    |
|                                 |
|o1 = {a, b, c}                   |
|                                 |
|o1 : List                        |
+---------------------------------+
|i2 : take({a,b,c,d,e,f,g}, -3)   |
|                                 |
|o2 = {e, f, g}                   |
|                                 |
|o2 : List                        |
+---------------------------------+
|i3 : take({a,b,c,d,e,f,g}, {1,3})|
|                                 |
|o3 = {b, c, d}                   |
|                                 |
|o3 : List                        |
+---------------------------------+
|i4 : take({a,b,c,d,e,f,g}, {2,2})|
|                                 |
|o4 = {c}                         |
|                                 |
|o4 : List                        |
+---------------------------------+

The pair $\{j,k\}$ must be given with both entries non-negative, and $j\le k$.
Otherwise an empty list is returned.

+----------------------------------+
|i5 : take({a,b,c,d,e,f,g}, {3,1}) |
|                                  |
|o5 = {}                           |
|                                  |
|o5 : List                         |
+----------------------------------+
|i6 : take({a,b,c,d,e,f,g}, {4,-1})|
|                                  |
|o6 = {}                           |
|                                  |
|o6 : List                         |
+----------------------------------+

If x is any object belonging to a class with the iterator,
method installed, then a list containing the first $i$ (or the $(j+1)$th
through $(k+1)$th) objects returned when next, is called on the
output of iterator x is returned.  If fewer than $i$ (or $k+1$) objects are
returned before the StopIteration, symbol is encountered,
then the list will have shorter than expected length.

+--------------------------------------------+
|i7 : take("Hello, world!", 5)               |
|                                            |
|o7 = {H, e, l, l, o}                        |
|                                            |
|o7 : List                                   |
+--------------------------------------------+
|i8 : take("Hello, world!", 20)              |
|                                            |
|o8 = {H, e, l, l, o, ,,  , w, o, r, l, d, !}|
|                                            |
|o8 : List                                   |
+--------------------------------------------+
|i9 : take("Hello, world!", {7, 11})         |
|                                            |
|o9 = {w, o, r, l, d}                        |
|                                            |
|o9 : List                                   |
+--------------------------------------------+

See also
========

  * drop -- drop some elements from a list or sequence.
  * select -- select from a list, hash table, or string
  * position -- the first element of a list satisfying a
    condition
  * positions -- which elements of a list satisfy a condition
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use take:
=================

  * "take(BasicList,List)"
  * "take(BasicList,ZZ)"
  * "take(Thing,List)"
  * "take(Thing,ZZ)"

For the programmer
==================

The object take, is a compiled function.

Tally -- the class of all tally results
***************************************

Description
===========

Tally -- a class designed to hold tally results, i.e., multisets.

See also
========

  * VirtualTally

Types of tally:
===============

  * Set -- the class of all sets

Functions and methods returning a tally:
========================================

  * "tally(String)" -- see tally, -- tally the elements of a list,
    sequence, array, or string
  * "tally(VisibleList)" -- see tally, -- tally the elements of a
    list, sequence, array, or string
  * Tally + Tally -- union of tallies
  * Tally - Tally -- difference of tallies

Methods that use a tally:
=========================

  * - Tally (missing documentation)
  * "commonest(Tally)" -- see commonest, -- the most common
    elements of a list or tally
  * "elements(Tally)" -- see elements, -- list of elements
  * Number * Tally (missing documentation)
  * RingElement * Tally (missing documentation)

For the programmer
==================

The object Tally, is a type, with ancestor classes
VirtualTally < HashTable < Thing.

tally -- tally the elements of a list, sequence, array, or string
*****************************************************************

Synopsis
========

  * Usage:
        y = tally x
  * Inputs:
      * x, a visible list, or a string,
  * Outputs:
      * y, a tally,

Description
===========

It produces a hash table (multiset) y which tallies the frequencies of the
occurrences of items in the list or string x, i.e., y_i is the number of times
i appears in x, or is 0 if i doesn't appear in the list or string.

+--------------------------------------------------+
|i1 : y = tally {1,2,3,a,b,1,2,a,1,2,{a,b},{a,b},a}|
|                                                  |
|o1 = Tally{{a, b} => 2}                           |
|           1 => 3                                 |
|           2 => 3                                 |
|           3 => 1                                 |
|           a => 3                                 |
|           b => 1                                 |
|                                                  |
|o1 : Tally                                        |
+--------------------------------------------------+
|i2 : y_2                                          |
|                                                  |
|o2 = 3                                            |
+--------------------------------------------------+
|i3 : y_5                                          |
|                                                  |
|o3 = 0                                            |
+--------------------------------------------------+
|i4 : y_{a,b}                                      |
|                                                  |
|o4 = 2                                            |
+--------------------------------------------------+
|i5 : tally "Hello, world!"                        |
|                                                  |
|o5 = Tally{  => 1}                                |
|           ! => 1                                 |
|           , => 1                                 |
|           d => 1                                 |
|           e => 1                                 |
|           H => 1                                 |
|           l => 3                                 |
|           o => 2                                 |
|           r => 1                                 |
|           w => 1                                 |
|                                                  |
|o5 : Tally                                        |
+--------------------------------------------------+

See also
========

  * Tally -- the class of all tally results

Ways to use tally:
==================

  * "tally(String)"
  * "tally(VisibleList)"

For the programmer
==================

The object tally, is a compiled function.

Tally + Tally -- union of tallies
*********************************

Synopsis
========

  * Operator: +,

Description
===========

x + y -- produces the union of two tallies.

One of the arguments may be a Set.

+----------------------------+
|i1 : x = tally {a,a,a,b,b,c}|
|                            |
|o1 = Tally{a => 3}          |
|           b => 2           |
|           c => 1           |
|                            |
|o1 : Tally                  |
+----------------------------+
|i2 : y = tally {b,c,c,d,d,d}|
|                            |
|o2 = Tally{b => 1}          |
|           c => 2           |
|           d => 3           |
|                            |
|o2 : Tally                  |
+----------------------------+
|i3 : x + y                  |
|                            |
|o3 = Tally{a => 3}          |
|           b => 3           |
|           c => 3           |
|           d => 3           |
|                            |
|o3 : Tally                  |
+----------------------------+

See also
========

  * Tally -- the class of all tally results
  * tally -- tally the elements of a list, sequence, array, or
    string

Ways to use this method:
========================

  * Tally + Tally -- union of tallies

Tally - Tally -- difference of tallies
**************************************

Synopsis
========

  * Operator: -,
  * Usage:
        x - y
  * Inputs:
      * x
      * y
  * Outputs:
      * the difference of the two tallies

Description
===========

The count associated to an item i in the result is the difference of the counts
in x and in y if it's positive, otherwise, zero.
+------------------------------------+
|i1 : tally {a,a,b,c} - tally {c,d,d}|
|                                    |
|o1 = Tally{a => 2}                  |
|           b => 1                   |
|                                    |
|o1 : Tally                          |
+------------------------------------+

See also
========

  * Tally -- the class of all tally results

Ways to use this method:
========================

  * Tally - Tally -- difference of tallies

tan -- compute the tangent
**************************

Synopsis
========

  * Usage:
        tan x
        tan I
  * Inputs:
      * x, a real number,
      * I, a real interval,
  * Outputs:
      * a real number, the tangent of x
      * a real interval, an interval containing the tangents of the
        points of I

Description
===========

+-------------------------+
|i1 : tan 1               |
|                         |
|o1 = 1.557407724654902   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

Ways to use tan:
================

  * "tan(CC)"
  * "tan(RR)"
  * "tan(RRi)"
  * tan(RingElement) (missing documentation)

For the programmer
==================

The object tan, is a method function.

tanh -- compute the hyperbolic tangent
**************************************

Synopsis
========

  * Usage:
        tanh x
        tanh I
  * Inputs:
      * x, a real number,
      * I, a real interval,
  * Outputs:
      * a real number, the hyperbolic tangent of x
      * a real interval, an interval containing the hyerbolic
        tangents of the points of I

Ways to use tanh:
=================

  * "tanh(CC)"
  * "tanh(RR)"
  * "tanh(RRi)"
  * tanh(RingElement) (missing documentation)

For the programmer
==================

The object tanh, is a method function.

target -- target of a map
*************************

Description
===========

This command returns the target of a morphism or Gröbner basis.

See also
========

  * source -- source of a map

Ways to use target:
===================

  * target(ChainComplexMap) --  find the
    target of a map of chain complexes
  * target(GradedModuleMap) -- find the
    target of a map of graded modules
  * target(GroebnerBasis) -- find target of a
    Gröbner basis
  * target(Matrix) -- find the target module of
    matrix
  * target(RingMap) -- find the target ring for a
    map of rings
  * target(SheafMap) (missing documentation)

For the programmer
==================

The object target, is a method function.

target(ChainComplexMap) --  find the target of a map of chain complexes
***********************************************************************

Synopsis
========

  * Function: target,
  * Usage:
        target f
  * Inputs:
      * f, a chain complex map,
  * Outputs:
      * the target chain complex of f

Description
===========

In the example below, we have a map between two modules and extend it to a map
between projective resolutions of the two modules. Then target gives the target
of the map of chain complexes.
+----------------------------------+
|i1 : R = ZZ[x,y,z];               |
+----------------------------------+
|i2 : M = R^1/(x,y,z);             |
+----------------------------------+
|i3 : N = R^1/(x^2,y^2,x*y*z,z^2); |
+----------------------------------+
|i4 : g = map(N,M,x*y);            |
|                                  |
|o4 : Matrix N <-- M               |
+----------------------------------+
|i5 : f = res g;                   |
+----------------------------------+
|i6 : target f                     |
|                                  |
|      1      4      6      3      |
|o6 = R  <-- R  <-- R  <-- R  <-- 0|
|                                  |
|     0      1      2      3      4|
|                                  |
|o6 : ChainComplex                 |
+----------------------------------+
(That was an expensive way of resolving N.)

Ways to use this method:
========================

  * target(ChainComplexMap) --  find the
    target of a map of chain complexes

target(GradedModuleMap) -- find the target of a map of graded modules
*********************************************************************

Synopsis
========

  * Function: target,
  * Usage:
        target f
  * Inputs:
      * f
  * Outputs:
      * a graded module,

Ways to use this method:
========================

  * target(GradedModuleMap) -- find the
    target of a map of graded modules

target(GroebnerBasis) -- find target of a Gröbner basis
*******************************************************

Synopsis
========

  * Function: target,
  * Usage:
        target g
  * Inputs:
      * g, a Gröbner basis,
  * Outputs:
      * the target of the matrix given by the generators of the Gröbner basis

Description
===========

+-------------------------------------+
|i1 : R = ZZ/10007[x,y,z];            |
+-------------------------------------+
|i2 : g = gb ideal(x^2, x*y-z^2, z^5);|
+-------------------------------------+
|i3 : target g                        |
|                                     |
|      1                              |
|o3 = R                               |
|                                     |
|o3 : R-module, free                  |
+-------------------------------------+

Ways to use this method:
========================

  * target(GroebnerBasis) -- find target of a
    Gröbner basis

target(Matrix) -- find the target module of matrix
**************************************************

Synopsis
========

  * Function: target,
  * Usage:
        target f
  * Inputs:
      * f, a matrix,
  * Outputs:
      * the target module of f

Description
===========

+---------------------------------+
|i1 : R = ZZ[x,y,z];              |
+---------------------------------+
|i2 : M = R^1/(x,y,z);            |
+---------------------------------+
|i3 : N = R^1/(x^2,y^2,x*y*z,z^2);|
+---------------------------------+
|i4 : g = map(N,M,x*y);           |
|                                 |
|o4 : Matrix N <-- M              |
+---------------------------------+
|i5 : target g                    |
|                                 |
|o5 = cokernel | x2 y2 xyz z2 |   |
|                                 |
|                            1    |
|o5 : R-module, quotient of R     |
+---------------------------------+

Ways to use this method:
========================

  * target(Matrix) -- find the target module of
    matrix

target(RingMap) -- find the target ring for a map of rings
**********************************************************

Synopsis
========

  * Function: target,
  * Usage:
        target f
  * Inputs:
      * f
  * Outputs:
      * the target ring of the map

Description
===========

+-------------------------------+
|i1 : S = ZZ/10007[x, y, z];    |
+-------------------------------+
|i2 : R = ZZ/10007[t];          |
+-------------------------------+
|i3 : f = map(R,S,{t^3,t^4,t^5})|
|                               |
|                  3   4   5    |
|o3 = map (R, S, {t , t , t })  |
|                               |
|o3 : RingMap R <-- S           |
+-------------------------------+
|i4 : target f                  |
|                               |
|o4 = R                         |
|                               |
|o4 : PolynomialRing            |
+-------------------------------+

Ways to use this method:
========================

  * target(RingMap) -- find the target ring for a
    map of rings

tensor -- tensor product
************************

Description
===========

This function calculates the tensor product of a list or sequence of compatible
objects.

This method is declared as a MethodFunctionBinary,
so for two or more argument the product is computed iteratively from the binary
tensor products, working from left to right. For two arguments, this is the
same as A ** B except that options are allowed.

+-----------------------------+
|i1 : tensor(ZZ^2, ZZ^3, ZZ^4)|
|                             |
|       24                    |
|o1 = ZZ                      |
|                             |
|o1 : ZZ-module, free         |
+-----------------------------+

See also
========

  * ** -- a binary operator, usually used for tensor product or
    Cartesian product

Ways to use tensor:
===================

  * "tensor(List)"
  * "tensor(Sequence)"
  * tensor(CoherentSheaf,CoherentSheaf) (missing documentation)
  * tensor(Matrix,Matrix) -- tensor product
  * tensor(Matrix,Module) -- tensor product
  * "tensor(Module,Matrix)" -- see tensor(Matrix,Module),
    -- tensor product
  * tensor(Module,Module) -- tensor product
    of modules
  * tensor(Monoid,Monoid) -- tensor product
    of monoids
  * "tensor(Ring,Ring)" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * tensor(RingMap,Matrix) -- tensor
    product via a ring map
  * "tensor(RingMap,Module)" -- see tensor(RingMap,Matrix),
    -- tensor product via a ring map
  * tensor(SheafMap,SheafMap) (missing documentation)

For the programmer
==================

The object tensor, is an associative binary method function.

tensor(Matrix,Matrix) -- tensor product
***************************************

Synopsis
========

  * Function: tensor,
  * Usage:
        f ** g
        tensor(f, g)
  * Inputs:
      * f, a matrix,
      * g, a matrix,
  * Outputs:
      * a matrix, the tensor product of maps $f$ and $g$

Description
===========

Other names for the tensor product include: the outer product, or the Kronecker
product of two matrices.

+---------------------------------+
|i1 : R = ZZ[a..d];               |
+---------------------------------+
|i2 : f = matrix {{a,b}}          |
|                                 |
|o2 = | a b |                     |
|                                 |
|             1      2            |
|o2 : Matrix R  <-- R             |
+---------------------------------+
|i3 : g = transpose matrix {{c,d}}|
|                                 |
|o3 = {-1} | c |                  |
|     {-1} | d |                  |
|                                 |
|             2      1            |
|o3 : Matrix R  <-- R             |
+---------------------------------+
|i4 : f ** g                      |
|                                 |
|o4 = {-1} | ac bc |              |
|     {-1} | ad bd |              |
|                                 |
|             2      2            |
|o4 : Matrix R  <-- R             |
+---------------------------------+

See also
========

  * flip -- isomorphism map of commutativity of tensor product
  * tensor(Module,Module) -- tensor product
    of modules
  * tensor(Matrix,Module) -- tensor product

Ways to use this method:
========================

  * tensor(Matrix,Matrix) -- tensor product

tensor(Matrix,Module) -- tensor product
***************************************

Synopsis
========

  * Function: tensor,
  * Usage:
        f ** M
        M ** f
        tensor(f, M)
        tensor(M, f)
  * Inputs:
      * f, a matrix,
      * M, a module,
  * Outputs:
      * a matrix, formed by tensoring $f$ with the identity map
        of $M$

Description
===========

+---------------------+
|i1 : R = ZZ/101[x,y];|
+---------------------+
|i2 : R^2 ** vars R   |
|                     |
|o2 = | x y 0 0 |     |
|     | 0 0 x y |     |
|                     |
|             2      4|
|o2 : Matrix R  <-- R |
+---------------------+
|i3 : (vars R) ** R^2 |
|                     |
|o3 = | x 0 y 0 |     |
|     | 0 x 0 y |     |
|                     |
|             2      4|
|o3 : Matrix R  <-- R |
+---------------------+

When $N$ is a free module of rank 1 the net effect of the operation is to shift
the degrees of $f$.

+---------------------------------+
|i4 : R = ZZ/101[t];              |
+---------------------------------+
|i5 : f = matrix {{t}}            |
|                                 |
|o5 = | t |                       |
|                                 |
|             1      1            |
|o5 : Matrix R  <-- R             |
+---------------------------------+
|i6 : degrees source f            |
|                                 |
|o6 = {{1}}                       |
|                                 |
|o6 : List                        |
+---------------------------------+
|i7 : degrees source (f ** R^{-3})|
|                                 |
|o7 = {{4}}                       |
|                                 |
|o7 : List                        |
+---------------------------------+

See also
========

  * tensor(Module,Module) -- tensor product
    of modules
  * tensor(Matrix,Matrix) -- tensor product

Ways to use this method:
========================

  * tensor(Matrix,Module) -- tensor product
  * "tensor(Module,Matrix)"

tensor(Module,Module) -- tensor product of modules
**************************************************

Synopsis
========

  * Function: tensor,
  * Usage:
        M ** N
        tensor(M, N)
  * Inputs:
      * M, a module,
      * N, a module,
  * Outputs:
      * a module, the tensor product of $M$ and $N$

Description
===========

If $M$ has generators $m_1, $m_2, \dots, $m_r$, and $N$ has generators $n_1,
n_2, \dots, n_s$, then $M \otimes N$ has generators $m_i\otimes n_j$ for
$0<i\leq r$ and $0<j\leq s$.

+---------------------------------+
|i1 : R = ZZ[a..d];               |
+---------------------------------+
|i2 : M = image matrix {{a,b}}    |
|                                 |
|o2 = image | a b |               |
|                                 |
|                             1   |
|o2 : R-module, submodule of R    |
+---------------------------------+
|i3 : N = image matrix {{c,d}}    |
|                                 |
|o3 = image | c d |               |
|                                 |
|                             1   |
|o3 : R-module, submodule of R    |
+---------------------------------+
|i4 : M ** N                      |
|                                 |
|o4 = cokernel {2} | -d 0  -b 0  ||
|              {2} | c  0  0  -b ||
|              {2} | 0  -d a  0  ||
|              {2} | 0  c  0  a  ||
|                                 |
|                            4    |
|o4 : R-module, quotient of R     |
+---------------------------------+
|i5 : N ** M                      |
|                                 |
|o5 = cokernel {2} | -b 0  -d 0  ||
|              {2} | a  0  0  -d ||
|              {2} | 0  -b c  0  ||
|              {2} | 0  a  0  c  ||
|                                 |
|                            4    |
|o5 : R-module, quotient of R     |
+---------------------------------+

Use trim, or minimalPresentation, if a
more compact presentation is desired.

Use flip, to produce the isomorphism $M \otimes N \to N \otimes M$.

To recover the factors from the tensor product, use the function
formation.

See also
========

  * flip -- isomorphism map of commutativity of tensor product
  * tensor(Module,Matrix) -- tensor product
  * tensor(Matrix,Matrix) -- tensor product
  * formation -- recover the methods used to make a module

Ways to use this method:
========================

  * tensor(Module,Module) -- tensor product
    of modules

tensor(Monoid,Monoid) -- tensor product of monoids
**************************************************

Synopsis
========

  * Function: tensor,
  * Usage:
        C = A ** B
        C = tensor(A, B, ...)
  * Inputs:
      * A, a ring, or a monoid,
      * B, a ring, or a monoid,
  * Optional inputs,:
      * DegreeRank => an integer, default value null, see
        monoid(...,DegreeRank=>...),;
      * Degrees => a list, default value null, see
        monoid(...,Degrees=>...),;
      * Inverses => a Boolean value, default value null, see
        monoid(...,Inverses=>...),;
      * Global => a Boolean value, default value true, see
        monoid(...,Global=>...),;
      * Local => a Boolean value, default value false, see
        monoid(...,Local=>...),;
      * MonomialOrder => a list, default value null, see
        monoid(...,MonomialOrder=>...),;
      * MonomialSize => an integer, default value 32, see
        monoid(...,MonomialSize=>...),;
      * Variables => a list, default value null, see
        monoid(...,Variables=>...),;
      * VariableBaseName => a symbol, default value null, see
        monoid(...,VariableBaseName=>...),;
      * Heft => a list, default value null, see
        monoid(...,Heft=>...),;
      * Join => a Boolean value, default value null, overrides
        the corresponding option in A; see monoid(...,Join=>...),;
      * DegreeMap => a Boolean value, default value null,
        overrides the corresponding option in A; see
        monoid(...,DegreeMap=>...),;
      * DegreeLift => a Boolean value, default value null,
        overrides the corresponding option in A; see
        monoid(...,DegreeLift=>...),;
      * SkewCommutative => a Boolean value, default value {},
        ignored by this routine;
      * Weights => a list, default value {}, ignored by this
        routine;
      * WeylAlgebra => a list, default value {}, ignored by this
        routine;
      * Constants (missing documentation) => ..., default value false,
      * DegreeGroup (missing documentation) => ..., default value null,
  * Outputs:
      * C, a ring, or a monoid, tensor product of
        the monoids or rings

Description
===========

This is the same as A ** B except that options are allowed, see Monoid ** Monoid,
and Ring ** Ring.
This method allows many of the options available
for monoids, see monoid, for details. This method essentially
combines the variables of A and B into one monoid or ring.

+-------------------+
|i1 : kk = ZZ/101   |
|                   |
|o1 = kk            |
|                   |
|o1 : QuotientRing  |
+-------------------+
|i2 : A = kk[a,b]   |
|                   |
|o2 = A             |
|                   |
|o2 : PolynomialRing|
+-------------------+
|i3 : B = kk[c,d,e] |
|                   |
|o3 = B             |
|                   |
|o3 : PolynomialRing|
+-------------------+

The simplest version is to simply use **,:

+-----------------------------------------------------------------------------+
|i4 : describe(A**B)                                                          |
|                                                                             |
|o4 = kk[a..e, Degrees => {2:{1}, 3:{0}}, Heft => {2:1}, MonomialOrder =>     |
|                            {0}    {1}                                       |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32}]                                                        |
|{GRevLex => {2:1}  }                                                         |
|{Position => Up    }                                                         |
|{GRevLex => {3:1}  }                                                         |
+-----------------------------------------------------------------------------+

If you wish to change the variable names:

+-----------------------------------------------------------------------------+
|i5 : describe tensor(A, B, VariableBaseName => p)                            |
|                                                                             |
|o5 = kk[p ..p , Degrees => {2:{1}, 3:{0}}, Heft => {2:1}, MonomialOrder =>   |
|         0   4                {0}    {1}                                     |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32}]                                                        |
|{GRevLex => {2:1}  }                                                         |
|{Position => Up    }                                                         |
|{GRevLex => {3:1}  }                                                         |
+-----------------------------------------------------------------------------+
|i6 : describe tensor(A, B, Variables => {a1,a2,b1,b2,b3})                    |
|                                                                             |
|o6 = kk[a1, a2, b1, b2, b3, Degrees => {2:{1}, 3:{0}}, Heft => {2:1},        |
|                                          {0}    {1}                         |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|MonomialOrder => {MonomialSize => 32}]                                       |
|                 {GRevLex => {2:1}  }                                        |
|                 {Position => Up    }                                        |
|                 {GRevLex => {3:1}  }                                        |
+-----------------------------------------------------------------------------+

The tensor product of two singly graded rings is bigraded. Sometimes you want a
singly graded ring. Here is one way to get it:

+-----------------------------------------------------------------------------+
|i7 : describe (C = tensor(A, B,                                              |
|                                                                             |
|o7 = kk[a..e, Degrees => {5:1},                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|DegreeRank => 1, Degrees => {5:1}))                                          |
|                                                                             |
|Heft => {1}, MonomialOrder => {MonomialSize => 32}]                          |
|                              {GRevLex => {2:1}  }                           |
|                              {Position => Up    }                           |
|                              {GRevLex => {3:1}  }                           |
+-----------------------------------------------------------------------------+
|i8 : degreeLength C                                                          |
|                                                                             |
|o8 = 1                                                                       |
+-----------------------------------------------------------------------------+
|i9 : degreesRing C                                                           |
|                                                                             |
|o9 = ZZ[T]                                                                   |
|                                                                             |
|o9 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+

Packing monomials into smaller space is more efficient, but less flexible. The
default is 32 bits, so if you want to pack them into 8 bit exponents, use:

+-----------------------------------------------------------------------------+
|i10 : describe tensor(A, B, MonomialSize => 8)                               |
|                                                                             |
|o10 = kk[a..e, Degrees => {2:{1}, 3:{0}}, Heft => {2:1}, MonomialOrder =>    |
|                             {0}    {1}                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 8 }]                                                        |
|{MonomialSize => 32}                                                         |
|{GRevLex => {2:1}  }                                                         |
|{Position => Up    }                                                         |
|{GRevLex => {3:1}  }                                                         |
+-----------------------------------------------------------------------------+

The default monomial order for tensor products is a product order. Sometimes
other orders are more desirable, e.g. GRevLex, or an elimination order:

+-----------------------------------------------------------------------------+
|i11 : describe (C = tensor(A, B, MonomialOrder => Eliminate numgens A))      |
|                                                                             |
|o11 = kk[a..e, Degrees => {2:{1}, 3:{0}}, Heft => {2:1}, MonomialOrder =>    |
|                             {0}    {1}                                      |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32}]                                                        |
|{Weights => {2:1}  }                                                         |
|{GRevLex => {5:1}  }                                                         |
|{Position => Up    }                                                         |
+-----------------------------------------------------------------------------+
|i12 : describe (C = tensor(A, B, MonomialOrder => GRevLex))                  |
|                                                                             |
|o12 = kk[a..e, Degrees => {2:{1}, 3:{0}}, Heft => {2:1}]                     |
|                             {0}    {1}                                      |
+-----------------------------------------------------------------------------+

If you tensor two skew-commutative rings, (or one skew commutative ring with a
commutative polynomial ring), then all of the skew-commuting variables skew
commute with each other:

+-----------------------------------------------------------------------------+
|i13 : As = kk[a, b, SkewCommutative => true]                                 |
|                                                                             |
|o13 = As                                                                     |
|                                                                             |
|o13 : PolynomialRing, 2 skew commutative variable(s)                         |
+-----------------------------------------------------------------------------+
|i14 : D  = kk[c, d, e, SkewCommutative => true]                              |
|                                                                             |
|o14 = D                                                                      |
|                                                                             |
|o14 : PolynomialRing, 3 skew commutative variable(s)                         |
+-----------------------------------------------------------------------------+
|i15 : E = tensor(As, D)                                                      |
|                                                                             |
|o15 = E                                                                      |
|                                                                             |
|o15 : PolynomialRing, 5 skew commutative variable(s)                         |
+-----------------------------------------------------------------------------+
|i16 : describe E                                                             |
|                                                                             |
|o16 = kk[a..e, Degrees => {2:{1}, 3:{0}}, Heft => {2:1}, MonomialOrder =>    |
|                             {0}    {1}                                      |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|{MonomialSize => 32}, SkewCommutative => {0..4}]                             |
|{GRevLex => {2:1}  }                                                         |
|{Position => Up    }                                                         |
|{GRevLex => {3:1}  }                                                         |
+-----------------------------------------------------------------------------+
|i17 : c * a                                                                  |
|                                                                             |
|o17 = -a*c                                                                   |
|                                                                             |
|o17 : E                                                                      |
+-----------------------------------------------------------------------------+

Similarly, tensoring two Weyl algebras (or one and a polynomial ring) produces
a Weyl algebra with both sets of non-commuting pairs.

+-----------------------------------------------------------------------------+
|i18 : E = kk[x, Dx, WeylAlgebra => {x => Dx}]                                |
|                                                                             |
|o18 = E                                                                      |
|                                                                             |
|o18 : PolynomialRing, 1 differential variable(s)                             |
+-----------------------------------------------------------------------------+
|i19 : tensor(E, E, Variables => {x, Dx, y, Dy})                              |
|                                                                             |
|o19 = kk[x, Dx, y, Dy]                                                       |
|                                                                             |
|o19 : PolynomialRing, 2 differential variable(s)                             |
+-----------------------------------------------------------------------------+
|i20 : describe oo                                                            |
|                                                                             |
|o20 = kk[x, Dx, y, Dy, Degrees => {2:{1}, 2:{0}}, Heft => {2:1},             |
|                                     {0}    {1}                              |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|MonomialOrder => {MonomialSize => 32}, WeylAlgebra => {{x, Dx}, {y, Dy}}]    |
|                 {GRevLex => {2:1}  }                                        |
|                 {Position => Up    }                                        |
|                 {GRevLex => {2:1}  }                                        |
+-----------------------------------------------------------------------------+

Two polynomial rings must have the same coefficient ring, otherwise an error is
issued. Currently, there is no way to specify other rings over which to define
the tensor product.

+-----------------------------------------------------------------------------+
|i21 : A = ZZ/101[a, b]                                                       |
|                                                                             |
|o21 = A                                                                      |
|                                                                             |
|o21 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i22 : B = A[x, y]                                                            |
|                                                                             |
|o22 = B                                                                      |
|                                                                             |
|o22 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i23 : C = tensor(B, B, Variables => {x1, y1, x2, y2})                        |
|                                                                             |
|o23 = C                                                                      |
|                                                                             |
|o23 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i24 : describe C                                                             |
|                                                                             |
|o24 = A[x1, y1, x2, y2, Degrees => {2:{1}, 2:{0}}, Heft => {2:1},            |
|                                      {0}    {1}                             |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|MonomialOrder => {MonomialSize => 32}]                                       |
|                 {GRevLex => {2:1}  }                                        |
|                 {Position => Up    }                                        |
|                 {GRevLex => {2:1}  }                                        |
+-----------------------------------------------------------------------------+

The flat monoid with the all variables visible, including those from the base
ring, can be obtained as follows.

+-----------------------------------------------------------------------------+
|i25 : C.FlatMonoid                                                           |
|                                                                             |
|o25 = monoid[x1, y1, x2, y2, a..b, Degrees => {2:{1}, 2:{0}, 2:{0}}, Heft => |
|                                                 {0}    {1}    {0}           |
|                                                 {0}    {0}    {1}           |
|                                                                             |
|                                                                             |
|o25 : GeneralOrderedMonoid                                                   |
|-----------------------------------------------------------------------------|
|{3:1}, MonomialOrder => {MonomialSize => 32   }]                             |
|                        {GRevLex => {2:1}     }                              |
|                        {Position => Up       }                              |
|                        {2:(GRevLex => {1, 1})}                              |
+-----------------------------------------------------------------------------+

Caveat
======

Not all of the options for monoid are useful here. Some are silently ignored.

See also
========

  * describe -- real description
  * degreesRing -- the ring or monoid of degrees
  * degreeLength -- the length of the degree vector
  * ** -- a binary operator, usually used for tensor product or
    Cartesian product
  * FlatMonoid

Ways to use this method:
========================

  * tensor(Monoid,Monoid) -- tensor product
    of monoids
  * "tensor(Ring,Ring)"

tensor(RingMap,Matrix) -- tensor product via a ring map
*******************************************************

Synopsis
========

  * Function: tensor,
  * Usage:
        f ** M
        tensor(f, M)
  * Inputs:
      * f, a ring map, from $R \to S$
      * M, a matrix, or a module, over the source
        ring $R$ of f
  * Outputs:
      * a matrix, or a module, the same type as M,
        but over the target ring $S$ of f

Description
===========

+---------------------------------------+
|i1 : R = QQ[a..d]                      |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : S = QQ[s,t]                       |
|                                       |
|o2 = S                                 |
|                                       |
|o2 : PolynomialRing                    |
+---------------------------------------+
|i3 : F = map(S,R,{s^4,s^3*t,s*t^3,t^4})|
|                                       |
|                  4   3      3   4     |
|o3 = map (S, R, {s , s t, s*t , t })   |
|                                       |
|o3 : RingMap S <-- R                   |
+---------------------------------------+
|i4 : m = matrix{{a,b,c,d}}             |
|                                       |
|o4 = | a b c d |                       |
|                                       |
|             1      4                  |
|o4 : Matrix R  <-- R                   |
+---------------------------------------+
|i5 : F ** m                            |
|                                       |
|o5 = | s4 s3t st3 t4 |                 |
|                                       |
|             1      4                  |
|o5 : Matrix S  <-- S                   |
+---------------------------------------+
|i6 : F ** image m                      |
|                                       |
|o6 = image | s4 s3t st3 t4 |           |
|                                       |
|                             1         |
|o6 : S-module, submodule of S          |
+---------------------------------------+

See also
========

  * RingMap Module -- apply a ring map
  * RingMap Module -- apply a ring map

Ways to use this method:
========================

  * tensor(RingMap,Matrix) -- tensor
    product via a ring map
  * "tensor(RingMap,Module)"

tensorAssociativity -- associativity isomorphisms for tensor products
*********************************************************************

Description
===========

tensorAssociativity(A,B,C) -- produces the isomorphism from A**(B**C) to
(A**B)**C.

Currently implemented for modules, graded modules, and chain complexes.

See also
========

  * ChainComplex -- the class of all chain complexes
  * Module -- the class of all modules

Ways to use tensorAssociativity:
================================

  * "tensorAssociativity(ChainComplex,ChainComplex,ChainComplex)"
  * "tensorAssociativity(GradedModule,GradedModule,GradedModule)"
  * "tensorAssociativity(Module,Module,Module)"

For the programmer
==================

The object tensorAssociativity, is a method function.

terms -- provide a list of terms of a polynomial
************************************************

Description
===========

Synopsis
========

  * Usage:
        terms f
  * Inputs:
      * f, a ring element, in a polynomial ring R with
        coefficient ring A
  * Outputs:
      * the list of terms of f
Each term is an element of the coefficient ring A, multiplied with a  monomial
in the variables of R.
+-------------------------+
|i1 : R = QQ[a..d];       |
+-------------------------+
|i2 : terms(a+d^2-1+a*b*c)|
|                         |
|              2          |
|o2 = {a*b*c, d , a, -1}  |
|                         |
|o2 : List                |
+-------------------------+
In the situation where the ring is a polynomial ring over another polynomial
ring, the polynomial is split using the monomials of the outer ring.
+-----------------------------------+
|i3 : S = R[x,y];                   |
+-----------------------------------+
|i4 : terms(a*x+b*x+c*x*y+c*x^3+1+a)|
|                                   |
|         3                         |
|o4 = {c*x , c*x*y, (a + b)x, a + 1}|
|                                   |
|o4 : List                          |
+-----------------------------------+

Synopsis
========

  * Usage:
        terms(k,f)
  * Inputs:
      * k, a ring,
      * f, a ring element, in a polynomial ring R
  * Outputs:
      * the list of terms of f with k regarded as the coefficient ring

Each term is an element of the coefficient ring k, multiplied with a monomial
in the variables of R. This is useful in the situation where the polynomial R
is built from k by a sequence of extensions.

+----------------------------------------------------------+
|i5 : R = QQ[a][d];                                        |
+----------------------------------------------------------+
|i6 : f = (1+a+d)^3                                        |
|                                                          |
|      3            2      2               3     2         |
|o6 = d  + (3a + 3)d  + (3a  + 6a + 3)d + a  + 3a  + 3a + 1|
|                                                          |
|o6 : R                                                    |
+----------------------------------------------------------+
|i7 : terms f                                              |
|                                                          |
|       3           2     2              3     2           |
|o7 = {d , (3a + 3)d , (3a  + 6a + 3)d, a  + 3a  + 3a + 1} |
|                                                          |
|o7 : List                                                 |
+----------------------------------------------------------+
|i8 : terms(QQ,f)                                          |
|                                                          |
|       3      2    2    2              3    2             |
|o8 = {d , 3a*d , 3d , 3a d, 6a*d, 3d, a , 3a , 3a, 1}     |
|                                                          |
|o8 : List                                                 |
+----------------------------------------------------------+

See also
========

  * coefficients -- monomials and their coefficients
  * monomials -- matrix of monomials in a ring element or
    matrix
  * someTerms -- select some terms of a polynomial

Ways to use terms:
==================

  * "terms(Ring,RingElement)"
  * "terms(RingElement)"

For the programmer
==================

The object terms, is a method function.

tests -- locate a package's tests
*********************************

Synopsis
========

  * Usage:
        tests pkg
        tests(i, pkg)
  * Inputs:
      * i, an integer,
      * pkg, a package, or a string,
  * Outputs:
      * a numbered vertical list, or a test input,

Description
===========

When an integer is not provided, this returns all the tests for the given
package.  The position of each element would be passed as the first argument of
check, to run the test. Each value is a TestInput object.  These
are printed with the location of the file so that you may quickly jump to the
source code of the test when using Emacs.

+-----------------------------------------------------------------------------+
|i1 : tests "FirstPackage"                                                    |
|                                                                             |
|o1 = {0 => TestInput[../../../../../Macaulay2/packages/FirstPackage.m2:54:5- |
|                                                                             |
|o1 : NumberedVerticalList                                                    |
|-----------------------------------------------------------------------------|
|56:3]}                                                                       |
+-----------------------------------------------------------------------------+

If the test number is also provided, then the corresponding TestInput object is
returned.

+---------------------------------------------------------------------------+
|i2 : t = tests(0, "FirstPackage")                                          |
|                                                                           |
|o2 = TestInput[../../../../../Macaulay2/packages/FirstPackage.m2:54:5-56:3]|
|                                                                           |
|o2 : TestInput                                                             |
+---------------------------------------------------------------------------+

The locate, and code, functions do the expected thing
when given a TestInput object.

+--------------------------------------------------------------------------+
|i3 : locate t                                                             |
|                                                                          |
|o3 = ../../../../../Macaulay2/packages/FirstPackage.m2:54:5-56:3          |
|                                                                          |
|o3 : FilePosition                                                         |
+--------------------------------------------------------------------------+
|i4 : code t                                                               |
|                                                                          |
|o4 = ../../../../../Macaulay2/packages/FirstPackage.m2:54:5-56:3: --source|
|     code:                                                                |
|     TEST ///                                                             |
|         assert ( firstFunction 2 == "D'oh!" )                            |
|     ///                                                                  |
+--------------------------------------------------------------------------+

Passing only the key of the desired test to code, is supported as
well.

+--------------------------------------------------------------------------+
|i5 : code 0                                                               |
|                                                                          |
|o5 = ../../../../../Macaulay2/packages/FirstPackage.m2:54:5-56:3: --source|
|     code:                                                                |
|     TEST ///                                                             |
|         assert ( firstFunction 2 == "D'oh!" )                            |
|     ///                                                                  |
+--------------------------------------------------------------------------+

You may also pass a TestInput object to edit, to open the code in
your favorite editor.

Ways to use tests:
==================

  * "tests(Package)"
  * "tests(String)"
  * "tests(ZZ,Package)"
  * "tests(ZZ,String)"

For the programmer
==================

The object tests, is a method function.

tex -- convert to $\TeX$ format
*******************************

Synopsis
========

  * Usage:
        tex x
  * Inputs:
      * x, any Macaulay2 object
  * Outputs:
      * a string, x converted to $\TeX$ format

Description
===========

+-----------------------------------------+
|i1 : R = ZZ[a..f];                       |
+-----------------------------------------+
|i2 : tex matrix {{a^2+2,b,c},{d,e,f^3-a}}|
|                                         |
|o2 = $\left(\!\begin{array}{ccc}         |
|     a^{2}+2&b&c\\                       |
|     d&e&f^{3}-a                         |
|     \end{array}\!\right)$               |
+-----------------------------------------+

Caveat
======

No attempt is made to wrap large matrices or equations.

See also
========

  * texMath -- convert to TeX math format
  * mathML -- convert to MathML format
  * showTex -- display various objects in an external viewer

For the programmer
==================

The object tex, is a method function with a single argument.

TeXmacs -- the TeXmacs top level printing method
************************************************

Description
===========

This symbol is used (tentatively) as the first element of a pair to specify
various top level interpreter methods, in connection with the use of TeXmacs as
front end.

See also
========

  * Standard -- the standard top level printing method
  * Print -- top level method for printing results
  * NoPrint -- top level method for non-printing results
  * BeforePrint -- top level method applied before printing
    results
  * AfterPrint -- top level method applied after printing
  * AfterNoPrint -- top level method applied after not
    printing

For the programmer
==================

The object TeXmacs, is a symbol.

texMath -- convert to TeX math format
*************************************

Synopsis
========

  * Usage:
        texMath x
  * Inputs:
      * x, any Macaulay2 object
  * Outputs:
      * a string, x converted to TeX math format

Description
===========

The main difference between this and tex, is that the surrounding
dollar signs aren't there.
+--------------------------------------------------------+
|i1 : R = ZZ[x];                                         |
+--------------------------------------------------------+
|i2 : texMath (x-1)^6                                    |
|                                                        |
|o2 = x^{6}-6\,x^{5}+15\,x^{4}-20\,x^{3}+15\,x^{2}-6\,x+1|
+--------------------------------------------------------+

Caveat
======

No attempt is made to wrap large matrices or equations.

See also
========

  * tex -- convert to $\TeX$ format
  * mathML -- convert to MathML format
  * showTex -- display various objects in an external viewer

For the programmer
==================

The object texMath, is a method function with a single argument.

the debugger
************

We have a Macaulay2 source file with a pair of functions in it that we can use
for demonstrating the debugger.  Let's load it so we can run the functions in
it.
+---------------------------------+
|i1 : load "Macaulay2Doc/demo1.m2"|
+---------------------------------+
We can see what functions were provided to us with listUserSymbols.
+-----------------------------------------------------------------------------+
|i2 : listUserSymbols                                                         |
|                                                                             |
|o2 = symbol  class            value                                          |
|     ------  -----            -----                                          |
|     g       FunctionClosure  g                                              |
|-----------------------------------------------------------------------------|
|location of symbol                                                           |
|------------------                                                           |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:11:0-11:1                   |
+-----------------------------------------------------------------------------+
Let's peek at the code of the function g.
+---------------------------------------------+
|i3 : code g                                  |
|                                             |
|o3 = /usr/local/share/Macaulay2/Macaulay2Doc/|
|     demo1.m2:11:4-14:9: --source code:      |
|     g = y -> (                              |
|          c := f(y-1);                       |
|          d := f(y-2);                       |
|          c+d)                               |
+---------------------------------------------+
We see that the function g calls a function f, but f is not visible to us
(because f is a local variable).  In emacs' Macaulay2 Interaction Mode,
pressing return (RET or enter) after positioning the cursor on the output line
displaying the file name and line number will bring up the source code in a new
buffer.

The first few times we use g, it seems to work.

+--------+
|i4 : g 4|
|        |
|     17 |
|o4 = -- |
|      6 |
|        |
|o4 : QQ |
+--------+
|i5 : g 3|
|        |
|     7  |
|o5 = -  |
|     2  |
|        |
|o5 : QQ |
+--------+
However, the following attempt results in an error, and the debugger starts up
automatically.
+-----------------------------------------------------------------------------+
|i6 : g 2                                                                     |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|8:10-8:13: --source code:                                                    |
|     b := 1/x;                                                               |
|-----------------------------------------------------------------------------|
|error: division by zero                                                      |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
You may use help, as instructed, to view the commands available in
the debugger. As suggested by the help display, we can use
listLocalSymbols, to list the local symbols and their values.
+-----------------------------------------------------------------------------+
|ii7 : listLocalSymbols                                                       |
|                                                                             |
|oo7 = symbol  class                                                          |
|      ------  -----                                                          |
|      a       String                                                         |
|      b       Nothing                                                        |
|      x       ZZ                                                             |
|      f       FunctionClosure                                                |
|-----------------------------------------------------------------------------|
|value                                                                        |
|-----                                                                        |
|"hi there"                                                                   |
|null                                                                         |
|0                                                                            |
|FunctionClosure[/home/m2user/src/macaulay2/M2/M2/Ma.                         |
|-----------------------------------------------------------------------------|
|   location of symbol                                                        |
|   ------------------                                                        |
|   /usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:7:5-7:6                  |
|   /usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:5-8:6                  |
|   /usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:6:5-6:6                  |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:6:0-6:1                     |
+-----------------------------------------------------------------------------+
We see that the value of x is 0, and that explains the error message about
division by zero. The other local symbols are the ones defined in the body of
the function f, whose code can now be displayed with code.
+----------------------------------------------+
|ii8 : code f                                  |
|                                              |
|oo8 = /usr/local/share/Macaulay2/Macaulay2Doc/|
|      demo1.m2:6:5-9:9: --source code:        |
|      f := x -> (                             |
|           a := "hi there";                   |
|           b := 1/x;                          |
|           b+1)                               |
+----------------------------------------------+
We can use step, with argument 0 to bypass the current expression.
+-----------------------------------------------------------------------------+
|ii9 : step 0                                                                 |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]: --stepping    |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]: --entering    |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|8:10-8:13: --source code:                                                    |
|     b := 1/x;                                                               |
|-----------------------------------------------------------------------------|
|limit reached                                                                |
|debugger (type help to see debugger commands)                                |
+-----------------------------------------------------------------------------+
If we decide the problem is one level up, we can use end or the end-of-file
character (which often is CTRL-D) to quit this instance of the debugger.  In
this case, the debugger will be entered again (triggered by the same error
indication that caused it to be entered originally) at the point inside the
function g from which the function f was called.
+-----------------------------------------------------------------------------+
|ii10 : end                                                                   |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:13:11:(3):[1]: --entering   |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|13:10-13:16: --source code:                                                  |
|     d := f(y-2);                                                            |
|-----------------------------------------------------------------------------|
|debugger (type help to see debugger commands)                                |
+-----------------------------------------------------------------------------+
We can use listLocalSymbols, again to see the local
variables of g.
+-----------------------------------------------------------------------------+
|ii11 : listLocalSymbols                                                      |
|                                                                             |
|oo11 = symbol  class                                                         |
|       ------  -----                                                         |
|       c       QQ                                                            |
|       d       Nothing                                                       |
|       y       ZZ                                                            |
|       f       FunctionClosure                                               |
|-----------------------------------------------------------------------------|
|value                                                                        |
|-----                                                                        |
|2                                                                            |
|null                                                                         |
|2                                                                            |
|FunctionClosure[/home/m2user/src/macaulay2/M2/M2/Ma.                         |
|-----------------------------------------------------------------------------|
|   location of symbol                                                        |
|   ------------------                                                        |
|   /usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:12:5-12:6                |
|   /usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:13:5-13:6                |
|   /usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:11:4-11:5                |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:6:0-6:1                     |
+-----------------------------------------------------------------------------+
After we are done debugging, we can quit the debugger entirely and return to
top level with break.
+------------+
|ii12 : break|
+------------+
The variable errorDepth, can be used to control how deep
inside the code the debugger should be activated.

See also
========

  * break -- break from a loop
  * end -- stop loading a file
  * step -- step by single lines in the debugger
  * continue -- continue with the next iteration of a loop
  * return -- return from a function
  * listLocalSymbols -- display of local symbols and
    their values
  * listUserSymbols -- display the user's symbols
  * code -- display source code
  * value -- evaluate
  * pseudocode -- produce the pseudocode for a function
  * disassemble -- disassemble a pseudocode or function
  * errorDepth -- set the error printing depth

then -- condition testing
*************************

Description
===========

then a keyword used with if.
+---------------------------+
|i1 : if 5 > 4 then 8 else 7|
|                           |
|o1 = 8                     |
+---------------------------+

See also
========

  * if -- condition testing
  * else -- condition testing

For the programmer
==================

The object then, is a keyword.

Thing -- the class of all things
********************************

Description
===========

Everything in Macaulay2 is a thing.  This includes numbers, strings, and lists.
More complicated things such as polynomials, groups, rings, and chain complexes
are implemented as hash tables.  See Type, for information about
what types of things there are.

Types of thing:
===============

  * AtomicInt -- the class of atomic integers
  * BasicList -- the class of all basic lists
  * Boolean -- the class of Boolean values
  * Database -- the class of all database files
  * Dictionary -- the class of all dictionaries
  * File -- the class of all files
  * Function -- the class of all functions
  * FunctionBody -- the class of function bodies
  * HashTable -- the class of all hash tables
  * Net -- the class of all nets and strings
  * NetFile -- the class of all net files
  * Nothing -- the empty class
  * Number -- the class of all numbers
  * Pseudocode -- the class of pseudocodes
  * Symbol -- the class of all symbols
  * "SymbolBody" -- see symbolBody, -- symbol bodies
  * Task -- the class of all tasks

Functions and methods returning a thing:
========================================

  * BasicList # ZZ -- get value from list, hash table,
    database, or string
  * "HashTable # Thing" -- see BasicList # ZZ, -- get
    value from list, hash table, database, or string
  * Function Thing -- function application
  * List # ZZ (missing documentation)
  * "scan(BasicList,BasicList,Function)" -- see scan, -- apply a
    function to each element in a list or sequence
  * "scan(BasicList,Function)" -- see scan, -- apply a function to
    each element in a list or sequence
  * "scan(Thing,Function)" -- see scan, -- apply a function to each
    element in a list or sequence
  * "scan(ZZ,Function)" -- see scan, -- apply a function to each
    element in a list or sequence
  * Sequence # ZZ (missing documentation)
  * taskResult(Task) -- retrieve the value
    returned by a task

Methods that use a thing:
=========================

  * "HashTable #? Thing" -- see #?, -- check existence of value in a
    list, hash table, database, or string
  * "List * Thing" -- see *, -- a binary operator, usually used for
    multiplication
  * "Thing * List" -- see *, -- a binary operator, usually used for
    multiplication
  * "Thing =!= Thing" -- see =!=, -- strict inequality
  * "Thing => Thing" -- see =>, -- produce an Option
  * "accumulate(Function,Thing)" -- see accumulate, -- apply
    a binary operator repeatedly
  * "accumulate(Function,Thing,Thing)" -- see accumulate, --
    apply a binary operator repeatedly
  * "accumulate(Function,Thing,VisibleList)" -- see accumulate,
    -- apply a binary operator repeatedly
  * "accumulate(VisibleList,Thing,Function)" -- see accumulate,
    -- apply a binary operator repeatedly
  * "addHook(MutableHashTable,Thing,Function)" -- see addHook,
    -- add a hook function to an object for later processing
  * "append(BasicList,Thing)" -- see append, -- add an element to
    the end of a list
  * apply(Thing,Function) -- apply a
    function to an object with an iterator
  * "assert(Thing)" -- see assert, -- check whether something is
    true, raise an error if not
  * "baseName(Thing)" -- see baseName, -- the base name of a
    generator
  * between(Thing,VisibleList), --
    insert something between elements of a list
  * "class(Thing)" -- see class, -- class of an object
  * "Command Thing" -- see Command, -- the class of all commands
  * "createTask(Function,Thing)" -- see createTask, -- create
    a task
  * "delete(Thing,BasicList)" -- see delete, -- delete some
    elements of a list
  * "describe(Thing)" -- see describe, -- real description
  * "dictionary(Thing)" -- see dictionary, -- determine the
    dictionary to which a symbol belongs
  * "makeDocumentTag(Thing)" -- see DocumentTag, -- the
    class of all document tags
  * "examples(Thing)" -- see examples, -- list the examples in
    documentation
  * "<< Thing" -- see File << Thing, -- print to a file
  * File << Thing -- print to a file
  * "Nothing << Thing" -- see File << Thing, -- print to a
    file
  * "String << Thing" -- see File << Thing, -- print to a
    file
  * "fold(Function,Thing)" -- see fold, -- apply a binary operator
    repeatedly
  * "fold(Function,Thing,Thing)" -- see fold, -- apply a binary
    operator repeatedly
  * "fold(VisibleList,Thing,Function)" -- see fold, -- apply a
    binary operator repeatedly
  * Function _ Thing -- attach the first argument to
    a function of two or more arguments
  * "help(Thing)" -- see help, -- view documentation nodes
  * "hooks(Thing)" -- see hooks, -- list hooks attached to a key
  * "IndexedVariableTable _ Thing" -- see IndexedVariableTable,
  * "IndexedVariableTable _ Thing = Thing" -- see IndexedVariableTable,
  * IndexedVariableTable .. Thing (missing documentation)
  * IndexedVariableTable ..< Thing (missing documentation)
  * "infoHelp(Thing)" -- see infoHelp, -- view documentation in
    Info format
  * "insert(ZZ,Thing,BasicList)" -- see insert, -- copy a list,
    inserting an element
  * "instance(Thing,Type)" -- see instance, -- whether
    something has a certain type
  * "isFreeModule(Thing)" -- see isFreeModule, -- whether
    something is a free module
  * "isIdeal(Thing)" -- see isIdeal, -- whether something is an
    ideal
  * "isMember(Thing,Set)" -- see isMember, -- test membership
    in a list or set
  * "isMember(Thing,VisibleList)" -- see isMember, -- test
    membership in a list or set
  * "isModule(Thing)" -- see isModule, -- whether something is
    a module
  * "isMonomialIdeal(Thing)" -- see isMonomialIdeal, --
    whether something is a monomial ideal
  * "isMutable(Thing)" -- see isMutable, -- whether something
    may be modified
  * "isPolynomialRing(Thing)" -- see isPolynomialRing,
    -- whether something is a polynomial ring
  * "isQuotientModule(Thing)" -- see isQuotientModule,
    -- whether something is evidently a quotient of a free module
  * "isRing(Thing)" -- see isRing, -- whether something is a ring
  * "isSubmodule(Thing)" -- see isSubmodule, -- whether a
    module is evidently a submodule of a free module
  * "methods(Thing)" -- see methods, -- list methods
  * MonoidElement .. Thing (missing documentation)
  * MonoidElement ..< Thing (missing documentation)
  * MonoidElement _ Thing (missing documentation)
  * "net(Thing)" -- see net, -- format for printing, as a net
  * Nothing #? Thing (missing documentation)
  * "package(Thing)" -- see package, -- get containing package
  * "parent(Thing)" -- see parent, -- parent type of an object
  * "peek'(ZZ,Thing)" -- see peek', -- examine contents of an
    object
  * "prepend(Thing,BasicList)" -- see prepend, -- add an element
    to the beginning of a list
  * Program << Thing -- run program with input
    redirection
  * registerFinalizer(Thing,String) (missing documentation)
  * "remove(HashTable,Thing)" -- see remove, -- remove an entry
    from a mutable hash table, list, or database
  * replace(ZZ,Thing,BasicList), --
    copy a list, replacing an element
  * RingElement .. Thing (missing documentation)
  * RingElement ..< Thing (missing documentation)
  * RingElement _ Thing (missing documentation)
  * "runHooks(MutableHashTable,Thing,Thing)" -- see runHooks,
    -- run the hook functions stored in an object
  * "runHooks(Sequence,Thing)" -- see runHooks, -- run the hook
    functions stored in an object
  * "runHooks(Symbol,Thing)" -- see runHooks, -- run the hook
    functions stored in an object
  * "schedule(Function,Thing)" -- see schedule, -- schedule a
    task for execution
  * "ScriptedFunctor ^ Thing" -- see ScriptedFunctor, --
    the class of all scripted functors
  * "ScriptedFunctor _ Thing" -- see ScriptedFunctor, --
    the class of all scripted functors
  * "ScriptedFunctor Thing" -- see ScriptedFunctor, --
    the class of all scripted functors
  * select(Thing,Function) -- select
    elements from an object with an iterator
  * "SelfInitializingType Thing" -- see SelfInitializingType,
    -- the class of all self initializing types
  * Set #? Thing -- test set membership
  * Symbol _ Thing -- index variable
  * Symbol _ Thing = Thing -- assignment to an
    indexed variable
  * "SYNOPSIS(Thing)" -- see SYNOPSIS, -- a standardized
    synopsis for use in documentation nodes
  * "take(Thing,List)" -- see take, -- Take some elements from a
    list or sequence.
  * "take(Thing,ZZ)" -- see take, -- Take some elements from a list
    or sequence.
  * Thing .. IndexedVariableTable (missing documentation)
  * Thing .. MonoidElement (missing documentation)
  * Thing .. RingElement (missing documentation)
  * Thing ..< IndexedVariableTable (missing documentation)
  * Thing ..< MonoidElement (missing documentation)
  * Thing ..< RingElement (missing documentation)
  * /// Command \\ Thing /// -- see Thing // Function,
    -- apply a function
  * /// Function \\ Thing /// -- see Thing // Function,
    -- apply a function
  * /// SelfInitializingType \\ Thing /// -- see Thing // Function,
    -- apply a function
  * "Thing // Command" -- see Thing // Function, --
    apply a function
  * Thing // Function -- apply a function
  * "Thing // SelfInitializingType" -- see Thing // Function,
    -- apply a function
  * Thing === Thing -- strict equality
  * "toList(Thing)" -- see toList, -- create a list
  * "toSequence(Thing)" -- see toSequence, -- convert to
    sequence
  * truncate(InfiniteNumber,Thing) (missing documentation)
  * "ultimate(Function,Thing)" -- see ultimate, -- ultimate
    value for an iteration
  * "undocumented(Thing)" -- see undocumented, -- declare
    that something need not be documented
  * "viewHelp(Thing)" -- see viewHelp, -- view online
    documentation in a web browser
  * VirtualTally _ Thing -- get a count from a
    tally
  * "WrapperType Thing" -- see WrapperType, -- a class of
    lists with abbreviated constructors
  * ZZ _colon_ Thing -- repeat an item

For the programmer
==================

The object Thing, is a type, with no ancestor class..

Thing // Function -- apply a function
*************************************

Synopsis
========

  * Operator: //,
  * Usage:
        x // f
        f \\ x
  * Inputs:
      * x
      * f, a function, a command, or a
        self initializing type,
  * Outputs:
      * the result of applying f to x, i.e., f x

Description
===========

The parsing precedence of the operators // and \\ is rather low, which makes
them useful for avoiding parentheses.  See precedence of operators.

+---------------------------------------------------+
|i1 : toList \\ sin \ ( 1 .. 5 )                    |
|                                                   |
|o1 = {.841471, .909297, .14112, -.756802, -.958924}|
|                                                   |
|o1 : List                                          |
+---------------------------------------------------+
|i2 : ( 1 .. 5 ) / sin // toList                    |
|                                                   |
|o2 = {.841471, .909297, .14112, -.756802, -.958924}|
|                                                   |
|o2 : List                                          |
+---------------------------------------------------+
|i3 : (x -> (x,x)) \ (a,b,c,d)                      |
|                                                   |
|o3 = ((a, a), (b, b), (c, c), (d, d))              |
|                                                   |
|o3 : Sequence                                      |
+---------------------------------------------------+
|i4 : splice \\ (x -> (x,x)) \ (a,b,c,d)            |
|                                                   |
|o4 = (a, a, b, b, c, c, d, d)                      |
|                                                   |
|o4 : Sequence                                      |
+---------------------------------------------------+

See also
========

  * VisibleList / Function -- apply a function
    to elements of a list

Ways to use this method:
========================

  * "Thing // Command"
  * Thing // Function -- apply a function
  * "Thing // SelfInitializingType"

times -- multiplication
***********************

Synopsis
========

  * Usage:
        times(x,y, ...)

Description
===========

times(x,y, ...) yields the product of its arguments. If there are no arguments,
the value is the integer 1.

For the programmer
==================

The object times, is a compiled function.

to -- loop control
******************

Description
===========

to a keyword used with for.

For the programmer
==================

The object to, is a keyword.

toAbsolutePath -- the absolute path version of a file name
**********************************************************

Synopsis
========

  * Usage:
        toAbsolutePath filename
  * Inputs:
      * filename, a string,
  * Outputs:
      * a string, the absolute (real) path name of filename

Description
===========

+--------------------------------------------------------------------+
|i1 : toAbsolutePath "a/b.m2"                                        |
|                                                                    |
|o1 = /home/m2user/src/macaulay2/M2/M2/BUILD/doug/Macaulay2/packages/|
|     Macaulay2Doc-temporary/a/b.m2                                  |
+--------------------------------------------------------------------+

Paths of the form foo/x/../bar, are shortened to foo/bar without checking the
file system to see whether x is a symbolic link.  For the other behavior, see
realpath.

See also
========

  * File -- the class of all files
  * minimizeFilename -- minimize a file name
  * relativizeFilename -- relativize a file name
  * baseFilename -- the base part of a filename or path
  * path -- list of directories to look in
  * rootPath
  * rootURI

For the programmer
==================

The object toAbsolutePath, is a function closure.

toCC -- convert to high-precision complex number
************************************************

Description
===========

Synopsis
========

  * Usage:
        toCC(prec,x,y)
        toCC(prec,x)
  * Inputs:
      * prec, an integer, the number of bits of precision desired
      * x, an integer, a rational number, or a real number,
      * y, an integer, a rational number, or a real number,
  * Outputs:
      * a complex number, the complex number with real part x and
        complex part y.  If y is omitted, the imaginary part is zero.
+--------------------------+
|i1 : toCC(200,7)          |
|                          |
|o1 = 7                    |
|                          |
|o1 : CC (of precision 200)|
+--------------------------+
|i2 : toCC(100,7,3.)       |
|                          |
|o2 = 7+3*ii               |
|                          |
|o2 : CC (of precision 100)|
+--------------------------+

Synopsis
========

  * Usage:
        toCC(x,y)
        toCC x
  * Inputs:
      * x, a real number,
      * y, a real number,
  * Outputs:
      * a complex number, the complex number with real part x and
        complex part y.  If y is omitted, the imaginary part is zero.  The
        precision of the result is the minimum precision of the arguments.
+--------------------------+
|i3 : toCC(3.,4.)          |
|                          |
|o3 = 3+4*ii               |
|                          |
|o3 : CC (of precision 53) |
+--------------------------+
|i4 : toCC(3.p100,4.p200)  |
|                          |
|o4 = 3+4*ii               |
|                          |
|o4 : CC (of precision 100)|
+--------------------------+

Ways to use toCC:
=================

  * "toCC(CC)"
  * "toCC(QQ)"
  * "toCC(RR)"
  * "toCC(RR,RR)"
  * "toCC(ZZ)"
  * "toCC(ZZ,CC)"
  * "toCC(ZZ,QQ)"
  * "toCC(ZZ,QQ,QQ)"
  * "toCC(ZZ,QQ,RR)"
  * "toCC(ZZ,QQ,ZZ)"
  * "toCC(ZZ,RR)"
  * "toCC(ZZ,RR,QQ)"
  * "toCC(ZZ,RR,RR)"
  * "toCC(ZZ,RR,ZZ)"
  * "toCC(ZZ,ZZ)"
  * "toCC(ZZ,ZZ,QQ)"
  * "toCC(ZZ,ZZ,RR)"
  * "toCC(ZZ,ZZ,ZZ)"

For the programmer
==================

The object toCC, is a compiled function.

toField(Ring) -- declare that a ring is a field
***********************************************

Synopsis
========

  * Function: toField,
  * Usage:
        L = toField R
  * Inputs:
      * R
  * Outputs:
      * L, a new ring, isomorphic to R, declared to be a field. Polynomial
        rings over it will support Gröbner basis operations.

Description
===========

+---------------------------------------+
|i1 : A = QQ[i]/(i^2+1);                |
+---------------------------------------+
|i2 : L = toField A                     |
|                                       |
|o2 = L                                 |
|                                       |
|o2 : PolynomialRing                    |
+---------------------------------------+
|i3 : B = L[x,y,z]                      |
|                                       |
|o3 = B                                 |
|                                       |
|o3 : PolynomialRing                    |
+---------------------------------------+
|i4 : I = ideal(i*x^2-y-i, i*y^2-z-i)   |
|                                       |
|               2             2         |
|o4 = ideal (i*x  - y - i, i*y  - z - i)|
|                                       |
|o4 : Ideal of B                        |
+---------------------------------------+
|i5 : gens gb I                         |
|                                       |
|o5 = | y2+iz-1 x2+iy-1 |               |
|                                       |
|             1      2                  |
|o5 : Matrix B  <-- B                   |
+---------------------------------------+

If the engine eventually discovers that some nonzero element of L is not a
unit, an error will be signalled.  The user may then use getNonUnit,
to obtain a non-invertible element of L. If a ring probably is a
field, it can be used as a field until a contradiction is found, and this may
be a good way of discovering whether a ring is a field.

+-------------------------------------------------------------+
|i6 : A = ZZ[a]/(a^2+3);                                      |
+-------------------------------------------------------------+
|i7 : L = toField A                                           |
|                                                             |
|o7 = L                                                       |
|                                                             |
|o7 : PolynomialRing                                          |
+-------------------------------------------------------------+
|i8 : L[x,y,z]                                                |
|                                                             |
|o8 = L[x..z]                                                 |
|                                                             |
|o8 : PolynomialRing                                          |
+-------------------------------------------------------------+
|i9 : try gb ideal (a*x^2-y^2-z^2, y^3, z^3) else getNonUnit L|
|                                                             |
|o9 = a                                                       |
|                                                             |
|o9 : L                                                       |
+-------------------------------------------------------------+

See also
========

  * getNonUnit -- retrieve a previously discovered non-unit
  * try -- catch an error

Ways to use this method:
========================

  * toField(Ring) -- declare that a ring is a field

toList -- create a list
***********************

Synopsis
========

  * Usage:
        toList A
  * Inputs:
      * A, a set, a string, a basic list,
        or an integer, or an instance of a class with
        the iterator, method installed
  * Outputs:
      * L, a list, a list whose elements are the elements of A

Description
===========

+---------------------+
|i1 : toList "foo"    |
|                     |
|o1 = {f, o, o}       |
|                     |
|o1 : List            |
+---------------------+
|i2 : A = set(3,7,9,6)|
|                     |
|o2 = set {9, 3, 6, 7}|
|                     |
|o2 : Set             |
+---------------------+
|i3 : toList A        |
|                     |
|o3 = {9, 3, 6, 7}    |
|                     |
|o3 : List            |
+---------------------+

The command toList 1..9 will throw an error, because toList comes before
.., in Macaulay2's order of operations. To create a list from a range,
use toList (1..9) instead.

+--------------------------------+
|i4 : toList (1..9)              |
|                                |
|o4 = {1, 2, 3, 4, 5, 6, 7, 8, 9}|
|                                |
|o4 : List                       |
+--------------------------------+

Converting between list types may change the order of the elements in
unexpected ways.

+------------------------+
|i5 : toList set {4,5,13}|
|                        |
|o5 = {4, 13, 5}         |
|                        |
|o5 : List               |
+------------------------+

See also
========

  * BasicList -- the class of all basic lists
  * List -- the class of all lists -- {...}
  * toSequence -- convert to sequence
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use toList:
===================

  * "toList(BasicList)"
  * "toList(Set)"
  * "toList(String)"
  * "toList(Thing)"
  * toList(Pseudocode) (missing documentation)

For the programmer
==================

The object toList, is a method function with a single argument.

toLower -- convert to lower case
********************************

Synopsis
========

  * Usage:
        toLower s
  * Inputs:
      * s, a string,
  * Outputs:
      * a string, the string produced from s by converting its
        characters to lower case

Description
===========

+--------------------------+
|i1 : toLower "A b C d E f"|
|                          |
|o1 = a b c d e f          |
+--------------------------+

For the programmer
==================

The object toLower, is a function closure.

topCoefficients -- first variable and its coefficient of a polynomial or matrix
*******************************************************************************

Synopsis
========

  * Usage:
        (lf, cf) = topCoefficients f
  * Inputs:
      * f, a ring element, or a matrix,
  * Outputs:
      * lf, a ring element, or a matrix, the
        power of the lowest index variable occurring in f, if f is a ring
        element, or the one row matrix of these powers for each column, if f is
        a matrix.
      * cf, a ring element, or a matrix, the
        coefficient of lf in f, if f is a ring element, or the matrix of these
        coefficients for each column of f

Description
===========

+-------------------------------------------------+
|i1 : A = ZZ[x]                                   |
|                                                 |
|o1 = A                                           |
|                                                 |
|o1 : PolynomialRing                              |
+-------------------------------------------------+
|i2 : (lf,cf) = topCoefficients (7*x^4-13*x^3+x+1)|
|                                                 |
|       4                                         |
|o2 = (x , 7)                                     |
|                                                 |
|o2 : Sequence                                    |
+-------------------------------------------------+
|i3 : v = first support lf                        |
|                                                 |
|o3 = x                                           |
|                                                 |
|o3 : A                                           |
+-------------------------------------------------+
|i4 : e = first degree lf                         |
|                                                 |
|o4 = 4                                           |
+-------------------------------------------------+
The polynomial ring may have more variables.
+-----------------------------------------------+
|i5 : B = ZZ[x,y,z]                             |
|                                               |
|o5 = B                                         |
|                                               |
|o5 : PolynomialRing                            |
+-----------------------------------------------+
|i6 : f = y^4*(3*z^3-z^2-1) - y^3*z^7 + y + z^12|
|                                               |
|      12    3 7     4 3    4 2    4            |
|o6 = z   - y z  + 3y z  - y z  - y  + y        |
|                                               |
|o6 : B                                         |
+-----------------------------------------------+
|i7 : (lf,cf) = topCoefficients f               |
|                                               |
|       4    3    2                             |
|o7 = (y , 3z  - z  - 1)                        |
|                                               |
|o7 : Sequence                                  |
+-----------------------------------------------+

Caveat
======

If the polynomial ring B of f has a polynomial coefficient ring A, and no
variables of B occur in f, then this 'drills down' into A and finds the top
variable and coefficient there, but as elements of B

See also
========

  * pseudoRemainder -- compute the pseudo-remainder

Ways to use topCoefficients:
============================

  * "topCoefficients(Matrix)"
  * "topCoefficients(RingElement)"

For the programmer
==================

The object topCoefficients, is a method function.

topLevelMode -- the current top level mode
******************************************

Synopsis
========

  * Usage:
        topLevelMode = x
  * Inputs:
      * x, a symbol, TeXmacs, or Standard,
        or WebApp, or Jupyter,
  * Consequences:
      * the interpreter will produce input and output prompts appropriate for
        the mode, and will format output values appropriately

Description
===========

This variable is intended for internal use only.

For the programmer
==================

The object topLevelMode, is a symbol.

Tor -- Tor module
*****************

Ways to use Tor:
================

  * Tor_ZZ(Ideal,Matrix) (missing documentation)
  * Tor_ZZ(Matrix,Ideal) (missing documentation)
  * Tor_ZZ(Matrix,Module) (missing documentation)
  * Tor_ZZ(Matrix,Ring) (missing documentation)
  * Tor_ZZ(Module,Matrix) (missing documentation)
  * "Tor_ZZ(Ideal,Ideal)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * "Tor_ZZ(Ideal,Module)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * "Tor_ZZ(Ideal,Ring)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * "Tor_ZZ(Module,Ideal)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * Tor_ZZ(Module,Module) -- compute a
    Tor module
  * "Tor_ZZ(Module,Ring)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * Tor_ZZ(Ring,Ideal) (missing documentation)
  * Tor_ZZ(Ring,Matrix) (missing documentation)
  * Tor_ZZ(Ring,Module) (missing documentation)
  * Tor_ZZ(Ring,Ring) (missing documentation)

For the programmer
==================

The object Tor, is a scripted functor.

Tor_ZZ(Module,Module) -- compute a Tor module
*********************************************

Synopsis
========

  * Scripted functor: Tor,
  * Usage:
        Tor_i(M,N)
  * Inputs:
      * i
      * M
      * N
  * Outputs:
      * the i-th Tor module of M and N

Description
===========

If N is a ring (instead of a module), then the free module of rank 1 over it is
used instead.  If M or N is an ideal of ring, then the underlying module is
used instead.

Ways to use this method:
========================

  * "Tor_ZZ(Ideal,Ideal)"
  * "Tor_ZZ(Ideal,Module)"
  * "Tor_ZZ(Ideal,Ring)"
  * "Tor_ZZ(Module,Ideal)"
  * Tor_ZZ(Module,Module) -- compute a
    Tor module
  * "Tor_ZZ(Module,Ring)"

toRR -- convert to high-precision real number
*********************************************

Synopsis
========

  * Usage:
        toRR(prec,x)
  * Inputs:
      * prec, an integer, the number of bits of precision desired
      * x, a real number, an integer, or a rational number,
  * Outputs:
      * a real number, the result of converting x to a
        high-precision real number

Description
===========

+-------------------------------------------------------------------+
|i1 : toRR(200,1/7)                                                 |
|                                                                   |
|o1 = .1428571428571428571428571428571428571428571428571428571428571|
|                                                                   |
|o1 : RR (of precision 200)                                         |
+-------------------------------------------------------------------+
|i2 : precision oo                                                  |
|                                                                   |
|o2 = 200                                                           |
+-------------------------------------------------------------------+

For the programmer
==================

The object toRR, is a compiled function.

toRRi -- construct an interval
******************************

Synopsis
========

  * Usage:
        I = toRRi(n)
        I = toRRi(l,r)
        I = toRRi(prec,l,r)
  * Inputs:
      * n, a number,
      * l, a number,
      * r, a number,
      * prec, an integer,
  * Outputs:
      * I, a real interval,

Description
===========

Returns an interval as small as possible containing n or from l to r.  Note
that if l is to the right of r, the constructed interval is empty.  This is a
more low-level function and interval, or span should be used
instead.

See also
========

  * span(List) -- construct smallest interval
  * span(Sequence) -- construct smallest interval
  * interval -- construct an interval

For the programmer
==================

The object toRRi, is a compiled function.

toSequence -- convert to sequence
*********************************

Synopsis
========

  * Usage:
        toSequence x
  * Inputs:
      * x, a basic list, or a string, or an
        instance of a class with the iterator, method installed
  * Outputs:
      * a sequence,

Description
===========

toSequence x yields the elements of a x as a sequence.

+----------------------------------+
|i1 : toSequence {1, 2, 3}         |
|                                  |
|o1 = (1, 2, 3)                    |
|                                  |
|o1 : Sequence                     |
+----------------------------------+
|i2 : toSequence "foo"             |
|                                  |
|o2 = (f, o, o)                    |
|                                  |
|o2 : Sequence                     |
+----------------------------------+
|i3 : toSequence iterator {1, 2, 3}|
|                                  |
|o3 = (1, 2, 3)                    |
|                                  |
|o3 : Sequence                     |
+----------------------------------+

If x is already a sequence, then x is returned.

+-------------------------+
|i4 : toSequence (1, 2, 3)|
|                         |
|o4 = (1, 2, 3)           |
|                         |
|o4 : Sequence            |
+-------------------------+

Ways to use toSequence:
=======================

  * "toSequence(BasicList)"
  * "toSequence(String)"
  * "toSequence(Thing)"

For the programmer
==================

The object toSequence, is a compiled function.

TotalPairs -- whether to display the total number of S-pairs
************************************************************

Description
===========

TotalPairs -- an option for status, which specifies whether to
display the total number of S-pairs.

Functions with optional argument named TotalPairs:
==================================================

  * "status(...,TotalPairs=>...)" -- see status, -- status of a
    resolution computation

For the programmer
==================

The object TotalPairs, is a symbol.

toUpper -- convert to upper case
********************************

Synopsis
========

  * Usage:
        toUpper s
  * Inputs:
      * s, a string,
  * Outputs:
      * a string, the string produced from s by converting its
        characters to lower case

Description
===========

+--------------------------+
|i1 : toUpper "A b C d E f"|
|                          |
|o1 = A B C D E F          |
+--------------------------+

For the programmer
==================

The object toUpper, is a function closure.

trace(Matrix) -- trace of a matrix
**********************************

Synopsis
========

  * Function: trace,

Description
===========

trace f -- returns the trace of the matrix f.

+-----------------------------+
|i1 : R = ZZ/101[a..d]        |
|                             |
|o1 = R                       |
|                             |
|o1 : PolynomialRing          |
+-----------------------------+
|i2 : p = matrix {{a,b},{c,d}}|
|                             |
|o2 = | a b |                 |
|     | c d |                 |
|                             |
|             2      2        |
|o2 : Matrix R  <-- R         |
+-----------------------------+
|i3 : trace p                 |
|                             |
|o3 = a + d                   |
|                             |
|o3 : R                       |
+-----------------------------+

Ways to use this method:
========================

  * trace(Matrix) -- trace of a matrix

transpose -- transpose a table or a matrix
******************************************

Description
===========

The function transpose transposes a matrix, a map of chain complexes or a
table.

Ways to use transpose:
======================

  * transpose(ChainComplexMap), --
    transpose a map of chain complexes
  * transpose(List) --  transposes a table
  * transpose(Matrix) -- transpose a matrix
  * "transpose(MutableMatrix)" -- see transpose(Matrix),
    -- transpose a matrix

For the programmer
==================

The object transpose, is a method function with a single argument.

transpose(ChainComplexMap) -- transpose a map of chain complexes
****************************************************************

Synopsis
========

  * Function: transpose,
  * Usage:
        transpose f
  * Inputs:
      * f, a chain complex map,
  * Outputs:
      * a chain complex map, the transpose of f

Description
===========

The output of transpose is a map from the duals of the original source and
target free modules. See the degree of the target module in the following
example
+------------------------------------------+
|i1 : S = ZZ/10007[x,y,z];                 |
+------------------------------------------+
|i2 : F = res ideal vars S;                |
+------------------------------------------+
|i3 : F.dd                                 |
|                                          |
|          1                 3             |
|o3 = 0 : S  <------------- S  : 1         |
|               | x y z |                  |
|                                          |
|          3                        3      |
|     1 : S  <-------------------- S  : 2  |
|               {1} | -y -z 0  |           |
|               {1} | x  0  -z |           |
|               {1} | 0  x  y  |           |
|                                          |
|          3                  1            |
|     2 : S  <-------------- S  : 3        |
|               {2} | z  |                 |
|               {2} | -y |                 |
|               {2} | x  |                 |
|                                          |
|          1                               |
|     3 : S  <----- 0 : 4                  |
|               0                          |
|                                          |
|o3 : ChainComplexMap                      |
+------------------------------------------+
|i4 : transpose F.dd                       |
|                                          |
|                    1                     |
|o4 = -4 : 0 <----- S  : -3                |
|               0                          |
|                                          |
|           1                       3      |
|     -3 : S  <------------------- S  : -2 |
|                {-3} | z -y x |           |
|                                          |
|           3                        3     |
|     -2 : S  <-------------------- S  : -1|
|                {-2} | y -x 0  |          |
|                {-2} | z 0  -x |          |
|                {-2} | 0 z  -y |          |
|                                          |
|           3                  1           |
|     -1 : S  <-------------- S  : 0       |
|                {-1} | x |                |
|                {-1} | y |                |
|                {-1} | z |                |
|                                          |
|o4 : ChainComplexMap                      |
+------------------------------------------+
Note that M2 treats the differentials of a chain complex map as map of degree
-1.

Ways to use this method:
========================

  * transpose(ChainComplexMap), --
    transpose a map of chain complexes

transpose(List) --  transposes a table
**************************************

Synopsis
========

  * Function: transpose,
  * Usage:
        transpose T
  * Inputs:
      * T, a list, which must be a table,
  * Outputs:
      * the transpose of the table T

Description
===========

Here is an example.
+-----------------------------------+
|i1 : transpose{{a, b, c},{d, e, f}}|
|                                   |
|o1 = {{a, d}, {b, e}, {c, f}}      |
|                                   |
|o1 : List                          |
+-----------------------------------+

Ways to use this method:
========================

  * transpose(List) --  transposes a table

transpose(Matrix) -- transpose a matrix
***************************************

Synopsis
========

  * Function: transpose,
  * Usage:
        transpose f
  * Inputs:
      * f, a matrix,
  * Outputs:
      * a matrix, the transpose of f

Description
===========

Here is an example.
+----------------------------------------+
|i1 : S = ZZ/10007[x,y,z];               |
+----------------------------------------+
|i2 : f = matrix{{x^3,x*y^2},{y*x^2,y^3}}|
|                                        |
|o2 = | x3  xy2 |                        |
|     | x2y y3  |                        |
|                                        |
|             2      2                   |
|o2 : Matrix S  <-- S                    |
+----------------------------------------+
|i3 : g = transpose f                    |
|                                        |
|o3 = {-3} | x3  x2y |                   |
|     {-3} | xy2 y3  |                   |
|                                        |
|             2      2                   |
|o3 : Matrix S  <-- S                    |
+----------------------------------------+
The output of transpose is a map between the duals of the original source and
target free modules. See:
+-------------------------------+
|i4 : degrees f                 |
|                               |
|o4 = {{{0}, {0}}, {{3}, {3}}}  |
|                               |
|o4 : List                      |
+-------------------------------+
|i5 : degrees g                 |
|                               |
|o5 = {{{-3}, {-3}}, {{0}, {0}}}|
|                               |
|o5 : List                      |
+-------------------------------+

Caveat
======

transpose works only for maps between free modules. Use dual for more general
maps.

See also
========

  * dual -- dual module or map

Ways to use this method:
========================

  * transpose(Matrix) -- transpose a matrix
  * "transpose(MutableMatrix)"

trim -- minimize generators and relations
*****************************************

Description
===========

There are two ways to present an $R$-module $M$. One way is to take a free
module $F$ (whose generators are called the generators) and
form the quotient $M = F/H$ by a submodule $H\subset F$ (whose generators are
called the relations).

Another way is take a free module $F$, a submodule $G\subset F$ (whose
generators are called the generators), a submodule $H\subset
F$ (whose generators are called the relations), and form the
subquotient module, $M = (G+H)/H$, obtained also as
the image of $G$ in $F/H$.

The purpose of trim is to minimize presentations of the latter type. This
applies also to rings and ideals.

+------------------------------------------------------+
|i1 : R = ZZ/101[x,y,z,u,w]                            |
|                                                      |
|o1 = R                                                |
|                                                      |
|o1 : PolynomialRing                                   |
+------------------------------------------------------+
|i2 : I = ideal(x^2-x^2-y^2, z^2+x*y, w^2-u^2, x^2-y^2)|
|                                                      |
|              2         2     2    2   2    2         |
|o2 = ideal (-y , x*y + z , - u  + w , x  - y )        |
|                                                      |
|o2 : Ideal of R                                       |
+------------------------------------------------------+
|i3 : trim I                                           |
|                                                      |
|             2    2   2         2   2                 |
|o3 = ideal (u  - w , y , x*y + z , x )                |
|                                                      |
|o3 : Ideal of R                                       |
+------------------------------------------------------+
|i4 : trim (R^1/I)                                     |
|                                                      |
|o4 = cokernel | u2-w2 y2 xy+z2 x2 |                   |
|                                                      |
|                            1                         |
|o4 : R-module, quotient of R                          |
+------------------------------------------------------+
+-----------------------------------------------------+
|i5 : R = ZZ/32003[a..d]                              |
|                                                     |
|o5 = R                                               |
|                                                     |
|o5 : PolynomialRing                                  |
+-----------------------------------------------------+
|i6 : M = coker matrix {{a,1,b},{c,3,b+d}}            |
|                                                     |
|o6 = cokernel | a 1 b   |                            |
|              | c 3 b+d |                            |
|                                                     |
|                            2                        |
|o6 : R-module, quotient of R                         |
+-----------------------------------------------------+
|i7 : trim M                                          |
|                                                     |
|o7 = subquotient (| 1 |, | 10668 b+16001d a-10668c |)|
|                  | 0 |  | 1     0        0        | |
|                                                     |
|                               2                     |
|o7 : R-module, subquotient of R                      |
+-----------------------------------------------------+
|i8 : prune M                                         |
|                                                     |
|o8 = cokernel | b+16001d a-10668c |                  |
|                                                     |
|                            1                        |
|o8 : R-module, quotient of R                         |
+-----------------------------------------------------+

See also
========

  * prune -- prune, e.g., compute a minimal presentation
  * mingens -- minimal generator matrix
  * subquotient modules -- the way Macaulay2
    represents modules
  * generators -- provide matrix or list of generators
  * relations -- the defining relations
  * subquotient -- make a subquotient module

Ways to use trim:
=================

  * "trim(Ideal)"
  * "trim(Module)"
  * "trim(MonomialIdeal)"
  * "trim(QuotientRing)"
  * "trim(Ring)"

For the programmer
==================

The object trim, is a method function with options.

true
****

Description
===========

true is a value indicating truth.

For the programmer
==================

The object true, is a Boolean value.

truncate
********

Description
===========

This function is a method function, defined in the core so multiple packages
can add methods to it.

See also
========

  * Truncations -- truncations of graded ring, ideals
    and modules

Ways to use truncate:
=====================

  * truncate(BettiTally,InfiniteNumber,InfiniteNumber) (missing documentation)
  * truncate(BettiTally,InfiniteNumber,ZZ) (missing documentation)
  * truncate(BettiTally,ZZ,InfiniteNumber) (missing documentation)
  * truncate(BettiTally,ZZ,ZZ) (missing documentation)
  * truncate(Cone,List,ZZ) (missing documentation)
  * truncate(InfiniteNumber,Thing) (missing documentation)
  * truncate(List,Matrix) (Truncations), --
    truncation of a map of free modules
  * "truncate(ZZ,Matrix)" -- see truncate(List,Matrix) (Truncations),
    -- truncation of a map of free
    modules
  * "truncate(List,Ideal)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * truncate(List,Module) (Truncations), --
    truncation of the graded ring, ideal or module at a specified degree or set
    of degrees
  * "truncate(List,Ring)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * "truncate(ZZ,Ideal)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * "truncate(ZZ,Module)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * "truncate(ZZ,Ring)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * truncate(Number) -- round a number toward zero

For the programmer
==================

The object truncate, is a method function with options.

truncate(Number) -- round a number toward zero
**********************************************

Synopsis
========

  * Function: truncate,
  * Usage:
        truncate x
  * Inputs:
      * x, a number,
  * Outputs:
      * an integer, the truncation of x;

Description
===========

The given number is rounded toward zero.

+-------------------+
|i1 : truncate 3.7  |
|                   |
|o1 = 3             |
+-------------------+
|i2 : truncate(-3.7)|
|                   |
|o2 = -3            |
+-------------------+

For complex numbers, the real part is truncated.

+-----------------------+
|i3 : truncate(2.5 + ii)|
|                       |
|o3 = 2                 |
+-----------------------+

See also
========

  * floor(Number) -- floor function
  * ceiling(Number) -- ceiling function

Ways to use this method:
========================

  * truncate(Number) -- round a number toward zero

truncateOutput
**************

Synopsis
========

  * Usage:
        truncateOutput w
  * Inputs:
      * w, an integer,
  * Consequences:
      * The maximum output line width is set to w, which should be an integer
        or infinity. This function works by assigning a value
        to Thing#{Standard,BeforePrint}, which may conflict with other
        BeforePrint, methods installed by the user, or those
        installed by the system that do line wrapping.

Ways to use truncateOutput:
===========================

  * "truncateOutput(InfiniteNumber)"
  * "truncateOutput(ZZ)"

For the programmer
==================

The object truncateOutput, is a method function.

tutorial -- convert documentation from tutorial format
******************************************************

Synopsis
========

  * Usage:
        tutorial x
  * Inputs:
      * x, a string, documentation in tutorial format
  * Outputs:
      * documentation in hypertext format

Description
===========

Some of the Macaulay2 documentation is written in this format.

+-----------------------------------------------------------------------------+
|i1 : ///-- We can compute $(x+y)^3$ as follows.                              |
|     R = QQ[x,y]                                                             |
|     (x+y)^3                                                                 |
|     ///                                                                     |
|                                                                             |
|o1 = -- We can compute $(x+y)^3$ as follows.                                 |
|     R = QQ[x,y]                                                             |
|     (x+y)^3                                                                 |
+-----------------------------------------------------------------------------+
|i2 : tutorial oo                                                             |
|                                                                             |
|                                            +---------------+                |
|o2 = {We can compute $(x+y)^3$ as follows., |  R = QQ[x,y]  |}               |
|                                            +---------------+                |
|                                            |  (x+y)^3      |                |
|                                            +---------------+                |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : peek oo                                                                 |
|                                                                             |
|o3 = {PARA{TEX{"We can compute $(x+y)^3$ as follows."}}, TABLE{class =>      |
|     ------------------------------------------------------------------------|
|     examples, TR{TD{ExampleItem{"R = QQ[x,y]"}}},                           |
|     ------------------------------------------------------------------------|
|     TR{TD{ExampleItem{"(x+y)^3"}}}}}                                        |
+-----------------------------------------------------------------------------+

For the programmer
==================

The object tutorial, is a function closure.

typicalValues -- types of values returned by functions
******************************************************

Description
===========

A hash table used to store information about the type of values typically
returned by functions and methods.

This information is used only to build documentation automatically.
+-------------------------+
|i1 : typicalValues#isRing|
|                         |
|o1 = Boolean             |
|                         |
|o1 : Type                |
+-------------------------+

See also
========

  * specifying typical values

For the programmer
==================

The object typicalValues, is a mutable hash table.

ultimate -- ultimate value for an iteration
*******************************************

Description
===========

ultimate(f,x) -- yields the value ultimately obtained by applying the function
f to x.

Iteration ceases when an error occurs during application of the function, or
the result is the same.  Errors are not reported.

It's a bad idea to use this function, because unexpected errors will produce
unexpected results silently.

Ways to use ultimate:
=====================

  * "ultimate(Function,Thing)"

For the programmer
==================

The object ultimate, is a method function.

unbag(Bag)
**********

Synopsis
========

  * Function: unbag,
  * Usage:
        unbag y
  * Inputs:
      * y
  * Outputs:
      * the contents of y

Description
===========

+-----------------------------------------------------------------------------+
|i1 : x = 100!                                                                |
|                                                                             |
|o1 = 933262154439441526816992388562667004907159682643816214685929638952175999|
|     932299156089414639761565182862536979208272237582511852109168640000000000|
|     00000000000000                                                          |
+-----------------------------------------------------------------------------+
|i2 : y = Bag {x}                                                             |
|                                                                             |
|o2 = -*a bagged integer*-                                                    |
|                                                                             |
|o2 : Bag                                                                     |
+-----------------------------------------------------------------------------+
|i3 : unbag y                                                                 |
|                                                                             |
|o3 = 933262154439441526816992388562667004907159682643816214685929638952175999|
|     932299156089414639761565182862536979208272237582511852109168640000000000|
|     00000000000000                                                          |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * unbag(Bag)

uncurry -- uncurry a function
*****************************

Description
===========

uncurry(f, (a,b))     -- computes ((f a) b).
uncurry(f, (a,b,c))   -- computes (((f a) b) c).
uncurry(f, (a,b,c,d)) -- computes ((((f a) b) c) d).
... and so on.
+-------------------------------+
|i1 : f = a -> b -> c -> [a,b,c]|
|                               |
|o1 = f                         |
|                               |
|o1 : FunctionClosure           |
+-------------------------------+
|i2 : uncurry(f, (1,2,3))       |
|                               |
|o2 = [1, 2, 3]                 |
|                               |
|o2 : Array                     |
+-------------------------------+

For the programmer
==================

The object uncurry, is a compiled function.

undocumented -- declare that something need not be documented
*************************************************************

Synopsis
========

  * Usage:
        undocumented key
  * Inputs:
      * key, a thing, a documentation key, or a list of keys
  * Consequences:
      * the documentation key(s) are designated as keys not needing
        documentation, thus avoiding warning messages when a package is
        installed.

Description
===========

+---------------------------------------------+
|i1 : f = method()                            |
|                                             |
|o1 = f                                       |
|                                             |
|o1 : MethodFunction                          |
+---------------------------------------------+
|i2 : f List := x -> 1                        |
|                                             |
|o2 = FunctionClosure[currentString:2:10-2:16]|
|                                             |
|o2 : FunctionClosure                         |
+---------------------------------------------+
|i3 : f VisibleList := x -> 2                 |
|                                             |
|o3 = FunctionClosure[currentString:3:17-3:23]|
|                                             |
|o3 : FunctionClosure                         |
+---------------------------------------------+
|i4 : f BasicList := x -> 3                   |
|                                             |
|o4 = FunctionClosure[currentString:4:15-4:21]|
|                                             |
|o4 : FunctionClosure                         |
+---------------------------------------------+
|i5 : undocumented { f, (f,List) }            |
+---------------------------------------------+

See also
========

  * installPackage -- load and install a package and its
    documentation
  * documentation keys

Ways to use undocumented:
=========================

  * "undocumented(List)"
  * "undocumented(Thing)"

For the programmer
==================

The object undocumented, is a method function with a single argument.

uniform -- whether all elements of a list are the same class
************************************************************

Synopsis
========

  * Usage:
        uniform L
  * Inputs:
      * L, a list,
  * Outputs:
      * a Boolean value, whether all elements of L are of the
        same class,

Description
===========

+--------------------------------+
|i1 : uniform {2, 5, 0}          |
|                                |
|o1 = true                       |
+--------------------------------+
|i2 : uniform {2*0.5, 5*0.5, 0/2}|
|                                |
|o2 = false                      |
+--------------------------------+

The second list is not uniform because 0/2 is represented as a rational number
(of class QQ), while 2*0.5 and 5*0.5 are represented as real numbers
(of class RR).

+-------------------------------------------------+
|i3 : uniform {hi, "hello"}                       |
|                                                 |
|o3 = false                                       |
+-------------------------------------------------+
|i4 : uniform {"hi", "hello"}                     |
|                                                 |
|o4 = true                                        |
+-------------------------------------------------+
|i5 : R = QQ[x,y,z];                              |
+-------------------------------------------------+
|i6 : uniform {x^2*y*z, 5*y, 12/7}                |
|                                                 |
|o6 = false                                       |
+-------------------------------------------------+
|i7 : uniform {x^2*y*z, 5*y, (12/7)_R}            |
|                                                 |
|o7 = true                                        |
+-------------------------------------------------+
|i8 : S = ZZ[t];                                  |
+-------------------------------------------------+
|i9 : uniform {monomialIdeal(x), monomialIdeal(t)}|
|                                                 |
|o9 = true                                        |
+-------------------------------------------------+
|i10 : uniform {monomialIdeal(t), ideal(t)}       |
|                                                 |
|o10 = false                                      |
+-------------------------------------------------+
|i11 : uniform {S/monomialIdeal(t), S/ideal(t)}   |
|                                                 |
|o11 = true                                       |
+-------------------------------------------------+

See also
========

  * all -- whether all elements satisfy a specified condition
  * any -- whether any elements satisfy a specified condition
  * instance -- whether something has a certain type
  * same -- whether everything in a list is the same
  * select -- select from a list, hash table, or string
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

For the programmer
==================

The object uniform, is a function closure.

union(Set,Set) -- set union
***************************

Synopsis
========

  * Function: union (Posets),
  * Usage:
        x + y
  * Inputs:
      * x
      * y
  * Outputs:
      * a set, the union of x and y

Description
===========

+----------------------------------------------+
|i1 : set{a,b,c} + set{a,d,f}                  |
|                                              |
|o1 = set {c, d, f, a, b}                      |
|                                              |
|o1 : Set                                      |
+----------------------------------------------+
|i2 : union(set{a,b,c}, set{a,d,f}, set{a,c,e})|
|                                              |
|o2 = set {c, d, e, f, a, b}                   |
|                                              |
|o2 : Set                                      |
+----------------------------------------------+

The function sum can be used to form the union of a list of sets, but this can
be slow for long lists.

+--------------------------------------------------------+
|i3 : x = apply(3, i -> set apply(3, j -> 10*i+j))       |
|                                                        |
|o3 = {set {0, 1, 2}, set {12, 10, 11}, set {20, 21, 22}}|
|                                                        |
|o3 : List                                               |
+--------------------------------------------------------+
|i4 : sum x                                              |
|                                                        |
|o4 = set {0, 1, 2, 20, 21, 22, 10, 11, 12}              |
|                                                        |
|o4 : Set                                                |
+--------------------------------------------------------+

See also
========

  * Set -- the class of all sets

Ways to use this method:
========================

  * union(Set,Set) -- set union

Unique -- do not return repeated polynomial roots
*************************************************

Description
===========

A booleanBoolean, to select whether to return repeated roots or
not.

Functions with optional argument named Unique:
==============================================

  * "roots(RingElement,Unique=>...)" -- see roots(RingElement),
    -- compute the roots of a polynomial

For the programmer
==================

The object Unique, is a symbol.

unique -- eliminate duplicates from a list
******************************************

Synopsis
========

  * Usage:
        unique(L)
  * Inputs:
      * L, a list, or sequence
  * Outputs:
      * M, a list, the elements of L without duplicates

Description
===========

The output list maintains the order of elements in L.

+------------------------------------------+
|i1 : unique {3,2,1,3,2,4,a,3,2,3,-2,1,2,4}|
|                                          |
|o1 = {3, 2, 1, 4, a, -2}                  |
|                                          |
|o1 : List                                 |
+------------------------------------------+

Another way to list the unique elements of L is by creating a set from L and
then listing its elements. This may be slightly faster than unique, but forgets
the ordering of L.

+----------------------------------------------+
|i2 : toList set {3,2,1,3,2,4,a,3,2,3,-2,1,2,4}|
|                                              |
|o2 = {1, 2, 3, 4, -2, a}                      |
|                                              |
|o2 : List                                     |
+----------------------------------------------+

To count occurrences of each element, use tally. To create a
sorted list, see sort. For an overview of lists and sequences, see
lists and sequences.

See also
========

  * same -- whether everything in a list is the same
  * sort -- sort a list or columns of a matrix
  * set -- make a set
  * tally -- tally the elements of a list, sequence, array, or
    string
  * uniform -- whether all elements of a list are the same
    class
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use unique:
===================

  * "unique(VisibleList)"

For the programmer
==================

The object unique, is a method function with a single argument.

uniquePermutations -- produce all unique permutations of a list
***************************************************************

Synopsis
========

  * Usage:
        uniquePermutations x
  * Inputs:
      * x, a visible list, or an integer,
  * Outputs:
      * a list of all distinct permutations of the visible list x, or, if x is
        an integer, of the list of integers from 0 through n-1

Description
===========

+-----------------------------------------------------------------------------+
|i1 : uniquePermutations {a,b,a,b}                                            |
|                                                                             |
|o1 = {{a, b, a, b}, {a, b, b, a}, {a, a, b, b}, {b, a, a, b}, {b, a, b, a},  |
|     ------------------------------------------------------------------------|
|     {b, b, a, a}}                                                           |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+

Ways to use uniquePermutations:
===============================

  * "uniquePermutations(VisibleList)"
  * "uniquePermutations(ZZ)"

For the programmer
==================

The object uniquePermutations, is a method function.

unsequence -- extract the single element from a sequence of length 1
********************************************************************

Synopsis
========

  * Usage:
        unsequence x
  * Inputs:
      * x, a thing,
  * Outputs:
      * x#0, if x is a sequence of length 1, otherwise x

Description
===========

+---------------------+
|i1 : unsequence (2:a)|
|                     |
|o1 = (a, a)          |
|                     |
|o1 : Sequence        |
+---------------------+
|i2 : unsequence (1:a)|
|                     |
|o2 = a               |
|                     |
|o2 : Symbol          |
+---------------------+
|i3 : unsequence (0:a)|
|                     |
|o3 = ()              |
|                     |
|o3 : Sequence        |
+---------------------+

See also
========

  * sequence -- make a sequence

For the programmer
==================

The object unsequence, is a compiled function.

UpdateOnly -- only copies of newer files should replace files
*************************************************************

Functions with optional argument named UpdateOnly:
==================================================

  * "copyDirectory(...,UpdateOnly=>...)" -- see
    copyDirectory(String,String),
  * "copyFile(...,UpdateOnly=>...)" -- see copyFile(String,String),

For the programmer
==================

The object UpdateOnly, is a symbol.

URL -- a type representing a URL
********************************

Synopsis
========

  * Usage:
        URL str
  * Inputs:
      * str, a string, a URL
  * Outputs:
      * an instance of the type URL,

Description
===========

The function show, knows how to display entities of various types,
including URLs.

See also
========

  * show -- display various objects in an external viewer

Methods that use an object of class URL:
========================================

  * "show(URL)" -- see show, -- display various objects in an
    external viewer
  * "new URL from String"

For the programmer
==================

The object URL, is a self initializing type,
with ancestor classes BasicList, <
Thing.

urlEncode -- URL encoding
*************************

Synopsis
========

  * Usage:
        urlEncode s
  * Inputs:
      * s, a string,
  * Outputs:
      * a string,

Description
===========

Encode all of the characters in a URL except for "/", ":", "#", and the
"unreserved characters" specified by RFC 3986 (see
https://www.rfc-editor.org/rfc/rfc3986.html ), i.e., the alphanumeric
characters, "-", ".", "_", and "~", using percent-encoding (see
https://en.wikipedia.org/wiki/percent-encoding ), a "%" followed by two
hexadecimal digits representing the ASCII encoding of the character.

+------------------------------------------------------------+
|i1 : urlEncode "https://en.wikipedia.org/wiki/Gröbner basis"|
|                                                            |
|o1 = https://en.wikipedia.org/wiki/Gr%C3%B6bner%20basis     |
+------------------------------------------------------------+

Ways to use urlEncode:
======================

  * "urlEncode(Nothing)"
  * "urlEncode(String)"

For the programmer
==================

The object urlEncode, is a method function.

use -- install or activate object
*********************************

Ways to use use:
================

  * use(Package) -- activate a previously dismissed
    package
  * "use(Monoid)" -- see use(Ring), -- install ring
    variables and ring operations
  * use(Ring) -- install ring variables and ring
    operations

For the programmer
==================

The object use, is a method function with a single argument.

use(Ring) -- install ring variables and ring operations
*******************************************************

Synopsis
========

  * Function: use,
  * Usage:
        use R
  * Inputs:
      * R, a ring, or a monoid,
  * Consequences:
      * All variables of R are set to global variables.  Additionally, certain
        operations creating elements of R are installed globally.

Description
===========

When a ring (or a monoid) is assigned to a global variable, this function is
automatically called for it.

It is possible to have several polynomial rings defined, perhaps with a
variable belonging to several rings.
+--------------------+
|i1 : R = QQ[a..d]   |
|                    |
|o1 = R              |
|                    |
|o1 : PolynomialRing |
+--------------------+
|i2 : S = QQ[b,c,d,e]|
|                    |
|o2 = S              |
|                    |
|o2 : PolynomialRing |
+--------------------+
|i3 : b              |
|                    |
|o3 = b              |
|                    |
|o3 : S              |
+--------------------+
At this point, b is thought to be a variable of S.  If one typed a+b, an error
would occur, since Macaulay2 doesn't know how to add elements of R and S
together.  This is fixed via:
+-------------------+
|i4 : use R         |
|                   |
|o4 = R             |
|                   |
|o4 : PolynomialRing|
+-------------------+
|i5 : b             |
|                   |
|o5 = b             |
|                   |
|o5 : R             |
+-------------------+
|i6 : a+b           |
|                   |
|o6 = a + b         |
|                   |
|o6 : R             |
+-------------------+

There are several functions that create rings for you.  Generally, their
variables are not globally visible.  However, once you 'use' the ring, the
variables are available.For example, the numerator of the Hilbert function is a
polynomial in a ring with a variable T.
+-------------------------------+
|i7 : T                         |
|                               |
|o7 = T                         |
|                               |
|o7 : Symbol                    |
+-------------------------------+
|i8 : hf = poincare ideal vars S|
|                               |
|                2     3    4   |
|o8 = 1 - 4T + 6T  - 4T  + T    |
|                               |
|o8 : ZZ[T]                     |
+-------------------------------+
|i9 : T                         |
|                               |
|o9 = T                         |
|                               |
|o9 : Symbol                    |
+-------------------------------+
|i10 : use ring hf              |
|                               |
|o10 = ZZ[T]                    |
|                               |
|o10 : PolynomialRing           |
+-------------------------------+
|i11 : T                        |
|                               |
|o11 = T                        |
|                               |
|o11 : Symbol                   |
+-------------------------------+

Caveat
======

Any values stored in the variables that have been assigned to are lost, hence
this operation should not be used by code in a package.

See also
========

  * GlobalAssignHook -- hook for assignment to global
    variables

Ways to use this method:
========================

  * "use(Monoid)"
  * use(Ring) -- install ring variables and ring
    operations

userSymbols -- a list of the user's symbols
*******************************************

Synopsis
========

  * Usage:
        userSymbols ()
  * Outputs:
      * a list,  a list of symbols

Description
===========

userSymbols () provides a list of symbols defined by the user.
userSymbols X limits the list to those symbols whose values are instances of
the class, X.

Protected symbols are excluded from the list.

See also
========

  * listUserSymbols -- display the user's symbols

For the programmer
==================

The object userSymbols, is a function closure.

utf8substring -- extract part of a utf8 string
**********************************************

Synopsis
========

  * Usage:
        utf8substring(s, i, n)
  * Inputs:
      * s, a string,
      * i, an integer, starting index of substring
      * n, an integer, length of substring
  * Outputs:
      * a string,

Description
===========

Returns the substring of s that starts at index i and has n characters, both
measured in utf8 characters.

+---------------------------+
|i1 : s = "π ≈ 3.14159";    |
+---------------------------+
|i2 : utf8substring(s, 4, 4)|
|                           |
|o2 = 3.14                  |
+---------------------------+

See also
========

  * substring -- extract part of a string

For the programmer
==================

The object utf8substring, is a compiled function.

value -- evaluate
*****************

Ways to use value:
==================

  * "value(Expression)" -- see Expression, -- the class of
    all expressions
  * value(IndexedVariable) -- retrieve the
    value of an indexed variable
  * value(Pseudocode) -- execute pseudocode
  * value(String) -- evaluate a string
  * value(Symbol) -- retrieve the value of a symbol

For the programmer
==================

The object value, is a method function.

value(IndexedVariable) -- retrieve the value of an indexed variable
*******************************************************************

Synopsis
========

  * Function: value,
  * Usage:
        value s
  * Inputs:
      * s
  * Outputs:
      * the value of s

Description
===========

+--------------------+
|i1 : y = x_3        |
|                    |
|o1 = x              |
|      3             |
|                    |
|o1 : IndexedVariable|
+--------------------+
|i2 : x_3 = 4        |
|                    |
|o2 = 4              |
+--------------------+
|i3 : x_3            |
|                    |
|o3 = 4              |
+--------------------+
|i4 : y              |
|                    |
|o4 = x              |
|      3             |
|                    |
|o4 : IndexedVariable|
+--------------------+
|i5 : value y        |
|                    |
|o5 = 4              |
+--------------------+

Ways to use this method:
========================

  * value(IndexedVariable) -- retrieve the
    value of an indexed variable

value(Pseudocode) -- execute pseudocode
***************************************

Synopsis
========

  * Function: value,
  * Usage:
        value p
  * Inputs:
      * p
  * Outputs:
      * the value returned by evaluation of p

Description
===========

Here is an example of its use in the debugger, to see whether modifying the
value of a local variable fixed the problem in the code, by executing just the
offending line.

+-----------------------------------------------------------------------------+
|i1 : load "Macaulay2Doc/demo1.m2"                                            |
+-----------------------------------------------------------------------------+
|i2 : g 2                                                                     |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3):[2]:               |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:                            |
|8:10-8:13: --source code:                                                    |
|     b := 1/x;                                                               |
|-----------------------------------------------------------------------------|
|error: division by zero                                                      |
|--entering debugger (type help to see debugger commands)                     |
+-----------------------------------------------------------------------------+
|ii3 : value current                                                          |
|/usr/local/share/Macaulay2/Macaulay2Doc/demo1.m2:8:11:(3): error: division by|
|-----------------------------------------------------------------------------|
|zero                                                                         |
+-----------------------------------------------------------------------------+
|ii4 : x = 11                                                                 |
|                                                                             |
|oo4 = 11                                                                     |
+-----------------------------------------------------------------------------+
|ii5 : value current                                                          |
|                                                                             |
|       1                                                                     |
|oo5 = --                                                                     |
|      11                                                                     |
|                                                                             |
|oo5 : QQ                                                                     |
+-----------------------------------------------------------------------------+

See also
========

  * current -- the pseudocode that produced an error
  * pseudocode -- produce the pseudocode for a function

Ways to use this method:
========================

  * value(Pseudocode) -- execute pseudocode

value(String) -- evaluate a string
**********************************

Synopsis
========

  * Function: value,
  * Usage:
        value s
  * Inputs:
      * s
  * Outputs:
      * the value obtained by evaluating the code in s

Description
===========

The contents of s are treated as code in the Macaulay2 language, parsed it in
its own scope (the same way a file is) and evaluated.  The string may contain
multiple lines.
+-------------------+
|i1 : value "2 + 2" |
|                   |
|o1 = 4             |
+-------------------+
|i2 : value "a := 33|
|     a+a"          |
|                   |
|o2 = 66            |
+-------------------+
|i3 : a             |
|                   |
|o3 = a             |
|                   |
|o3 : Symbol        |
+-------------------+
Since the local assignment to a above occurred in a new scope, the value of the
global variable a is unaffected.

During evaluation of the string, error messages will refer to the location of
the error as currentString with a line number and a column number, and the
value of the variable currentString, is set to the
string, to aid in debugging.

+-----------------------------------------------------------------------------+
|i4 : debuggingMode = stopIfError = false;                                    |
+-----------------------------------------------------------------------------+
|i5 : value "1/0"                                                             |
|currentString:1:1:(3):[1]: error: division by zero                           |
+-----------------------------------------------------------------------------+
|i6 : debuggingMode = true;                                                   |
+-----------------------------------------------------------------------------+
|i7 : value "1/0"                                                             |
|currentString:1:1:(3):[1]: error: division by zero                           |
|currentString:1:1:(3):[1]: --entering debugger (type help to see debugger    |
|currentString:1:0-1:3: --source code:                                        |
|1/0                                                                          |
|-----------------------------------------------------------------------------|
|commands)                                                                    |
+-----------------------------------------------------------------------------+
|ii8 : break                                                                  |
+-----------------------------------------------------------------------------+

See also
========

  * debugging
  * stopIfError -- whether to stop the program when an
    error occurs
  * debuggingMode -- whether to enter the debugger when
    an error occurs

Ways to use this method:
========================

  * value(String) -- evaluate a string

value(Symbol) -- retrieve the value of a symbol
***********************************************

Synopsis
========

  * Function: value,
  * Usage:
        value s
  * Inputs:
      * s
  * Outputs:
      * the value of s

Description
===========

+--------------------+
|i1 : x = s          |
|                    |
|o1 = s              |
|                    |
|o1 : Symbol         |
+--------------------+
|i2 : s = 11111111111|
|                    |
|o2 = 11111111111    |
+--------------------+
|i3 : x              |
|                    |
|o3 = s              |
|                    |
|o3 : Symbol         |
+--------------------+
|i4 : value x        |
|                    |
|o4 = 11111111111    |
+--------------------+

Ways to use this method:
========================

  * value(Symbol) -- retrieve the value of a symbol

Variable -- specify a name for a variable
*****************************************

Description
===========

Variable => x -- an option used with GF, to specify a symbol to be
used as a name for the generator of the Galois field.

Functions with optional argument named Variable:
================================================

  * conwayPolynomial(...,Variable=>...) (missing documentation)
  * "GF(...,Variable=>...)" -- see GF, -- make a finite field
  * "Grassmannian(...,Variable=>...)" -- see Grassmannian(ZZ,ZZ),
    -- the Grassmannian of linear subspaces of a
    vector space
  * idealizer(...,Variable=>...) (IntegralClosure)
    -- Sets
    the name of the indexed variables introduced in computing the endomorphism
    ring Hom(J,J).
  * integralClosure(...,Variable=>...) (IntegralClosure),
    --
    set the base letter for the indexed variables introduced while computing
    the integral closure
  * "intersectInP(...,Variable=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "multiplicity(...,Variable=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * makeS2(...,Variable=>...) (IntegralClosure)
    -- Sets the
    name of the indexed variables introduced in computing the S2-ification.
  * "ringFromFractions(...,Variable=>...)" -- see ringFromFractions (IntegralClosure),
    -- find presentation for f.g. ring
  * "Schubert(...,Variable=>...)" -- see Schubert(ZZ,ZZ,VisibleList),
    -- find the Plücker ideal of a
    Schubert variety
  * "associatedGradedRing(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "distinguished(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "isReduction(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "jacobianDual(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "normalCone(Ideal,RingElement,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "normalCone(Ideal,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "reesAlgebra(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "reesIdeal(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "specialFiber(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "specialFiberIdeal(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring

For the programmer
==================

The object Variable, is a symbol.

vars -- variables
*****************

Ways to use vars:
=================

  * vars(List) -- a sequence of variables
  * "vars(Sequence)" -- see vars(List), -- a sequence of
    variables
  * "vars(ZZ)" -- see vars(List), -- a sequence of
    variables
  * vars(Monoid) -- list of variables in a monoid
  * vars(Ring) -- row matrix of the variables

For the programmer
==================

The object vars, is a method function with a single argument.

vars(List) -- a sequence of variables
*************************************

Synopsis
========

  * Function: vars,
  * Usage:
        vars L
  * Inputs:
      * L, , integer, or sequence, of integers
  * Outputs:
      * a sequence, which consists of symbols,
        which can be used as indeterminates

Description
===========

The symbols, returned are single letters, or the letter x or X
followed by some digits.  There is no limit on the size or sign of the integers
in L.
+-----------------------------------------------------------------------------+
|i1 : vars{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25|
|                                                                             |
|o1 = {a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x,|
|     ------------------------------------------------------------------------|
|     y, z}                                                                   |
|                                                                             |
|o1 : List                                                                    |
|-----------------------------------------------------------------------------|
|}                                                                            |
+-----------------------------------------------------------------------------+
|i2 : vars(26..51)                                                            |
|                                                                             |
|o2 = (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X,|
|     ------------------------------------------------------------------------|
|     Y, Z)                                                                   |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i3 : vars 52                                                                 |
|                                                                             |
|o3 = x0                                                                      |
|                                                                             |
|o3 : Symbol                                                                  |
+-----------------------------------------------------------------------------+
|i4 : vars(-9..-1)                                                            |
|                                                                             |
|o4 = (X9, X8, X7, X6, X5, X4, X3, X2, X1)                                    |
|                                                                             |
|o4 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i5 : vars(3 .. 9, 33 .. 35, 1000 .. 1002, -100 .. -98)                       |
|                                                                             |
|o5 = (d, e, f, g, h, i, j, H, I, J, x948, x949, x950, X100, X99, X98)        |
|                                                                             |
|o5 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * .. -- a binary operator, used for sequences of consecutive
    items

Ways to use this method:
========================

  * vars(List) -- a sequence of variables
  * "vars(Sequence)"
  * "vars(ZZ)"

vars(Monoid) -- list of variables in a monoid
*********************************************

Synopsis
========

  * Function: vars,
  * Usage:
        vars M
  * Inputs:
      * R
  * Outputs:
      * a list, a list of the generators of M

Description
===========

The result is the same as that provided by generators(Monoid).
+-------------------------+
|i1 : M = monoid[x,y,z]   |
|                         |
|o1 = M                   |
|                         |
|o1 : GeneralOrderedMonoid|
+-------------------------+
|i2 : vars M              |
|                         |
|o2 = {x, y, z}           |
|                         |
|o2 : List                |
+-------------------------+

Ways to use this method:
========================

  * vars(Monoid) -- list of variables in a monoid

vars(Ring) -- row matrix of the variables
*****************************************

Synopsis
========

  * Function: vars,
  * Usage:
        vars R
  * Inputs:
      * R
  * Outputs:
      * a matrix, a matrix with one row whose entries are the
        variables of the ring R

Description
===========

+-----------------------------------------+
|i1 : S = QQ[w,x,y,z];                    |
+-----------------------------------------+
|i2 : vars S                              |
|                                         |
|o2 = | w x y z |                         |
|                                         |
|             1      4                    |
|o2 : Matrix S  <-- S                     |
+-----------------------------------------+
|i3 : ideal vars S                        |
|                                         |
|o3 = ideal (w, x, y, z)                  |
|                                         |
|o3 : Ideal of S                          |
+-----------------------------------------+
|i4 : coker vars S                        |
|                                         |
|o4 = cokernel | w x y z |                |
|                                         |
|                            1            |
|o4 : S-module, quotient of S             |
+-----------------------------------------+
|i5 : res coker vars S                    |
|                                         |
|      1      4      6      4      1      |
|o5 = S  <-- S  <-- S  <-- S  <-- S  <-- 0|
|                                         |
|     0      1      2      3      4      5|
|                                         |
|o5 : ChainComplex                        |
+-----------------------------------------+
|i6 : R = S/(x^2-w*y, x*y-w*z, x*z-y^2);  |
+-----------------------------------------+
|i7 : vars R                              |
|                                         |
|o7 = | w x y z |                         |
|                                         |
|             1      4                    |
|o7 : Matrix R  <-- R                     |
+-----------------------------------------+
|i8 : use S;                              |
+-----------------------------------------+
|i9 : Q = S/(x^2-w*y, z);                 |
+-----------------------------------------+
|i10 : vars S                             |
|                                         |
|o10 = | w x y z |                        |
|                                         |
|              1      4                   |
|o10 : Matrix S  <-- S                    |
+-----------------------------------------+

Ways to use this method:
========================

  * vars(Ring) -- row matrix of the variables

Vector -- the class of all elements of modules that are handled by the engine
*****************************************************************************

Description
===========

If R is a ring handled by the engine, and M is a module over R, then M is a
subclass of Vector.

See also
========

  * engine
  * Module -- the class of all modules

Functions and methods returning a vector:
=========================================

  * "Matrix * Vector" -- see *, -- a binary operator, usually used
    for multiplication
  * "Number * Vector" -- see *, -- a binary operator, usually used
    for multiplication
  * "RingElement * Vector" -- see *, -- a binary operator, usually
    used for multiplication
  * "Vector * Number" -- see *, -- a binary operator, usually used
    for multiplication
  * "Vector * RingElement" -- see *, -- a binary operator, usually
    used for multiplication
  * "+ Vector" -- see +, -- a unary or binary operator, usually used
    for addition
  * "Vector + Vector" -- see +, -- a unary or binary operator, usually
    used for addition
  * "Vector - Vector" -- see -, -- a unary or binary operator, usually
    used for negation or subtraction
  * - Vector -- negation of a Vector
  * "Matrix _ ZZ" -- see generators of ideals and modules,
  * "Module _ ZZ" -- see generators of ideals and modules,
  * "homogenize(Vector,RingElement)" -- see homogenize, --
    homogenize with respect to a variable
  * "homogenize(Vector,RingElement,List)" -- see homogenize,
    -- homogenize with respect to a variable
  * lift(Vector,type of InexactNumber') (missing documentation)
  * lift(Vector,type of InexactNumber) (missing documentation)
  * lift(Vector,type of Number) (missing documentation)
  * lift(Vector,type of RingElement) (missing documentation)
  * "Vector / Number" -- see Matrix / Number, -- scalar
    division
  * "Vector / RingElement" -- see Matrix / Number, --
    scalar division
  * Matrix Vector (missing documentation)
  * random(Module) -- get a random vector in the
    module
  * "RingMap Vector" -- see RingMap RingElement, --
    apply a ring map
  * "substitute(Vector,List)" -- see substitute, --
    substituting values for variables
  * "substitute(Vector,Matrix)" -- see substitute, --
    substituting values for variables
  * "substitute(Vector,Ring)" -- see substitute, --
    substituting values for variables
  * "substitute(Vector,RingFamily)" -- see substitute, --
    substituting values for variables
  * "super(Vector)" -- see super, -- get the ambient module
  * Vector ** Vector -- tensor product
  * Vector || Vector -- join Vectors
  * ZZ _ Module -- integers or zero element

Methods that use a vector:
==========================

  * "Ideal * Vector" -- see *, -- a binary operator, usually used
    for multiplication
  * "Ring * Vector" -- see *, -- a binary operator, usually used for
    multiplication
  * "contract(Matrix,Vector)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Number,Vector)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(RingElement,Vector)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Vector,Matrix)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Vector,Number)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Vector,RingElement)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "contract(Vector,Vector)" -- see contract(Matrix,Matrix),
    -- contract a matrix by a matrix
  * "degree(Vector)" -- see degree(RingElement),
  * "describe(Vector)" -- see describe, -- real description
  * "diff(Matrix,Vector)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * "diff(RingElement,Vector)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * "diff(Vector,Matrix)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * "diff(Vector,RingElement)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * "diff(Vector,Vector)" -- see diff(Matrix,Matrix),
    -- differentiate a matrix by a matrix
  * entries(Vector) -- lists the entries of a
    vector
  * "homomorphism(Vector)" -- see homomorphism, -- get the
    homomorphism from element of Hom
  * "isHomogeneous(Vector)" -- see isHomogeneous, --
    whether something is homogeneous (graded)
  * "leadComponent(Vector)" -- see leadComponent, -- the
    leading component(s) of a vector or matrix
  * leadMonomial(Vector) (missing documentation)
  * "leadTerm(Vector)" -- see leadTerm(Matrix), --
    get the greatest term of each column
  * matrix(Vector) -- make a matrix
  * "Module / Vector" -- see Module / Module, --
    quotient module
  * module(Vector) -- the module of a vector
  * "norm(Vector)" -- see norm,
  * "numeric(Vector)" -- see numeric, -- convert to floating
    point
  * "numeric(ZZ,Vector)" -- see numeric, -- convert to floating
    point
  * "ring(Vector)" -- see ring, -- get the associated ring of an
    object
  * "saturate(Vector)" -- see saturate (Saturation), --
    saturation of ideal or submodule
  * "saturate(Vector,Ideal)" -- see saturate (Saturation), --
    saturation of ideal or submodule
  * "saturate(Vector,RingElement)" -- see saturate (Saturation),
    -- saturation of ideal or submodule
  * solve(Matrix,Vector) (missing documentation)
  * "substitute(Vector,Option)" -- see substitute, --
    substituting values for variables
  * Vector % Ideal (missing documentation)
  * Vector == Vector (missing documentation)
  * Vector ^ List (missing documentation)

For the programmer
==================

The object Vector, is a type, with ancestor classes
BasicList < Thing.

vector -- make a vector
***********************

Synopsis
========

  * Usage:
        vector(M, x)
        vector x
  * Inputs:
      * M, a module,
      * x, a list, a matrix, a number,
        or a ring element,
  * Outputs:
      * a vector,

Description
===========

For any $R$-module $M$, there exists an isomorphism between
$\operatorname{Hom}(R,M)$ and $M$ given by $f\mapsto f(1)$. Therefore,
internally all Vector, objects representing elements of $M$
correspond to matrices with source $R^1$ and target $M$.  A vector may be
constructed from such a matrix using vector.

+-------------------------------+
|i1 : R = QQ[x,y,z]             |
|                               |
|o1 = R                         |
|                               |
|o1 : PolynomialRing            |
+-------------------------------+
|i2 : f = matrix {{x}, {y}, {z}}|
|                               |
|o2 = | x |                     |
|     | y |                     |
|     | z |                     |
|                               |
|             3      1          |
|o2 : Matrix R  <-- R           |
+-------------------------------+
|i3 : vector f                  |
|                               |
|o3 = | x |                     |
|     | y |                     |
|     | z |                     |
|                               |
|      3                        |
|o3 : R                         |
+-------------------------------+

Alternatively, $M$ may be specified if it differs from the target of the
matrix.

+-------------------------------+
|i4 : g = matrix {{1}, {2}, {3}}|
|                               |
|o4 = | 1 |                     |
|     | 2 |                     |
|     | 3 |                     |
|                               |
|              3       1        |
|o4 : Matrix ZZ  <-- ZZ         |
+-------------------------------+
|i5 : vector(R^3, g)            |
|                               |
|o5 = | 1 |                     |
|     | 2 |                     |
|     | 3 |                     |
|                               |
|      3                        |
|o5 : R                         |
+-------------------------------+

If the matrix would have only one element, then that element may be given
instead.  If the module is not provided, then the result will be an element of
the free module of rank one of the ring of the given element.

+-------------------+
|i6 : vector 2      |
|                   |
|o6 = | 2 |         |
|                   |
|       1           |
|o6 : ZZ            |
+-------------------+
|i7 : vector x      |
|                   |
|o7 = | x |         |
|                   |
|      1            |
|o7 : R             |
+-------------------+
|i8 : vector(R^1, 2)|
|                   |
|o8 = | 2 |         |
|                   |
|      1            |
|o8 : R             |
+-------------------+

Alternatively, a list of elements may be provided.  If the module is not
specified, then the vector will be an element of a free module over a ring
containing all the elements of the list.

+----------------------------+
|i9 : vector {1, 2, 3}       |
|                            |
|o9 = | 1 |                  |
|     | 2 |                  |
|     | 3 |                  |
|                            |
|       3                    |
|o9 : ZZ                     |
+----------------------------+
|i10 : vector {1, x, y}      |
|                            |
|o10 = | 1 |                 |
|      | x |                 |
|      | y |                 |
|                            |
|       3                    |
|o10 : R                     |
+----------------------------+
|i11 : vector(R^3, {1, 2, 3})|
|                            |
|o11 = | 1 |                 |
|      | 2 |                 |
|      | 3 |                 |
|                            |
|       3                    |
|o11 : R                     |
+----------------------------+

Ways to use vector:
===================

  * "vector(List)"
  * "vector(Matrix)"
  * "vector(Module,List)"
  * "vector(Module,Matrix)"
  * "vector(Module,Number)"
  * "vector(Module,RingElement)"
  * "vector(Number)"
  * "vector(RingElement)"

For the programmer
==================

The object vector, is a method function.

Vector ** Vector -- tensor product
**********************************

Synopsis
========

  * Operator: **,
  * Usage:
        v ** w
        tensor(v, w)
  * Inputs:
      * v, a vector,
      * w, a vector,
  * Outputs:
      * a vector, the tensor product of $v$ and $w$

Description
===========

If $v$ is in the module $M$ and $w$ is in the module $N$, then $v\otimes w$ is
in the module $M\otimes N$.

+-----------------------------+
|i1 : R = ZZ[a..d];           |
+-----------------------------+
|i2 : F = R^3                 |
|                             |
|      3                      |
|o2 = R                       |
|                             |
|o2 : R-module, free          |
+-----------------------------+
|i3 : G = coker vars R        |
|                             |
|o3 = cokernel | a b c d |    |
|                             |
|                            1|
|o3 : R-module, quotient of R |
+-----------------------------+
|i4 : v = (a-37)*F_1          |
|                             |
|o4 = |   0  |                |
|     | a-37 |                |
|     |   0  |                |
|                             |
|      3                      |
|o4 : R                       |
+-----------------------------+
|i5 : v ** G_0                |
|                             |
|o5 = |  0  |                 |
|     | -37 |                 |
|     |  0  |                 |
|                             |
|o5 : Vector                  |
+-----------------------------+

See also
========

  * flip -- isomorphism map of commutativity of tensor product
  * tensor(Module,Module) -- tensor product
    of modules
  * tensor(Matrix,Module) -- tensor product
  * tensor(Matrix,Matrix) -- tensor product

Ways to use this method:
========================

  * Vector ** Vector -- tensor product

Vector || Vector -- join Vectors
*********************************

Synopsis
========

  * Operator: ||,
  * Usage:
        v || w
  * Inputs:
      * v
      * w
  * Outputs:
      * a vector, obtained from vectors v and w by concatenating
        the columns.

Description
===========

+-----------------------------------+
|i1 : R = (ZZ[x,y,z])^3;            |
+-----------------------------------+
|i2 : v = vector {1,x,x*y,x*z,x*y*z}|
|                                   |
|o2 = |  1  |                       |
|     |  x  |                       |
|     |  xy |                       |
|     |  xz |                       |
|     | xyz |                       |
|                                   |
|               5                   |
|o2 : (ZZ[x..z])                    |
+-----------------------------------+
|i3 : w = vector {z*x,z^2,3}        |
|                                   |
|o3 = | xz |                        |
|     | z2 |                        |
|     |  3 |                        |
|                                   |
|               3                   |
|o3 : (ZZ[x..z])                    |
+-----------------------------------+
|i4 : v || w                        |
|                                   |
|o4 = |  1  |                       |
|     |  x  |                       |
|     |  xy |                       |
|     |  xz |                       |
|     | xyz |                       |
|     |  xz |                       |
|     |  z2 |                       |
|     |  3  |                       |
|                                   |
|               8                   |
|o4 : (ZZ[x..z])                    |
+-----------------------------------+

See also
========

  * Matrix || Matrix -- join matrices vertically

Ways to use this method:
========================

  * Vector || Vector -- join Vectors

VectorExpression -- the class of all vector expressions
*******************************************************

Description
===========

VectorExpression is a type of Expression, representing a
vector.

+-----------------------------------------+
|i1 : VectorExpression {a,b,c}            |
|                                         |
|o1 = | a |                               |
|     | b |                               |
|     | c |                               |
|                                         |
|o1 : Expression of class VectorExpression|
+-----------------------------------------+

See also
========

  * MatrixExpression -- the class of all matrix
    expressions

For the programmer
==================

The object VectorExpression, is a header type,
with ancestor classes Expression, <
BasicList < Thing.

Verbose -- request verbose feedback
***********************************

Functions with optional argument named Verbose:
===============================================

  * "check(...,Verbose=>...)" -- see check, -- perform tests of a
    package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String),
  * "findProgram(...,Verbose=>...)" -- see findProgram, --
    load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage,
    -- load and install a package and its documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String),
  * "runProgram(...,Verbose=>...)" -- see runProgram, -- run
    an external program
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String), --
    make symbolic links for all files in a directory tree

For the programmer
==================

The object Verbose, is a symbol.

VerticalList -- a type of visible self-initializing list that prints vertically
*******************************************************************************

Synopsis
========

  * Usage:
        VerticalList x
  * Inputs:
      * x, a list,
  * Outputs:
      * a vertical list,

Description
===========

All operations on lists apply to vertical lists, since they inherit from the
type VisibleList.  The only difference is the way that a
vertical list is displayed vertically.
+------------------------+
|i1 : a .. e             |
|                        |
|o1 = (a, b, c, d, e)    |
|                        |
|o1 : Sequence           |
+------------------------+
|i2 : v = VerticalList oo|
|                        |
|o2 = {a}                |
|     {b}                |
|     {c}                |
|     {d}                |
|     {e}                |
|                        |
|o2 : VerticalList       |
+------------------------+
|i3 : v_1                |
|                        |
|o3 = b                  |
|                        |
|o3 : Symbol             |
+------------------------+
|i4 : length v           |
|                        |
|o4 = 5                  |
+------------------------+
One may get a normal list back from a vertical list as follows.
+--------------------+
|i5 : toList v       |
|                    |
|o5 = {a, b, c, d, e}|
|                    |
|o5 : List           |
+--------------------+

See also
========

  * NumberedVerticalList -- a type of visible
    self-initializing list that prints vertically

Types of vertical list:
=======================

  * NumberedVerticalList -- a type of visible
    self-initializing list that prints vertically

For the programmer
==================

The object VerticalList, is a self initializing type,
with ancestor classes List, <
VisibleList < BasicList < Thing.

VirtualTally
************

Description
===========

The only difference between this class and Tally, is that this
class allows negative numbers.
+---------------------------------+
|i1 : x = tally {a,b,b,c,c,c}     |
|                                 |
|o1 = Tally{a => 1}               |
|           b => 2                |
|           c => 3                |
|                                 |
|o1 : Tally                       |
+---------------------------------+
|i2 : y = tally {a,a,a,b,b,c}     |
|                                 |
|o2 = Tally{a => 3}               |
|           b => 2                |
|           c => 1                |
|                                 |
|o2 : Tally                       |
+---------------------------------+
|i3 : x' = new VirtualTally from x|
|                                 |
|o3 = VirtualTally{a => 1}        |
|                  b => 2         |
|                  c => 3         |
|                                 |
|o3 : VirtualTally                |
+---------------------------------+
|i4 : y' = new VirtualTally from y|
|                                 |
|o4 = VirtualTally{a => 3}        |
|                  b => 2         |
|                  c => 1         |
|                                 |
|o4 : VirtualTally                |
+---------------------------------+
|i5 : x-y                         |
|                                 |
|o5 = Tally{c => 2}               |
|                                 |
|o5 : Tally                       |
+---------------------------------+
|i6 : x'-y'                       |
|                                 |
|o6 = VirtualTally{a => -2}       |
|                  c => 2         |
|                                 |
|o6 : VirtualTally                |
+---------------------------------+

See also
========

  * BettiTally -- the class of all Betti tallies

Types of virtual tally:
=======================

  * BettiTally -- the class of all Betti tallies
  * Tally -- the class of all tally results

Functions and methods returning a virtual tally:
================================================

  * "VirtualTally - VirtualTally"
  * VirtualTally ** VirtualTally, --
    Cartesian product of tallies
  * VirtualTally + VirtualTally -- union of
    tallies
  * VirtualTally ^** ZZ -- Cartesian power of
    sets and tallies
  * /// Command \ VirtualTally /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// Function \ VirtualTally /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "VirtualTally / Command" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "VirtualTally / Function" -- see VisibleList / Function,
    -- apply a function to elements of a list

Methods that use a virtual tally:
=================================

  * - VirtualTally -- negation of a VirtualTally
  * "VirtualTally ? VirtualTally" -- see ?, -- comparison operator
  * Number * VirtualTally (missing documentation)
  * "partition(Function,VirtualTally)" -- see partition, --
    partition a set or list by values of a function
  * "partition(Function,VirtualTally,VisibleList)" -- see partition,
    -- partition a set or list by values of a function
  * product(VirtualTally) -- product of
    elements
  * RingElement * VirtualTally (missing documentation)
  * sum(VirtualTally) -- sum of elements
  * VirtualTally == VirtualTally (missing documentation)
  * VirtualTally == ZZ (missing documentation)
  * VirtualTally ? ZZ (missing documentation)
  * VirtualTally _ Thing -- get a count from a
    tally
  * ZZ == VirtualTally (missing documentation)
  * ZZ ? VirtualTally (missing documentation)

For the programmer
==================

The object VirtualTally, is a type, with
ancestor classes HashTable, < Thing.

VirtualTally ** VirtualTally -- Cartesian product of tallies
************************************************************

Synopsis
========

  * Operator: **,

Description
===========

x ** y -- produces the Cartesian product of two tallies.

One of the arguments may be a Set.

+------------------------+
|i1 : x = tally {a,a,b}  |
|                        |
|o1 = Tally{a => 2}      |
|           b => 1       |
|                        |
|o1 : Tally              |
+------------------------+
|i2 : y = tally {1,2,2,2}|
|                        |
|o2 = Tally{1 => 1}      |
|           2 => 3       |
|                        |
|o2 : Tally              |
+------------------------+
|i3 : x ** y             |
|                        |
|o3 = Tally{(a, 1) => 2} |
|           (a, 2) => 6  |
|           (b, 1) => 1  |
|           (b, 2) => 3  |
|                        |
|o3 : Tally              |
+------------------------+

See also
========

  * Tally -- the class of all tally results
  * tally -- tally the elements of a list, sequence, array, or
    string

Ways to use this method:
========================

  * VirtualTally ** VirtualTally, --
    Cartesian product of tallies

VirtualTally + VirtualTally -- union of tallies
***********************************************

Synopsis
========

  * Operator: +,

Description
===========

x + y -- produces the union of two tallies.

One of the arguments may be a Set.

+----------------------------------+
|i1 : x = tally {a,b,b,c,c,c,d,d,d}|
|                                  |
|o1 = Tally{a => 1}                |
|           b => 2                 |
|           c => 3                 |
|           d => 3                 |
|                                  |
|o1 : Tally                        |
+----------------------------------+
|i2 : y = tally {a,a,a,b,b,c,d}    |
|                                  |
|o2 = Tally{a => 3}                |
|           b => 2                 |
|           c => 1                 |
|           d => 1                 |
|                                  |
|o2 : Tally                        |
+----------------------------------+
|i3 : x' = new VirtualTally from x |
|                                  |
|o3 = VirtualTally{a => 1}         |
|                  b => 2          |
|                  c => 3          |
|                  d => 3          |
|                                  |
|o3 : VirtualTally                 |
+----------------------------------+
|i4 : y' = new VirtualTally from y |
|                                  |
|o4 = VirtualTally{a => 3}         |
|                  b => 2          |
|                  c => 1          |
|                  d => 1          |
|                                  |
|o4 : VirtualTally                 |
+----------------------------------+
|i5 : z' = y' - x'                 |
|                                  |
|o5 = VirtualTally{a => 2 }        |
|                  c => -2         |
|                  d => -2         |
|                                  |
|o5 : VirtualTally                 |
+----------------------------------+
|i6 : z' + x'                      |
|                                  |
|o6 = VirtualTally{a => 3}         |
|                  b => 2          |
|                  c => 1          |
|                  d => 1          |
|                                  |
|o6 : VirtualTally                 |
+----------------------------------+
|i7 : z' + y'                      |
|                                  |
|o7 = VirtualTally{a => 5 }        |
|                  b => 2          |
|                  c => -1         |
|                  d => -1         |
|                                  |
|o7 : VirtualTally                 |
+----------------------------------+

Ways to use this method:
========================

  * VirtualTally + VirtualTally -- union of
    tallies

VirtualTally ^** ZZ -- Cartesian power of sets and tallies
**********************************************************

Synopsis
========

  * Operator: ^**,
  * Usage:
        B = A^**n
  * Inputs:
      * A
      * n
  * Outputs:
      * B, the tally of n-tuples of elements from A

Description
===========

If A is a set, then so is B.
+-----------------------------------------------------------------------------+
|i1 : A = set {1,2}                                                           |
|                                                                             |
|o1 = set {1, 2}                                                              |
|                                                                             |
|o1 : Set                                                                     |
+-----------------------------------------------------------------------------+
|i2 : A^**3                                                                   |
|                                                                             |
|o2 = set {((1, 1), 1), ((1, 2), 1), ((1, 1), 2), ((2, 1), 1), ((2, 2), 1),   |
|     ------------------------------------------------------------------------|
|     ((1, 2), 2), ((2, 1), 2), ((2, 2), 2)}                                  |
|                                                                             |
|o2 : Set                                                                     |
+-----------------------------------------------------------------------------+
|i3 : A = tally {1,1,2}                                                       |
|                                                                             |
|o3 = Tally{1 => 2}                                                           |
|           2 => 1                                                            |
|                                                                             |
|o3 : Tally                                                                   |
+-----------------------------------------------------------------------------+
|i4 : A^**3                                                                   |
|                                                                             |
|o4 = Tally{((1, 1), 1) => 8}                                                 |
|           ((1, 1), 2) => 4                                                  |
|           ((1, 2), 1) => 4                                                  |
|           ((1, 2), 2) => 2                                                  |
|           ((2, 1), 1) => 4                                                  |
|           ((2, 1), 2) => 2                                                  |
|           ((2, 2), 1) => 2                                                  |
|           ((2, 2), 2) => 1                                                  |
|                                                                             |
|o4 : Tally                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * Set -- the class of all sets
  * Set ** Set -- Cartesian product

Ways to use this method:
========================

  * VirtualTally ^** ZZ -- Cartesian power of
    sets and tallies

VirtualTally _ Thing -- get a count from a tally
************************************************

Synopsis
========

  * Operator: _,
  * Usage:
        t_x
  * Inputs:
      * t
      * x
  * Outputs:
      * an integer, the number of times x is counted by t

Description
===========

+-----------------------------------------------+
|i1 : t = tally apply(1..10000, i -> # factor i)|
|                                               |
|o1 = Tally{0 => 1   }                          |
|           1 => 1280                           |
|           2 => 4097                           |
|           3 => 3695                           |
|           4 => 894                            |
|           5 => 33                             |
|                                               |
|o1 : Tally                                     |
+-----------------------------------------------+
|i2 : t_5                                       |
|                                               |
|o2 = 33                                        |
+-----------------------------------------------+
|i3 : t_6                                       |
|                                               |
|o3 = 0                                         |
+-----------------------------------------------+

See also
========

  * Tally -- the class of all tally results

Ways to use this method:
========================

  * VirtualTally _ Thing -- get a count from a
    tally

VisibleList -- the class of all visible lists
*********************************************

Description
===========

There are three types of lists that can be entered directly from the keyboard,
as follows.
+--------------+
|i1 : {a,b,c}  |
|              |
|o1 = {a, b, c}|
|              |
|o1 : List     |
+--------------+
|i2 : [a,b,c]  |
|              |
|o2 = [a, b, c]|
|              |
|o2 : Array    |
+--------------+
|i3 : (a,b,c)  |
|              |
|o3 = (a, b, c)|
|              |
|o3 : Sequence |
+--------------+
We introduce the class of visible lists as a convenience for referring to lists
of these types.

Types of visible list:
======================

  * AngleBarList -- the class of lists delimited by <| ...
    |>
  * Array -- the class of all arrays -- [...]
  * List -- the class of all lists -- {...}
  * Sequence -- the class of all sequences -- (...)

Functions and methods returning a visible list:
===============================================

  * "accumulate(Function,Thing,VisibleList)" -- see accumulate,
    -- apply a binary operator repeatedly
  * "accumulate(Function,VisibleList)" -- see accumulate, --
    apply a binary operator repeatedly
  * "accumulate(VisibleList,Function)" -- see accumulate, --
    apply a binary operator repeatedly
  * "accumulate(VisibleList,Thing,Function)" -- see accumulate,
    -- apply a binary operator repeatedly
  * "flatten(VisibleList)" -- see flatten, -- flatten a nested
    list or a matrix
  * "permutations(VisibleList)" -- see permutations, --
    produce all permutations of a list
  * /// Command \\ Thing /// -- see Thing // Function,
    -- apply a function
  * /// Function \\ Thing /// -- see Thing // Function,
    -- apply a function
  * "Thing // Command" -- see Thing // Function, --
    apply a function
  * Thing // Function -- apply a function
  * "uniquePermutations(VisibleList)" -- see uniquePermutations,
    -- produce all unique permutations of a list
  * /// Command \ VisibleList /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// Function \ VisibleList /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// RingMap \ VisibleList /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "VisibleList / Command" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * VisibleList / Function -- apply a function
    to elements of a list
  * "VisibleList / RingMap" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * VisibleList _ List -- get some entries of a
    list

Methods that use a visible list:
================================

  * between(Thing,VisibleList), --
    insert something between elements of a list
  * "commonest(VisibleList)" -- see commonest, -- the most
    common elements of a list or tally
  * "EXAMPLE(VisibleList)" -- see EXAMPLE, -- hypertext EXAMPLE
    item
  * "fold(Function,VisibleList)" -- see fold, -- apply a binary
    operator repeatedly
  * "fold(VisibleList,Function)" -- see fold, -- apply a binary
    operator repeatedly
  * "fold(VisibleList,Thing,Function)" -- see fold, -- apply a
    binary operator repeatedly
  * "isMember(Thing,VisibleList)" -- see isMember, -- test
    membership in a list or set
  * "isSorted(VisibleList)" -- see isSorted, -- whether a list
    is sorted
  * "isSubset(Set,VisibleList)" -- see isSubset(Set,Set),
    -- whether one object is a subset of another
  * "isSubset(VisibleList,Set)" -- see isSubset(Set,Set),
    -- whether one object is a subset of another
  * "isSubset(VisibleList,VisibleList)" -- see isSubset(Set,Set),
    -- whether one object is a subset of another
  * "iterator(VisibleList)" -- see iterator, -- get an iterator
  * length(VisibleList) -- length of a visible
    list
  * "max(VisibleList)" -- see max, -- yields the maximum element in
    a list or sequence
  * "min(VisibleList)" -- see min, -- yields the minimum element in
    a list or sequence
  * netList(VisibleList) -- a table of boxes
  * "numeric(VisibleList)" -- see numeric, -- convert to
    floating point
  * "numeric(ZZ,VisibleList)" -- see numeric, -- convert to
    floating point
  * "oeis(VisibleList)" -- see oeis (OnlineLookup), -- OEIS lookup
  * "part(InfiniteNumber,InfiniteNumber,VisibleList,RingElement)" -- see
    part, -- select terms of a polynomial by degree(s) or weight(s)
  * "part(InfiniteNumber,ZZ,VisibleList,RingElement)" -- see part,
    -- select terms of a polynomial by degree(s) or weight(s)
  * "part(Nothing,Nothing,VisibleList,RingElement)" -- see part, --
    select terms of a polynomial by degree(s) or weight(s)
  * "part(Nothing,ZZ,VisibleList,RingElement)" -- see part, --
    select terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,InfiniteNumber,VisibleList,RingElement)" -- see part,
    -- select terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,Nothing,VisibleList,RingElement)" -- see part, --
    select terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,VisibleList,RingElement)" -- see part, -- select terms
    of a polynomial by degree(s) or weight(s)
  * "part(ZZ,ZZ,VisibleList,RingElement)" -- see part, -- select
    terms of a polynomial by degree(s) or weight(s)
  * "partition(Function,VirtualTally,VisibleList)" -- see partition,
    -- partition a set or list by values of a function
  * "partition(Function,VisibleList)" -- see partition, --
    partition a set or list by values of a function
  * "partition(Function,VisibleList,VisibleList)" -- see partition,
    -- partition a set or list by values of a function
  * "position(VisibleList,Function)" -- see position, -- the
    first element of a list satisfying a condition
  * "position(VisibleList,VisibleList,Function)" -- see position,
    -- the first element of a list satisfying a condition
  * "positions(VisibleList,Function)" -- see positions, --
    which elements of a list satisfy a condition
  * product(VisibleList,Function),
    -- product of values of a function
  * product(VisibleList,VisibleList,Function)
    -- product of results of
    applying a function pairwise
  * rotate(ZZ,VisibleList) -- rotate a
    list
  * runLengthEncode(VisibleList), --
    run length encoding
  * Schubert(ZZ,ZZ,VisibleList), --
    find the Plücker ideal of a Schubert variety
  * "set(VisibleList)" -- see set, -- make a set
  * "sublists(VisibleList,Function)" -- see sublists, --
    process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Function)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Function,Function)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Function,Nothing)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Nothing)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Nothing,Function)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "sublists(VisibleList,Function,Nothing,Nothing)" -- see sublists,
    -- process interspersed subsequences of a visible list
  * "submatrix'(Matrix,Nothing,VisibleList)" -- see submatrix',
    -- exclude rows and/or columns of a matrix
  * "submatrix'(Matrix,VisibleList)" -- see submatrix', --
    exclude rows and/or columns of a matrix
  * "submatrix'(Matrix,VisibleList,Nothing)" -- see submatrix',
    -- exclude rows and/or columns of a matrix
  * "submatrix'(Matrix,VisibleList,VisibleList)" -- see submatrix',
    -- exclude rows and/or columns of a matrix
  * submatrix(Matrix,VisibleList),
    -- select columns
  * "submatrix(MutableMatrix,VisibleList)" -- see
    submatrix(Matrix,VisibleList), --
    select columns
  * submatrix(Matrix,VisibleList,VisibleList)
    -- select part of a
    matrix
  * "submatrix(MutableMatrix,VisibleList,VisibleList)" -- see
    submatrix(Matrix,VisibleList,VisibleList),
    -- select part of a
    matrix
  * sum(VisibleList,Function) -- sum
    results of applying a function
  * sum(VisibleList,VisibleList,Function)
    -- sum results of applying a
    function pairwise
  * "tally(VisibleList)" -- see tally, -- tally the elements of a
    list, sequence, array, or string
  * "unique(VisibleList)" -- see unique, -- eliminate duplicates
    from a list
  * /// SelfInitializingType \ VisibleList /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "VisibleList / SelfInitializingType" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * VisibleList == VisibleList (missing documentation)
  * VisibleList _ ZZ -- get element from list

For the programmer
==================

The object VisibleList, is a type, with
ancestor classes BasicList, < Thing.

List -- the class of all lists -- {...}
***************************************

Description
===========

Lists in Macaulay2 consist of elements of any type, enclosed in braces, and
separated by commas.
+------------------+
|i1 : L = {a,1,b,2}|
|                  |
|o1 = {a, 1, b, 2} |
|                  |
|o1 : List         |
+------------------+
The length of a list has two notations, the version with the # is faster when
writing programs.
+-----------------+
|i2 : #L, length L|
|                 |
|o2 = (4, 4)      |
|                 |
|o2 : Sequence    |
+-----------------+
The first entry of the list has index 0.  Indexing is performed using #.
+-----------+
|i3 : L#2   |
|           |
|o3 = b     |
|           |
|o3 : Symbol|
+-----------+

Lists in Macaulay2 are immutable. See MutableList, for
making and using lists that you may modify.

To convert lists to and from other types of BasicList, in
addition to toList, one may use new.

+---------------------------+
|i4 : new Array from {a,b,c}|
|                           |
|o4 = [a, b, c]             |
|                           |
|o4 : Array                 |
+---------------------------+
|i5 : new List from [a,b,c] |
|                           |
|o5 = {a, b, c}             |
|                           |
|o5 : List                  |
+---------------------------+

For an overview of lists and sequences, see lists and sequences.

Types of list:
==============

  * Hybrid (MinimalPrimes) -- the class of lists encapsulating
    hybrid strategies
  * VerticalList -- a type of visible self-initializing
    list that prints vertically

Functions and methods returning a list:
=======================================

  * "List * Thing" -- see *, -- a binary operator, usually used for
    multiplication
  * "Thing * List" -- see *, -- a binary operator, usually used for
    multiplication
  * - List -- negation of a vector
  * apply(ZZ,Function) -- apply a function to
    {0,..., n-1}
  * associatedPrimes (PrimaryDecomposition) -- find
    associated primes
  * "associatedPrimes(Ideal)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "associatedPrimes(Module)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "associatedPrimes(Ring)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * between(Thing,VisibleList), --
    insert something between elements of a list
  * cellDecompose (Polyhedra) -- Deprecated variant of
    {\tt regularSubdivision}
  * commonest -- the most common elements of a list or tally
  * components(CoherentSheaf) (missing documentation)
  * components(SheafMap) (missing documentation)
  * compositions -- list the compositions of an integer
  * cones (Polyhedra) -- computes all cones of a fan of a certain
    dimension
  * degree(Matrix) (missing documentation)
  * degrees -- degrees of generators
  * "elements(Set)" -- see elements, -- list of elements
  * eulers (missing documentation)
  * findHeft -- find a heft vector for a list of degrees
  * "frames(FunctionClosure)" -- see frames, -- get the frames
    associated to a closure
  * "frames(PseudocodeClosure)" -- see frames, -- get the frames
    associated to a closure
  * "frames(Sequence)" -- see frames, -- get the frames
    associated to a closure
  * "frames(Symbol)" -- see frames, -- get the frames associated
    to a closure
  * frames(CompiledFunction) (missing documentation)
  * frames(CompiledFunctionClosure) (missing documentation)
  * fVector (Polyhedra) -- computes the f-vector of a Cone,
    Polyhedron, Fan or PolyhedralComplex
  * genera (missing documentation)
  * "hilbertBasis(Cone)" -- see hilbertBasis (Polyhedra), --
    computes the Hilbert basis of a Cone
  * "icFracP(Ring)" -- see icFracP (IntegralClosure), -- compute
    the integral closure in prime characteristic
  * /// Function \ Ideal /// -- see Ideal / Function,
    -- apply a function to generators of an ideal
  * Ideal / Function -- apply a function to generators
    of an ideal
  * incompCones (Polyhedra) -- returns the pairs of
    incompatible cones
  * incompPolyhedra (Polyhedra) -- returns the pairs of
    incompatible polyhedra
  * "independentSets(Ideal)" -- see independentSets, --
    some size-maximal independent subsets of variables modulo an ideal
  * "independentSets(MonomialIdeal)" -- see independentSets,
    -- some size-maximal independent subsets of variables
    modulo an ideal
  * interiorLatticePoints (Polyhedra) -- computes
    the lattice points in the relative interior of a polytope
  * "irreducibleDecomposition(MonomialIdeal)" -- see
    irreducibleDecomposition (PrimaryDecomposition),
    -- express a monomial ideal as an intersection of irreducible monomial
    ideals
  * "keys(Database)" -- see keys, -- keys used in a hash table,
    dictionary, or database
  * "keys(Dictionary)" -- see keys, -- keys used in a hash table,
    dictionary, or database
  * "keys(HashTable)" -- see keys, -- keys used in a hash table,
    dictionary, or database
  * latticePoints (Polyhedra) -- computes the lattice
    points of a polytope
  * "leadComponent(Matrix)" -- see leadComponent, -- the
    leading component(s) of a vector or matrix
  * "lines(String)" -- see lines, -- split a string into lines
  * "lines(String,String)" -- see lines, -- split a string into
    lines
  * List % Number (missing documentation)
  * List % RingElement (missing documentation)
  * List ** List -- Cartesian product of two lists
  * List + List -- sum of two vectors
  * List - List -- difference of two vectors
  * "List / Number" -- see List / RingElement, --
    vector division
  * List / RingElement -- vector division
  * List // Number (missing documentation)
  * List // RingElement (missing documentation)
  * List | List -- join lists, sequences or arrays
  * "localDictionaries(Dictionary)" -- see localDictionaries,
    -- get local dictionaries
  * "localDictionaries(FunctionClosure)" -- see localDictionaries,
    -- get local dictionaries
  * "localDictionaries(PseudocodeClosure)" -- see localDictionaries,
    -- get local dictionaries
  * "localDictionaries(Symbol)" -- see localDictionaries,
    -- get local dictionaries
  * localDictionaries(CompiledFunction) (missing documentation)
  * localDictionaries(CompiledFunctionClosure) (missing documentation)
  * localDictionaries(Sequence) (missing documentation)
  * "locate(List)" -- see locate, -- locate source code
  * maxCones (Polyhedra) -- displays the generating Cones of a
    Fan
  * maxPolyhedra (Polyhedra) -- displays the generating
    Polyhedra of a PolyhedralComplex
  * "mingle(BasicList)" -- see mingle, -- mingle elements of
    several lists
  * "decompose(Ideal)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(Ideal)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * Monoid _* (missing documentation)
  * "pack(BasicList,ZZ)" -- see pack, -- pack elements of a list or
    string into several shorter lists or strings
  * "pack(String,ZZ)" -- see pack, -- pack elements of a list or
    string into several shorter lists or strings
  * "pack(ZZ,BasicList)" -- see pack, -- pack elements of a list or
    string into several shorter lists or strings
  * "pack(ZZ,String)" -- see pack, -- pack elements of a list or
    string into several shorter lists or strings
  * "pairs(BasicList)" -- see pairs, -- list the pairs in a hash
    table, dictionary, or basic list
  * "pairs(Dictionary)" -- see pairs, -- list the pairs in a hash
    table, dictionary, or basic list
  * "pairs(HashTable)" -- see pairs, -- list the pairs in a hash
    table, dictionary, or basic list
  * partitions -- list the partitions of an integer
  * "permutations(ZZ)" -- see permutations, -- produce all
    permutations of a list
  * polyhedra (Polyhedra) -- computes all polyhedra of a
    polyhedral complex of a certain dimension
  * positions -- which elements of a list satisfy a condition
  * primaryDecomposition (PrimaryDecomposition), --
    irredundant primary decomposition of an ideal
  * "primaryDecomposition(Ideal)" -- see primaryDecomposition (PrimaryDecomposition),
    -- irredundant primary
    decomposition of an ideal
  * primaryDecomposition(Module) (PrimaryDecomposition)
    -- irredundant
    primary decomposition of a module
  * "primaryDecomposition(Ring)" -- see primaryDecomposition(Module) (PrimaryDecomposition),
    -- irredundant
    primary decomposition of a module
  * regex -- evaluate a regular expression search
  * regularSubdivision (Polyhedra) -- Computes the
    regular cell decomposition
  * searchPath(List,String) -- search a
    path for a file
  * "searchPath(String)" -- see searchPath(List,String),
    -- search a path for a file
  * "select(String,String)" -- see select(String,String,String),
    -- select and reformat substrings
    matching a regular expression
  * select(String,String,String),
    -- select and reformat substrings matching a regular expression
  * select(ZZ,Function) -- select integers
  * separate -- split a string into substrings using a regular
    expression
  * "List - Set" -- see Set - Set, -- set difference
  * subsets -- produce the subsets of a set or list
  * "take(Thing,List)" -- see take, -- Take some elements from a
    list or sequence.
  * "take(Thing,ZZ)" -- see take, -- Take some elements from a list
    or sequence.
  * "toList(BasicList)" -- see toList, -- create a list
  * "toList(Set)" -- see toList, -- create a list
  * "toList(String)" -- see toList, -- create a list
  * toList(Pseudocode) (missing documentation)
  * transpose(List) --  transposes a table
  * truncate(Cone,List,ZZ) (missing documentation)
  * unique -- eliminate duplicates from a list
  * "unstack(Net)" -- see unstack, -- list the rows of a net
  * unstack(String) (missing documentation)
  * "values(Dictionary)" -- see values, -- values in a hash table
  * "values(HashTable)" -- see values, -- values in a hash table
  * "List / Command" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "List / Function" -- see VisibleList / Function,
    -- apply a function to elements of a list

Methods that use a list:
========================

  * # List (missing documentation)
  * >= List (missing documentation)
  * "List ? List" -- see ?, -- comparison operator
  * "addCone(List,Fan)" -- see addCone (Polyhedra), -- adds cones
    to a Fan
  * "addPolyhedron(List,PolyhedralComplex)" -- see addPolyhedron (Polyhedra),
    -- adds Polyhedra to a PolyhedralComplex
  * "basis(InfiniteNumber,List,Ideal)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,List,Matrix)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,List,Module)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,List,Ring)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,Ideal)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(List,InfiniteNumber,Ideal)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,InfiniteNumber,Matrix)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,InfiniteNumber,Module)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,InfiniteNumber,Ring)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,List,Ideal)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,List,Matrix)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,List,Module)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,List,Ring)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,Matrix)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(List,Module)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(List,Ring)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(List,RingMap)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(List,ZZ,Ideal)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,ZZ,Matrix)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,ZZ,Module)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,ZZ,Ring)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(ZZ,List,Ideal)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(ZZ,List,Matrix)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(ZZ,List,Module)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(ZZ,List,Ring)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "capture(List)" -- see capture, -- evaluate Macaulay2 code
    and capture the output
  * chainComplex(List) -- make a chain complex
  * "check(List,Package)" -- see check, -- perform tests of a
    package
  * "check(List,String)" -- see check, -- perform tests of a
    package
  * "code(List)" -- see code, -- display source code
  * CoherentSheaf ^ List (missing documentation)
  * "columnPermute(MutableMatrix,ZZ,List)" -- see columnPermute,
    -- permute some columns
  * "commonFace(List)" -- see commonFace (Polyhedra), --
    checks if the intersection is a face of both Cones or Polyhedra, or of
    cones with fans
  * "commonRing(List)" -- see commonRing, -- find smallest
    containing ring
  * "coneFromVData(List)" -- see coneFromVData (Polyhedra),
    -- computes the positive hull of rays, cones, and the cone over a
    polyhedron
  * "contains(List,Cone)" -- see contains (Polyhedra), -- checks
    if the first argument contains the second argument
  * "contains(List,Polyhedron)" -- see contains (Polyhedra), --
    checks if the first argument contains the second argument
  * "convexHull(List)" -- see convexHull (Polyhedra), --
    computing the convex hull of points, rays and polyhedra
  * "degreesMonoid(List)" -- see degreesRing(List),
    -- the ring or monoid of degrees
  * degreesRing(List) -- the ring or monoid of
    degrees
  * "diagonalMatrix(List)" -- see diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a
    list
  * "diagonalMatrix(Ring,List)" -- see diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a
    list
  * diagonalMatrix(Ring,ZZ,ZZ,List)
    -- make a diagonal matrix from a
    list
  * "diagonalMatrix(RingFamily,List)" -- see
    diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a list
  * "diagonalMatrix(RingFamily,ZZ,ZZ,List)" -- see
    diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a list
  * "diagonalMatrix(ZZ,ZZ,List)" -- see diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a
    list
  * "directSum(List)" -- see directSum, -- direct sum of
    modules or maps
  * "document(List)" -- see document, -- create a documentation
    node
  * "makeDocumentTag(List)" -- see DocumentTag, -- the class
    of all document tags
  * "drop(BasicList,List)" -- see drop, -- drop some elements from
    a list or sequence.
  * dual(MonomialIdeal,List) -- the
    Alexander dual
  * "eliminate(List,Ideal)" -- see eliminate (Elimination),
  * "examples(List)" -- see examples, -- list the examples in
    documentation
  * "export(List)" -- see export, -- export symbols from a
    package
  * "exportFrom(Package,List)" -- see exportFrom, -- export
    symbols from a package's private dictionary
  * "exportFrom(String,List)" -- see exportFrom, -- export
    symbols from a package's private dictionary
  * "exportMutable(List)" -- see exportMutable, -- export
    mutable symbols from a package
  * "fan(List)" -- see fan (Polyhedra), -- generates a Fan
  * "fan(Matrix,List)" -- see fan(Matrix,Matrix,List) (Polyhedra),
    -- Constructing a fan.
  * fan(Matrix,Matrix,List) (Polyhedra),
    -- Constructing a fan.
  * "fanFromGfan(List)" -- see fanFromGfan (Polyhedra), --
    Construct a fan from output data of {\tt Gfan}
  * "findFiles(List)" -- see findFiles, -- find files
    recursively
  * "findHeft(List)" -- see findHeft, -- find a heft vector for
    a list of degrees
  * "findProgram(String,List)" -- see findProgram, -- load
    external program
  * "gcd(List)" -- see gcd, -- greatest common divisor
  * "gcdLLL(List)" -- see gcdLLL (LLLBases), -- compute the gcd of
    integers, and small multipliers
  * "gradedModule(List)" -- see gradedModule, -- make a
    graded module
  * "gradedModuleMap(List)" -- see gradedModuleMap, --
    make a map of graded modules
  * "hashTable(List)" -- see hashTable, -- make a hash table
  * hashTable(Function,List) (missing documentation)
  * "HeaderType List" -- see HeaderType, -- a class of lists
    with abbreviated constructors
  * headlines(List) (missing documentation)
  * "help(List)" -- see help, -- view documentation nodes
  * "hilbertFunction(List,Ideal)" -- see hilbertFunction,
    -- the Hilbert function
  * "hilbertFunction(List,Module)" -- see hilbertFunction,
    -- the Hilbert function
  * "hilbertFunction(List,Ring)" -- see hilbertFunction,
    -- the Hilbert function
  * "homogenize(Matrix,RingElement,List)" -- see homogenize,
    -- homogenize with respect to a variable
  * "homogenize(Module,RingElement,List)" -- see homogenize,
    -- homogenize with respect to a variable
  * "homogenize(RingElement,RingElement,List)" -- see homogenize,
    -- homogenize with respect to a variable
  * "homogenize(Vector,RingElement,List)" -- see homogenize,
    -- homogenize with respect to a variable
  * "hooks(List)" -- see hooks, -- list hooks attached to a key
  * ideal(List) -- make an ideal
  * "importFrom(Package,List)" -- see importFrom, -- import
    symbols to the current private dictionary
  * "importFrom(String,List)" -- see importFrom, -- import
    symbols to the current private dictionary
  * "incompCones(List)" -- see incompCones (Polyhedra), --
    returns the pairs of incompatible cones
  * "incompPolyhedra(List)" -- see incompPolyhedra (Polyhedra),
    -- returns the pairs of incompatible polyhedra
  * "intersect(List)" -- see intersect, -- compute an
    intersection
  * "intersection(List)" -- see intersection (Polyhedra), --
    computes the intersection of cones, and polyhedra
  * "lcm(List)" -- see lcm, -- least common multiple
  * List # ZZ (missing documentation)
  * List #? ZZ (missing documentation)
  * List .. List -- rectangular sequences of
    consecutive lists and sequences
  * List ..< List -- rectangular sequences of
    consecutive lists and sequences
  * List << List -- component-wise comparison of lists
  * List ^ List (missing documentation)
  * "listSymbols(List)" -- see listSymbols, -- compact
    display of symbols and their values
  * "makePackageIndex(List)" -- see makePackageIndex,
    -- create an index of installed packages
  * map(Module,Module,List) -- create a
    matrix by giving a sparse or dense list of entries
  * "map(Module,Module,RingMap,List)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * "map(Module,Nothing,RingMap,List)" -- see
    map(Module,Module,RingMap,Matrix),
    -- homomorphism of modules
    over different rings
  * map(Module,Nothing,List) -- create
    a matrix by giving a doubly nested list of ring elements
  * map(Module,ZZ,List) -- create a matrix
    by giving a sparse or dense list of entries
  * map(Ring,Ring,List) -- make a ring map
  * "match(List,String)" -- see match, -- regular expression
    matching
  * Matrix ^ List -- select rows
  * Matrix _ List -- select columns
  * matrix(List) -- create a matrix from a
    doubly-nested list of ring elements or matrices
  * matrix(Ring,List) -- create a matrix from a
    doubly nested list of ring elements or matrices
  * "matrix(RingFamily,List)" -- see matrix(Ring,List),
    -- create a matrix from a doubly nested list of
    ring elements or matrices
  * "memoize(Function,List)" -- see memoize, -- record results
    of function evaluation for future use
  * "mixedVolume(List)" -- see mixedVolume (Polyhedra), --
    computes the mixed volume of a list of polytope
  * "Module / List" -- see Module / Module, -- quotient
    module
  * Module ^ List -- projection onto summand
  * "Ideal _ List" -- see Module _ List, -- map from
    free module to some generators
  * Module _ List -- map from free module to some
    generators
  * "monoid(List)" -- see monoid, -- make or retrieve a monoid
  * "monomialIdeal(List)" -- see monomialIdeal(Matrix),
    -- monomial ideal of lead monomials
  * MultigradedBettiTally List (missing documentation)
  * "mutableMatrix(List)" -- see mutableMatrix, -- make a
    mutable matrix
  * MutableMatrix ^ List (missing documentation)
  * MutableMatrix _ List (missing documentation)
  * new HashTable from List -- make a hash
    table from a list
  * new OptionTable from List (missing documentation)
  * "norm(List)" -- see norm,
  * "ofClass(List)" -- see ofClass, -- English phrases for types
  * "OptionTable ++ List" -- see OptionTable ++ OptionTable,
    -- a binary operator, usually used for direct sum
  * "List >> Function" -- see OptionTable >> Function,
    -- attaching options to a function
  * "part(List,RingElement)" -- see part, -- select terms of a
    polynomial by degree(s) or weight(s)
  * "polyhedralComplex(List)" -- see polyhedralComplex (Polyhedra),
    -- generates a PolyhedralComplex
  * "polyhedralComplex(Matrix,List)" -- see
    polyhedralComplex(Matrix,Matrix,Matrix,List) (Polyhedra),
    --
    Constructing a polyhedral complex.
  * "polyhedralComplex(Matrix,Matrix,List)" -- see
    polyhedralComplex(Matrix,Matrix,Matrix,List) (Polyhedra),
    --
    Constructing a polyhedral complex.
  * polyhedralComplex(Matrix,Matrix,Matrix,List) (Polyhedra),
    --
    Constructing a polyhedral complex.
  * product(List) -- product of elements
  * random(List) -- shuffle a list randomly
  * "random(List,Ideal)" -- see random(ZZ,Ideal),
    -- get a random homogeneous element from a graded ideal
  * "random(List,Ring)" -- see random(ZZ,Ring), --
    get a random homogeneous element from a graded ring
  * "Ring / List" -- see Ring / Ideal, -- make a quotient
    ring
  * Ring ^ List -- make a free module
  * "RingFamily ^ List" -- see Ring ^ List, -- make a free
    module
  * Ring _ List -- make a monomial from a list of
    exponents
  * "InexactFieldFamily List" -- see Ring List, -- make a
    local polynomial ring
  * Ring List -- make a local polynomial ring
  * "rowPermute(MutableMatrix,ZZ,List)" -- see rowPermute, --
    permute some rows
  * "rsort(List)" -- see rsort, -- sort a list or matrix in
    reverse order
  * rsort(List,Function) (missing documentation)
  * "scanLines(Function,List)" -- see scanLines, -- apply a
    function to each line of a file
  * selectVariables(List,PolynomialRing)
    -- make a subring of a
    polynomial ring generated by selected variables
  * "Set - List" -- see Set - Set, -- set difference
  * SheafOfRings ^ List (Varieties) -- make a graded
    free coherent sheaf
  * sort(List) -- sort a list
  * sort(List,Function) (missing documentation)
  * span(List) -- construct smallest interval
  * "standardPairs(MonomialIdeal,List)" -- see standardPairs,
    -- find the standard pairs of a monomial ideal
  * "submatrixByDegrees(Matrix,List,List)" -- see submatrixByDegrees,
    -- submatrix consisting of rows and columns in an
    interval or box of degrees
  * "subsets(List)" -- see subsets, -- produce the subsets of a
    set or list
  * "subsets(List,ZZ)" -- see subsets, -- produce the subsets of
    a set or list
  * "substitute(Ideal,List)" -- see substitute, --
    substituting values for variables
  * "substitute(Matrix,List)" -- see substitute, --
    substituting values for variables
  * "substitute(Module,List)" -- see substitute, --
    substituting values for variables
  * "substitute(RingElement,List)" -- see substitute, --
    substituting values for variables
  * "substitute(Vector,List)" -- see substitute, --
    substituting values for variables
  * sum(List) -- sum the elements of a list
  * "SYNOPSIS(List)" -- see SYNOPSIS, -- a standardized
    synopsis for use in documentation nodes
  * "take(BasicList,List)" -- see take, -- Take some elements from
    a list or sequence.
  * "tensor(List)" -- see tensor, -- tensor product
  * truncate(List,Matrix) (Truncations), --
    truncation of a map of free modules
  * "truncate(List,Ideal)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * truncate(List,Module) (Truncations), --
    truncation of the graded ring, ideal or module at a specified degree or set
    of degrees
  * "truncate(List,Ring)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * "undocumented(List)" -- see undocumented, -- declare
    that something need not be documented
  * union(List) (missing documentation)
  * vars(List) -- a sequence of variables
  * "vector(List)" -- see vector, -- make a vector
  * "vector(Module,List)" -- see vector, -- make a vector
  * Vector ^ List (missing documentation)
  * VisibleList _ List -- get some entries of a
    list
  * "weightRange(List,RingElement)" -- see weightRange, --
    the pair of lowest and highest weights of the monomials
  * "WrapperType List" -- see WrapperType, -- a class of
    lists with abbreviated constructors

For the programmer
==================

The object List, is a type, with ancestor classes
VisibleList < BasicList < Thing.

Sequence -- the class of all sequences -- (...)
***********************************************

Description
===========

A sequence is an ordered collection of things enclosed by parentheses and
separated by commas.  Use #, to get the length of a sequence of to get
one of the elements.

+----------------+
|i1 : v = (a,b,c)|
|                |
|o1 = (a, b, c)  |
|                |
|o1 : Sequence   |
+----------------+
|i2 : #v         |
|                |
|o2 = 3          |
+----------------+
|i3 : v#2        |
|                |
|o3 = c          |
|                |
|o3 : Symbol     |
+----------------+

To convert sequences to and from other types of BasicList, in
addition to toSequence, one may use new.

+------------------------------+
|i4 : new Array from (a,b,c)   |
|                              |
|o4 = [a, b, c]                |
|                              |
|o4 : Array                    |
+------------------------------+
|i5 : new Sequence from [a,b,c]|
|                              |
|o5 = (a, b, c)                |
|                              |
|o5 : Sequence                 |
+------------------------------+

For an overview of lists and sequences, see lists and sequences.

Functions and methods returning a sequence:
===========================================

  * "apply(BasicList,String,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * "apply(String,BasicList,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * "apply(String,String,Function)" -- see
    apply(BasicList,BasicList,Function),
    -- apply a function to pairs
    of elements, one from each list
  * "apply(String,Function)" -- see apply(BasicList,Function),
    -- apply a function to each element of a
    list
  * "ascii(String)" -- see ascii, -- ASCII character conversion
  * "checkDegrees(Matrix,Matrix)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * "checkDegrees(Module,Module)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * IndexedVariable .. IndexedVariable
    -- sequences of consecutive indexed variables
  * IndexedVariable ..< IndexedVariable
    -- sequences of consecutive indexed variables
  * "isIsomorphic(Matrix,Matrix)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * "isIsomorphic(Module,Module)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * List .. List -- rectangular sequences of
    consecutive lists and sequences
  * "Sequence .. Sequence" -- see List .. List, --
    rectangular sequences of consecutive lists and sequences
  * List ..< List -- rectangular sequences of
    consecutive lists and sequences
  * "Sequence ..< Sequence" -- see List ..< List, --
    rectangular sequences of consecutive lists and sequences
  * "Sequence | Sequence" -- see List | List, -- join lists,
    sequences or arrays
  * String .. String -- a sequence of consecutive
    strings
  * String ..< String -- a sequence of
    consecutive strings, not including the endpoint
  * "toSequence(BasicList)" -- see toSequence, -- convert to
    sequence
  * "toSequence(String)" -- see toSequence, -- convert to
    sequence
  * "toSequence(Thing)" -- see toSequence, -- convert to
    sequence
  * /// Command \ String /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * /// Function \ String /// -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "String / Command" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * "String / Function" -- see VisibleList / Function,
    -- apply a function to elements of a list
  * ZZ .. ZZ -- sequences of consecutive integers
  * ZZ ..< ZZ -- sequences of consecutive integers

Methods that use a sequence:
============================

  * # Sequence (missing documentation)
  * "Sequence <- Thing" -- see <-, -- assignment with left side
    evaluated
  * "addHook(Sequence,Function)" -- see addHook, -- add a hook
    function to an object for later processing
  * "basis(Sequence,RingMap)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "chainComplex(Sequence)" -- see chainComplex(List),
    -- make a chain complex
  * "code(Sequence)" -- see code, -- display source code
  * CoherentSheaf Sequence (missing documentation)
  * "directSum(Sequence)" -- see directSum, -- direct sum of
    modules or maps
  * "fan(Matrix,Matrix,Sequence)" -- see fan(Matrix,Matrix,List) (Polyhedra),
    -- Constructing a fan.
  * "fan(Matrix,Sequence)" -- see fan(Matrix,Matrix,List) (Polyhedra),
    -- Constructing a fan.
  * "frames(Sequence)" -- see frames, -- get the frames
    associated to a closure
  * "gcd(Sequence)" -- see gcd, -- greatest common divisor
  * "gradedModule(Sequence)" -- see gradedModule, -- make a
    graded module
  * "gradedModuleMap(Sequence)" -- see gradedModuleMap,
    -- make a map of graded modules
  * "HeaderType Sequence" -- see HeaderType, -- a class of
    lists with abbreviated constructors
  * "help(Sequence)" -- see help, -- view documentation nodes
  * "hh(Sequence,ProjectiveVariety)" -- see hh (Varieties), -- Hodge
    numbers of a smooth projective variety
  * HH_ZZ Sequence (missing documentation)
  * "hooks(Sequence)" -- see hooks, -- list hooks attached to a
    key
  * "ideal(Sequence)" -- see ideal(List), -- make an
    ideal
  * "intersect(Sequence)" -- see intersect, -- compute an
    intersection
  * "lcm(Sequence)" -- see lcm, -- least common multiple
  * localDictionaries(Sequence) (missing documentation)
  * "locate(Sequence)" -- see locate, -- locate source code
  * "makePackageIndex(Sequence)" -- see makePackageIndex,
    -- create an index of installed packages
  * Matrix _ Sequence -- get entry of matrix
  * "MutableMatrix _ Sequence" -- see Matrix _ Sequence,
    -- get entry of matrix
  * "methods(Sequence)" -- see methods, -- list methods
  * "Module / Sequence" -- see Module / Module, --
    quotient module
  * "monomialIdeal(Sequence)" -- see monomialIdeal(Matrix),
    -- monomial ideal of lead monomials
  * "MultigradedBettiTally Sequence" -- see MultigradedBettiTally,
    -- the class of all multigraded Betti tallies
  * MutableMatrix _ Sequence = Thing,
    -- assignment to an element of a mutable matrix
  * "options(Sequence)" -- see options(Command), --
    get optional arguments and default values of functions and methods
  * "package(Sequence)" -- see package, -- get containing
    package
  * read(Sequence) -- read from a file
  * "Ring / Sequence" -- see Ring / Ideal, -- make a
    quotient ring
  * RingElement Sequence -- evaluation of
    polynomials
  * "runHooks(Sequence,Thing)" -- see runHooks, -- run the hook
    functions stored in an object
  * Sequence # ZZ (missing documentation)
  * Sequence #? ZZ (missing documentation)
  * Sequence == Sequence (missing documentation)
  * "setRandomSeed(Sequence)" -- see setRandomSeed, -- set
    starting point for random number generator
  * SheafOfRings Sequence (missing documentation)
  * span(Sequence) -- construct smallest interval
  * String ^ Sequence -- vertically stacked copies of
    a string
  * String _ Sequence -- substring
  * "submatrixByDegrees(Matrix,Sequence,Sequence)" -- see
    submatrixByDegrees, -- submatrix consisting of rows and
    columns in an interval or box of degrees
  * "subsets(Sequence,ZZ)" -- see subsets, -- produce the
    subsets of a set or list
  * "substring(Sequence,String)" -- see substring, -- extract
    part of a string
  * "SYNOPSIS(Sequence)" -- see SYNOPSIS, -- a standardized
    synopsis for use in documentation nodes
  * "tensor(Sequence)" -- see tensor, -- tensor product
  * union(Sequence) (missing documentation)
  * "vars(Sequence)" -- see vars(List), -- a sequence of
    variables
  * "WrapperType Sequence" -- see WrapperType, -- a class of
    lists with abbreviated constructors

For the programmer
==================

The object Sequence, is a type, with ancestor
classes VisibleList, < BasicList <
Thing.

Array -- the class of all arrays -- [...]
*****************************************

Description
===========

An array can be created by enclosing elements of any type in brackets.

+----------------+
|i1 : x = [a,b,c]|
|                |
|o1 = [a, b, c]  |
|                |
|o1 : Array      |
+----------------+
|i2 : # x        |
|                |
|o2 = 3          |
+----------------+
|i3 : x#1        |
|                |
|o3 = b          |
|                |
|o3 : Symbol     |
+----------------+

To convert arrays to and from other types of BasicList, one
may use new.

+------------------------------+
|i4 : new Array from {a,b,c}   |
|                              |
|o4 = [a, b, c]                |
|                              |
|o4 : Array                    |
+------------------------------+
|i5 : new Sequence from [a,b,c]|
|                              |
|o5 = (a, b, c)                |
|                              |
|o5 : Sequence                 |
+------------------------------+

For an overview of lists and sequences, see lists and sequences.

Functions and methods returning an array:
=========================================

  * "Array | Array" -- see List | List, -- join lists,
    sequences or arrays

Methods that use an array:
==========================

  * "BettiTally Array" -- see BettiTally, -- the class of all
    Betti tallies
  * ChainComplex Array -- degree shift
  * ChainComplexMap Array -- degree shift
  * CoherentSheaf ^ Array (missing documentation)
  * CoherentSheaf _ Array (missing documentation)
  * GradedModule Array -- degree shift
  * "help(Array)" -- see help, -- view documentation nodes
  * Ideal ^ Array -- bracket power of an ideal
  * "MonomialIdeal ^ Array" -- see Ideal ^ Array, --
    bracket power of an ideal
  * "interval(Array)" -- see interval, -- construct an interval
  * "ChainComplexMap ^ Array" -- see Matrix ^ Array, --
    component of map corresponding to summand of target
  * "GradedModuleMap ^ Array" -- see Matrix ^ Array, --
    component of map corresponding to summand of target
  * Matrix ^ Array -- component of map corresponding to
    summand of target
  * "ChainComplexMap _ Array" -- see Matrix _ Array, --
    component of map corresponding to summand of source
  * "GradedModuleMap _ Array" -- see Matrix _ Array, --
    component of map corresponding to summand of source
  * Matrix _ Array -- component of map corresponding
    to summand of source
  * "ChainComplex ^ Array" -- see Module ^ Array, --
    projection onto summand
  * Module ^ Array -- projection onto summand
  * "ChainComplex _ Array" -- see Module _ Array, --
    inclusion from summand
  * Module _ Array -- inclusion from summand
  * Module Array -- make a chain complex from a module
  * "monoid(Array)" -- see monoid, -- make or retrieve a monoid
  * MonoidElement Array (missing documentation)
  * "package(Array)" -- see package, -- get containing package
  * "InexactFieldFamily Array" -- see Ring Array, -- the
    standard way to make a polynomial ring
  * Ring Array -- the standard way to make a polynomial ring

For the programmer
==================

The object Array, is a type, with ancestor classes
VisibleList < BasicList < Thing.

VisibleList / Function -- apply a function to elements of a list
****************************************************************

Synopsis
========

  * Operator: /,
  * Usage:
        x/f
        f\x
  * Inputs:
      * x, a visible list, a list, a
        sequence, an array, a tally, a
        set, or a string,
      * f, a function, a command, a self initializing type,
        or a ring map,
  * Outputs:
      * the list, tally, or set obtained by applying f to each element of x; it
        has the same type as x has

Description
===========

The function apply, does the same thing.

The operator /, is left associative, which means that w / f / g is
interpreted as (w / f) / g. The operator \, is right associative, so g
\ f \ w is interpreted as g \ (f \ w). Both operators have parsing precedence
lower than that of @@, which means that the previous two expressions
are equivalent to w / g @@ f and g @@ f \ w, respectively. See precedence of operators.

+---------------------------------------------+
|i1 : f = x -> x+1                            |
|                                             |
|o1 = f                                       |
|                                             |
|o1 : FunctionClosure                         |
+---------------------------------------------+
|i2 : g = x -> 2*x                            |
|                                             |
|o2 = g                                       |
|                                             |
|o2 : FunctionClosure                         |
+---------------------------------------------+
|i3 : g \ (1 .. 10)                           |
|                                             |
|o3 = (2, 4, 6, 8, 10, 12, 14, 16, 18, 20)    |
|                                             |
|o3 : Sequence                                |
+---------------------------------------------+
|i4 : (1 .. 10) / g                           |
|                                             |
|o4 = (2, 4, 6, 8, 10, 12, 14, 16, 18, 20)    |
|                                             |
|o4 : Sequence                                |
+---------------------------------------------+
|i5 : f \ g \ (1 .. 10)                       |
|                                             |
|o5 = (3, 5, 7, 9, 11, 13, 15, 17, 19, 21)    |
|                                             |
|o5 : Sequence                                |
+---------------------------------------------+
|i6 : f @@ g \ (1 .. 10)                      |
|                                             |
|o6 = (3, 5, 7, 9, 11, 13, 15, 17, 19, 21)    |
|                                             |
|o6 : Sequence                                |
+---------------------------------------------+
|i7 : set (1 .. 10)                           |
|                                             |
|o7 = set {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}     |
|                                             |
|o7 : Set                                     |
+---------------------------------------------+
|i8 : g \ oo                                  |
|                                             |
|o8 = set {16, 18, 2, 20, 4, 6, 8, 10, 12, 14}|
|                                             |
|o8 : Set                                     |
+---------------------------------------------+
|i9 : R = QQ[x];                              |
+---------------------------------------------+
|i10 : f = map(R,R,{x^2})                     |
|                                             |
|                   2                         |
|o10 = map (R, R, {x })                       |
|                                             |
|o10 : RingMap R <-- R                        |
+---------------------------------------------+
|i11 : f \ {x,x^2,x^3,x^4}                    |
|                                             |
|        2   4   6   8                        |
|o11 = {x , x , x , x }                       |
|                                             |
|o11 : List                                   |
+---------------------------------------------+

Code
====

../../../../../Macaulay2/m2/classes.m2:83:42-83:61: --source code:
VisibleList /  Function := VisibleList => (v,f) -> apply(v,f)

Ways to use this method:
========================

  * "List / Command"
  * "List / Function"
  * "String / Command"
  * "String / Function"
  * "VirtualTally / Command"
  * "VirtualTally / Function"
  * "VisibleList / Command"
  * VisibleList / Function -- apply a function
    to elements of a list
  * "VisibleList / RingMap"
  * "VisibleList / SelfInitializingType"

VisibleList _ List -- get some entries of a list
************************************************

Synopsis
========

  * Operator: _,
  * Usage:
        w_{i,j,...}
  * Inputs:
      * w
      * {i,j,...}, a list of integers to serve as indices
  * Outputs:
      * the list of entries {w_i, w_j, ...}

Description
===========

The entries of w are numbered starting with 0.  If  i is negative, then the
i-th entry counting from the end is provided. If i is out of range, an error is
signaled.

+-----------------------------+
|i1 : w = {a,b,c,d,e,f,g,h}   |
|                             |
|o1 = {a, b, c, d, e, f, g, h}|
|                             |
|o1 : List                    |
+-----------------------------+
|i2 : w_{1,3,4}               |
|                             |
|o2 = {b, d, e}               |
|                             |
|o2 : List                    |
+-----------------------------+
|i3 : w_{-1,-2,-3}            |
|                             |
|o3 = {h, g, f}               |
|                             |
|o3 : List                    |
+-----------------------------+

We can use this operation to compute composition of permutations represented as
lists.
+------------------------------+
|i4 : {4,2,3,1,0} _ {2,1,3,4,0}|
|                              |
|o4 = {3, 2, 1, 0, 4}          |
|                              |
|o4 : List                     |
+------------------------------+

Remark: any subscripts that are sequences will have their elements spliced into
the rest of the list.
+-----------------------+
|i5 : {a,b,c,d,e}_{2..4}|
|                       |
|o5 = {c, d, e}         |
|                       |
|o5 : List              |
+-----------------------+

See also
========

  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2
  * VisibleList _ ZZ -- get element from list

Ways to use this method:
========================

  * VisibleList _ List -- get some entries of a
    list

VisibleList _ ZZ -- get element from list
*****************************************

Synopsis
========

  * Operator: _,
  * Usage:
        x_i
  * Inputs:
      * x
      * i
  * Outputs:
      * the i-th element of the list x

Description
===========

The entries of the list, sequence or array are numbered starting with 0.  If  i
is negative, then the i-th entry counting from the end is provided. If i is out
of range, an error is signaled.

+-----------------------------------------------------------------+
|i1 : x = a..t                                                    |
|                                                                 |
|o1 = (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t)|
|                                                                 |
|o1 : Sequence                                                    |
+-----------------------------------------------------------------+
|i2 : #x                                                          |
|                                                                 |
|o2 = 20                                                          |
+-----------------------------------------------------------------+
|i3 : x_-1, x_19, x_0                                             |
|                                                                 |
|o3 = (t, t, a)                                                   |
|                                                                 |
|o3 : Sequence                                                    |
+-----------------------------------------------------------------+

Caveat
======

Lists are immutable objects, i.e. you cannot assign to them.  See
MutableList, for lists that you may modify.

See also
========

  * BasicList # ZZ -- get value from list, hash table,
    database, or string

Ways to use this method:
========================

  * VisibleList _ ZZ -- get element from list

w3
**

You may download the package w3, by William M. Perry, from
http://www.cs.indiana.edu/elisp/w3/docs.html.  It is an emacs package that
implements a web browser that displays web pages within emacs.

WebApp -- the web app top level printing method
***********************************************

Description
===========

This symbol is used (tentatively) as the first element of a pair to specify
various top level interpreter methods, in connection with the use of the
(currently developed) web app with (Ka)TeX output as front end.

See also
========

  * Standard -- the standard top level printing method
  * Print -- top level method for printing results
  * NoPrint -- top level method for non-printing results
  * BeforePrint -- top level method applied before printing
    results
  * AfterPrint -- top level method applied after printing
  * AfterNoPrint -- top level method applied after not
    printing

For the programmer
==================

The object WebApp, is a symbol.

wedgeProduct(ZZ,ZZ,Module) -- the exterior multiplication map
*************************************************************

Synopsis
========

  * Function: wedgeProduct,
  * Usage:
        wedgeProduct(p,q,F)
  * Inputs:
      * p
      * q
      * F, a free module
  * Outputs:
      * a matrix, representing the multiplication map from
        exteriorPower(p,M) ** exteriorPower(q,M) to exteriorPower(p+q,M)

Description
===========

+----------------------------------------------+
|i1 : F = QQ^4                                 |
|                                              |
|       4                                      |
|o1 = QQ                                       |
|                                              |
|o1 : QQ-module, free                          |
+----------------------------------------------+
|i2 : wedgeProduct(1,1,F)                      |
|                                              |
|o2 = | 0 1 0 0 -1 0 0 0 0  0  0 0 0  0  0  0 ||
|     | 0 0 1 0 0  0 0 0 -1 0  0 0 0  0  0  0 ||
|     | 0 0 0 0 0  0 1 0 0  -1 0 0 0  0  0  0 ||
|     | 0 0 0 1 0  0 0 0 0  0  0 0 -1 0  0  0 ||
|     | 0 0 0 0 0  0 0 1 0  0  0 0 0  -1 0  0 ||
|     | 0 0 0 0 0  0 0 0 0  0  0 1 0  0  -1 0 ||
|                                              |
|              6       16                      |
|o2 : Matrix QQ  <-- QQ                        |
+----------------------------------------------+

See also
========

  * exteriorPower -- exterior power

Ways to use this method:
========================

  * wedgeProduct(ZZ,ZZ,Module), --
    the exterior multiplication map

weightRange -- the pair of lowest and highest weights of the monomials
**********************************************************************

Description
===========

Synopsis
========

  * Usage:
        (lo,hi) = weightRange(w,f)
  * Inputs:
      * w, a list, of integers, the weight of each variable
      * f, a ring element, in a polynomial ring
  * Outputs:
      * lo, an integer, the least weight of the monomials of f
      * hi, an integer, the greatest weight of the monomials of f
The weight of a monomial is the dot product of w and the exponent vector. If
the weight vector has length smaller than the number of variables, the other
variables are assumed to have weight zero.  If there are too many weights
given, the extras are silently ignored.
+-----------------------------------+
|i1 : R = QQ[a..g]                  |
|                                   |
|o1 = R                             |
|                                   |
|o1 : PolynomialRing                |
+-----------------------------------+
|i2 : f = a^3+b^2*c+3*f^10*d-1+e-e  |
|                                   |
|         10    3    2              |
|o2 = 3d*f   + a  + b c - 1         |
|                                   |
|o2 : R                             |
+-----------------------------------+
|i3 : weightRange({1,1,0,0,0,0,0},f)|
|                                   |
|o3 = (0, 3)                        |
|                                   |
|o3 : Sequence                      |
+-----------------------------------+
Use  terms, and weightRange, together to select
the terms which have a given weight.
+------------------------------------------------------------+
|i4 : f = a^2*b+3*a^2*c+b*c+1                                |
|                                                            |
|      2      2                                              |
|o4 = a b + 3a c + b*c + 1                                   |
|                                                            |
|o4 : R                                                      |
+------------------------------------------------------------+
|i5 : sum select(terms f, t -> (weightRange({1,0},t))#0 == 2)|
|                                                            |
|      2      2                                              |
|o5 = a b + 3a c                                             |
|                                                            |
|o5 : R                                                      |
+------------------------------------------------------------+
If the coefficient ring is a polynomial ring, one can use the weights of these
variables too.  The order of weights is the same as the order of variables (see
index)
+---------------------------------------+
|i6 : S = R[x,y];                       |
+---------------------------------------+
|i7 : weightRange({0,0,3,7},a*x^2+b*x*y)|
|                                       |
|o7 = (3, 7)                            |
|                                       |
|o7 : Sequence                          |
+---------------------------------------+

Synopsis
========

  * Usage:
        (lo,hi) = weightRange f
  * Inputs:
      * f, a ring element,
  * Outputs:
      * lo, an integer, the minimum value for (the first component
        of) the degrees of the monomials occurring in f
      * hi, an integer, the corresponding maximum value
+----------------------------+
|i8 : R = QQ[x,y];           |
+----------------------------+
|i9 : weightRange (x^3+y^2)^5|
|                            |
|o9 = (10, 15)               |
|                            |
|o9 : Sequence               |
+----------------------------+

See also
========

  * degree
  * homogenize -- homogenize with respect to a variable
  * part -- select terms of a polynomial by degree(s) or weight(s)
  * index -- numeric index of a ring variable

Ways to use weightRange:
========================

  * "weightRange(List,RingElement)"
  * "weightRange(RingElement)"

For the programmer
==================

The object weightRange, is a method function.

when -- a keyword
*****************

Description
===========

A keyword used in for, loops.

For the programmer
==================

The object when, is a keyword.

width -- width of a file or net
*******************************

Ways to use width:
==================

  * width(File) -- get window width
  * width(Net) -- width of a net
  * "width(String)" -- see width(Net), -- width of a net

For the programmer
==================

The object width, is a method function.

width(File) -- get window width
*******************************

Synopsis
========

  * Function: width,
  * Usage:
        width f
  * Inputs:
      * f
  * Outputs:
      * an integer, the width of the window or terminal attached to
        the file f, if any, else 0

Ways to use this method:
========================

  * width(File) -- get window width

Wrap -- a key for methods for wrapping printed output
*****************************************************

Description
===========

The default method for printing results of computations (stored in
Thing#{Standard,Print}) searches for a method for wrapping the output by search
in the class of the result (and its ancestors) for a function stored under the
key Wrap.  The preinstalled wrapping methods use wrap, they differ
in their choice of separator between wrapped lines, or in whether to wrap at
all.
+--------------------------------------------------------------------------+
|i1 : QQ[x_0 .. x_40 ]                                                     |
|                                                                          |
|o1 = QQ[x ..x  ]                                                          |
|         0   40                                                           |
|                                                                          |
|o1 : PolynomialRing                                                       |
+--------------------------------------------------------------------------+
|i2 : concatenate(50:"abcd ")                                              |
|                                                                          |
|o2 = abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd|
|     abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd|
|     abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd abcd|
|     abcd abcd abcd abcd abcd abcd abcd abcd                              |
+--------------------------------------------------------------------------+

For the programmer
==================

The object Wrap, is a symbol.

wrap
****

Synopsis
========

  * Usage:
        wrap(wid,sep,s)
  * Inputs:
      * wid, an integer,
      * sep, a string,
      * s, a string,
  * Outputs:
      * a string obtained by wrapping the string s, in case it is wider than
        the number wid, so that it occupies multiple lines, separated by lines
        filled with the single character in the string sep, if provided

Description
===========

The inputs wid and sep are optional, and can be given in either order.  The
default for wid is printWidth, and the default for sep is null.
+----------------------------------------------+
|i1 : wrap(10,"abcdefghijklmnopqrstuvwxyz")    |
|                                              |
|o1 = abcdefghij                               |
|     klmnopqrst                               |
|     uvwxyz                                   |
+----------------------------------------------+
|i2 : wrap(10,"-","abcdefghijklmnopqrstuvwxyz")|
|                                              |
|o2 = abcdefghij                               |
|     ----------                               |
|     klmnopqrst                               |
|     ----------                               |
|     uvwxyz                                   |
+----------------------------------------------+

For the programmer
==================

The object wrap, is a compiled function.

WrapperType -- a class of lists with abbreviated constructors
*************************************************************

Description
===========

These are the types X of lists that can be constructed by expressions of the
form X {a,b,c,...}, or, for lists of length one, by an expression of the form X
a.  They also act on sequences.

+-------------------------------------+
|i1 : X = new WrapperType of BasicList|
|                                     |
|o1 = X                               |
|                                     |
|o1 : WrapperType                     |
+-------------------------------------+
|i2 : X {a,b,c}                       |
|                                     |
|o2 = X{a, b, c}                      |
|                                     |
|o2 : X                               |
+-------------------------------------+
|i3 : X a                             |
|                                     |
|o3 = X{a}                            |
|                                     |
|o3 : X                               |
+-------------------------------------+

See also
========

  * HeaderType -- a class of lists with abbreviated
    constructors
  * SelfInitializingType -- the class of all self
    initializing types

Methods that use a wrapper type:
================================

  * "WrapperType List"
  * "WrapperType Sequence"
  * "WrapperType Thing"

Protected objects of class WrapperType:
=======================================

  * Describe -- the class of the output of describe
  * DirectSum (missing documentation)
  * Holder -- the class of all holder expressions
  * Minus -- the class of all minus expressions
  * Parenthesize
  * Product -- the class of all product expressions
  * SheafExpression (Varieties) -- the class of sheaf
    expressions
  * Sum -- the class of all sum expressions
  * TensorProduct (missing documentation)

For the programmer
==================

The object WrapperType, is a type, with
ancestor classes Type, < MutableHashTable
< HashTable < Thing.

xor -- exclusive disjunction
****************************

Synopsis
========

  * Usage:
        t xor u
  * Inputs:
      * t, a Boolean value,
      * u, a Boolean value,
  * Outputs:
      * a Boolean value, equivalent to t and not u or not t and
        u

See also
========

  * and -- conjunction
  * or -- disjunction

Ways to use symbol xor:
=======================

  * "Boolean xor Boolean"

For the programmer
==================

The object xor, is a keyword.

This operator may be used as a binary operator in an expression like x xor y.
The user may install binary methods, for handling such
expressions with code such as

         X  xor  Y := (x,y) -> ...

where X is the class of x and Y is the class of y.

youngest -- the youngest member of a sequence
*********************************************

Description
===========

youngest s -- return the youngest mutable hash table in the sequence s, if any,
else null.

For the programmer
==================

The object youngest, is a compiled function.

zero -- whether something is zero
*********************************

Synopsis
========

  * Usage:
        zero x
  * Inputs:
      * x
  * Outputs:
      * whether x is equal to 0

Code
====

../../../../../Macaulay2/m2/integers.m2:74:7-74:18: --source code:
zero = x -> x == 0                                          -- we use == so
-------------------------------------------------------------------------------
this can apply to all types of things

For the programmer
==================

The object zero, is a function closure.

ZeroExpression -- the class of all zero expressions
***************************************************

Description
===========

ZeroExpression a type of Expression, of which there is just
one instance, an expression representing the number 0.

For the programmer
==================

The object ZeroExpression, is a type, with
ancestor classes Holder, < Expression <
BasicList < Thing.

zeta -- Riemann zeta function
*****************************

Synopsis
========

  * Usage:
        zeta x
  * Inputs:
      * x
  * Outputs:
      * a real number, the zeta function of x

Description
===========

+-------------------------+
|i1 : zeta 2              |
|                         |
|o1 = 1.644934066848226   |
|                         |
|o1 : RR (of precision 53)|
+-------------------------+

See Riemann zeta function (see
https://en.wikipedia.org/wiki/Riemann_zeta_function ).

Ways to use zeta:
=================

  * "zeta(CC)"
  * "zeta(RR)"
  * "zeta(RRi)"

For the programmer
==================

The object zeta, is a method function.

ZZ -- the class of all integers
*******************************

Functions and methods returning an integer:
===========================================

  * # BasicList -- length or cardinality
  * "# HashTable" -- see # BasicList, -- length or
    cardinality
  * "# Set" -- see # BasicList, -- length or cardinality
  * "# String" -- see # BasicList, -- length or cardinality
  * # Dictionary (missing documentation)
  * # List (missing documentation)
  * # Net (missing documentation)
  * # Sequence (missing documentation)
  * "ZZ * ZZ" -- see *, -- a binary operator, usually used for
    multiplication
  * "+ ZZ" -- see +, -- a unary or binary operator, usually used for
    addition
  * "ZZ + ZZ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "- ZZ" -- see -, -- a unary or binary operator, usually used for
    negation or subtraction
  * "ZZ - ZZ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "ZZ / ZZ" -- see /, -- a binary operator, usually used for
    division
  * "ZZ // ZZ" -- see //, -- a binary operator, usually used for
    quotient
  * ambDim (Polyhedra) -- ambient dimension of a Polyhedron, Cone
    or Fan
  * "analyticSpread(Ideal)" -- see analyticSpread (ReesAlgebra),
    -- Compute the analytic spread of a module or
    ideal
  * "analyticSpread(Ideal,RingElement)" -- see analyticSpread (ReesAlgebra),
    -- Compute the analytic spread of a module or
    ideal
  * "analyticSpread(Module)" -- see analyticSpread (ReesAlgebra),
    -- Compute the analytic spread of a module or
    ideal
  * "analyticSpread(Module,RingElement)" -- see analyticSpread (ReesAlgebra),
    -- Compute the analytic spread of a module or
    ideal
  * AtomicInt &= ZZ -- atomic fetch and bitwise and
  * AtomicInt += ZZ -- atomic fetch and add
  * AtomicInt -= ZZ -- atomic fetch and subtract
  * AtomicInt ^^= ZZ -- atomic fetch and bitwise xor
  * AtomicInt |= ZZ -- atomic fetch and bitwise or
  * binomial -- binomial coefficient
  * "binomial(Number,Number)" -- see binomial, -- binomial
    coefficient
  * "binomial(ZZ,ZZ)" -- see binomial, -- binomial coefficient
  * "changeBase(String,ZZ)" -- see changeBase, -- change
    integer base
  * char -- computes the characteristic of the ring or field
  * degree(SheafMap) (missing documentation)
  * degreeLength -- the length of the degree vector
  * depth -- depth of a net
  * dim -- compute the Krull dimension
  * "dim(GaloisField)" -- see dim(Ring), -- compute the
    Krull dimension
  * euler (missing documentation)
  * fileMode(String) -- get file mode
  * "gcd(ZZ,ZZ)" -- see gcd, -- greatest common divisor
  * genus (missing documentation)
  * height -- height of a net
  * "leadComponent(Vector)" -- see leadComponent, -- the
    leading component(s) of a vector or matrix
  * length -- length of an object
  * length(Module) -- Computes the length of a
    module
  * "maxPosition(BasicList)" -- see maxPosition, -- position
    of the largest element
  * "minPosition(BasicList)" -- see minPosition, -- position
    of the smallest element
  * "multiplicity(Ideal)" -- see multiplicity (ReesAlgebra),
    -- Compute the Hilbert-Samuel multiplicity of an ideal
  * "multiplicity(Ideal,RingElement)" -- see multiplicity (ReesAlgebra),
    -- Compute the Hilbert-Samuel multiplicity of an
    ideal
  * nextPrime -- compute the smallest prime greater than or
    equal to a given number
  * "numColumns" -- see numColumns(Matrix), --
    number of columns in a matrix or mutable matrix
  * numgens -- the number of generators
  * "numRows" -- see numRows(Matrix), -- number of
    rows in a matrix or mutable matrix
  * nVertices (Polyhedra) -- Returns the number of vertices of
    a polyhedron
  * pdim -- calculate the projective dimension
  * position -- the first element of a list satisfying a
    condition
  * "powermod(ZZ,ZZ,ZZ)" -- see powermod, -- powers of integers
    mod N
  * "random(ZZ)" -- see random(ZZ,ZZ), -- get a
    random integer or real number
  * random(ZZ,ZZ) -- get a random integer or real
    number
  * rank -- compute the rank
  * regularity -- compute the Castelnuovo-Mumford regularity
  * "size2(CC)" -- see size2, -- number of binary digits to the
    left of the point
  * "size2(RR)" -- see size2, -- number of binary digits to the
    left of the point
  * "size2(RRi)" -- see size2, -- number of binary digits to the
    left of the point
  * "size2(ZZ)" -- see size2, -- number of binary digits to the
    left of the point
  * width -- width of a file or net
  * ZZ & ZZ -- logical and

Methods that use an integer:
============================

  * "ZZ !" -- see !, -- factorial
  * "BasicList #? ZZ" -- see #?, -- check existence of value in a
    list, hash table, database, or string
  * "String #? ZZ" -- see #?, -- check existence of value in a list,
    hash table, database, or string
  * "CC % ZZ" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "QQ % ZZ" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "RR % ZZ" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "ZZ % MonomialIdeal" -- see %, -- a binary operator, usually used
    for remainder and reduction
  * "ZZ % ZZ" -- see %, -- a binary operator, usually used for
    remainder and reduction
  * "CC * ZZ" -- see *, -- a binary operator, usually used for
    multiplication
  * "ProjectiveHilbertPolynomial * ZZ" -- see *, -- a binary
    operator, usually used for multiplication
  * "QQ * ZZ" -- see *, -- a binary operator, usually used for
    multiplication
  * "RR * ZZ" -- see *, -- a binary operator, usually used for
    multiplication
  * "RRi * ZZ" -- see *, -- a binary operator, usually used for
    multiplication
  * "ZZ * CC" -- see *, -- a binary operator, usually used for
    multiplication
  * "ZZ * ProjectiveHilbertPolynomial" -- see *, -- a binary
    operator, usually used for multiplication
  * "ZZ * QQ" -- see *, -- a binary operator, usually used for
    multiplication
  * "ZZ * RR" -- see *, -- a binary operator, usually used for
    multiplication
  * "ZZ * RRi" -- see *, -- a binary operator, usually used for
    multiplication
  * "CC + ZZ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "ChainComplexMap + ZZ" -- see +, -- a unary or binary operator,
    usually used for addition
  * "ProjectiveHilbertPolynomial + ZZ" -- see +, -- a unary or binary
    operator, usually used for addition
  * "QQ + ZZ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RR + ZZ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "RRi + ZZ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "ZZ + CC" -- see +, -- a unary or binary operator, usually used
    for addition
  * "ZZ + ChainComplexMap" -- see +, -- a unary or binary operator,
    usually used for addition
  * "ZZ + ProjectiveHilbertPolynomial" -- see +, -- a unary or binary
    operator, usually used for addition
  * "ZZ + QQ" -- see +, -- a unary or binary operator, usually used
    for addition
  * "ZZ + RR" -- see +, -- a unary or binary operator, usually used
    for addition
  * "ZZ + RRi" -- see +, -- a unary or binary operator, usually used
    for addition
  * "CC - ZZ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "ProjectiveHilbertPolynomial - ZZ" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "QQ - ZZ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RR - ZZ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "RRi - ZZ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "ZZ - CC" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "ZZ - ProjectiveHilbertPolynomial" -- see -, -- a unary or binary
    operator, usually used for negation or subtraction
  * "ZZ - QQ" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "ZZ - RR" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "ZZ - RRi" -- see -, -- a unary or binary operator, usually used
    for negation or subtraction
  * "CC / ZZ" -- see /, -- a binary operator, usually used for
    division
  * "QQ / ZZ" -- see /, -- a binary operator, usually used for
    division
  * "RR / ZZ" -- see /, -- a binary operator, usually used for
    division
  * "RRi / ZZ" -- see /, -- a binary operator, usually used for
    division
  * "ZZ / CC" -- see /, -- a binary operator, usually used for
    division
  * "ZZ / QQ" -- see /, -- a binary operator, usually used for
    division
  * "ZZ / RR" -- see /, -- a binary operator, usually used for
    division
  * "ZZ / RRi" -- see /, -- a binary operator, usually used for
    division
  * "CC // ZZ" -- see //, -- a binary operator, usually used for
    quotient
  * "QQ // ZZ" -- see //, -- a binary operator, usually used for
    quotient
  * "RR // ZZ" -- see //, -- a binary operator, usually used for
    quotient
  * "ZZ // MonomialIdeal" -- see //, -- a binary operator, usually
    used for quotient
  * > ZZ (Varieties)
  * >= ZZ (Varieties)
  * "ZZ ^^ ZZ" -- see ^^, -- logical exclusive-or
  * "help(ZZ)" -- see about, -- search the documentation
  * "infoHelp(ZZ)" -- see about, -- search the documentation
  * "viewHelp(ZZ)" -- see about, -- search the documentation
  * "abs(ZZ)" -- see abs, -- absolute value function
  * "all(ZZ,Function)" -- see all(BasicList,Function),
    -- whether all elements of a list satisfy a
    specified condition
  * "any(ZZ,Function)" -- see any(BasicList,Function),
    -- whether any elements of a list satisfy a
    specified condition
  * apply(ZZ,Function) -- apply a function to
    {0,..., n-1}
  * "ascii(ZZ)" -- see ascii, -- ASCII character conversion
  * BasicList # ZZ -- get value from list, hash table,
    database, or string
  * "String # ZZ" -- see BasicList # ZZ, -- get value
    from list, hash table, database, or string
  * "basis(InfiniteNumber,ZZ,Ideal)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,ZZ,Matrix)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,ZZ,Module)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(InfiniteNumber,ZZ,Ring)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(List,ZZ,Ideal)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,ZZ,Matrix)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,ZZ,Module)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(List,ZZ,Ring)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(ZZ,Ideal)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(ZZ,InfiniteNumber,Ideal)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(ZZ,InfiniteNumber,Matrix)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(ZZ,InfiniteNumber,Module)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(ZZ,InfiniteNumber,Ring)" -- see basis, -- basis or
    generating set of all or part of a ring, ideal or module
  * "basis(ZZ,List,Ideal)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(ZZ,List,Matrix)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(ZZ,List,Module)" -- see basis, -- basis or generating
    set of all or part of a ring, ideal or module
  * "basis(ZZ,List,Ring)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(ZZ,Matrix)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(ZZ,Module)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(ZZ,Ring)" -- see basis, -- basis or generating set of
    all or part of a ring, ideal or module
  * "basis(ZZ,RingMap)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(ZZ,ZZ,Ideal)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(ZZ,ZZ,Matrix)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(ZZ,ZZ,Module)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "basis(ZZ,ZZ,Ring)" -- see basis, -- basis or generating set
    of all or part of a ring, ideal or module
  * "BesselJ(ZZ,Number)" -- see BesselJ, -- Bessel function of
    the first kind
  * "BesselY(ZZ,Number)" -- see BesselY, -- Bessel function of
    the second kind
  * "BettiTally ZZ" -- see BettiTally, -- the class of all
    Betti tallies
  * "hilbertPolynomial(ZZ,BettiTally)" -- see BettiTally, --
    the class of all Betti tallies
  * "hilbertSeries(ZZ,BettiTally)" -- see BettiTally, -- the
    class of all Betti tallies
  * "lift(BettiTally,type of ZZ)" -- see BettiTally, -- the
    class of all Betti tallies
  * "ZZ * BettiTally" -- see BettiTally, -- the class of all
    Betti tallies
  * "binomial(RingElement,ZZ)" -- see binomial, -- binomial
    coefficient
  * CC == ZZ (missing documentation)
  * ChainComplex == ZZ (missing documentation)
  * ChainComplex ^ ZZ -- access member, cohomological
    degree
  * ChainComplex _ ZZ -- component
  * "GradedModule _ ZZ" -- see ChainComplex _ ZZ, --
    component
  * ChainComplex _ ZZ = Thing -- install
    component of chain complex
  * ChainComplexMap == ZZ (missing documentation)
  * ChainComplexMap ^ ZZ -- iterated composition
  * "GradedModuleMap ^ ZZ" -- see ChainComplexMap ^ ZZ,
    -- iterated composition
  * ChainComplexMap _ ZZ -- component map
  * "GradedModuleMap _ ZZ" -- see ChainComplexMap _ ZZ,
    -- component map
  * ChainComplexMap _ ZZ = Thing, --
    install component of chain complex map
  * "changeBase(String,ZZ,ZZ)" -- see changeBase, -- change
    integer base
  * "changeBase(ZZ,ZZ)" -- see changeBase, -- change integer
    base
  * "check(ZZ,Package)" -- see check, -- perform tests of a
    package
  * "check(ZZ,String)" -- see check, -- perform tests of a package
  * "code(ZZ)" -- see code, -- display source code
  * CoherentSheaf == ZZ (missing documentation)
  * CoherentSheaf ^ ZZ (Varieties) -- direct sum
  * "SheafOfRings ^ ZZ" -- see CoherentSheaf ^ ZZ (Varieties),
    -- direct sum
  * CoherentSheaf ^** ZZ (Varieties) -- tensor
    power
  * CoherentSheaf ZZ (Varieties) -- canonical twist of
    a coherent sheaf
  * "SheafOfRings ZZ" -- see CoherentSheaf ZZ (Varieties),
    -- canonical twist of a coherent sheaf
  * "columnAdd(MutableMatrix,ZZ,Number,ZZ)" -- see columnAdd,
    -- add a multiple of one column to another
  * "columnAdd(MutableMatrix,ZZ,RingElement,ZZ)" -- see columnAdd,
    -- add a multiple of one column to another
  * "columnMult(MutableMatrix,ZZ,Number)" -- see columnMult,
    -- multiply a column by a ring element
  * "columnMult(MutableMatrix,ZZ,RingElement)" -- see columnMult,
    -- multiply a column by a ring element
  * "columnPermute(MutableMatrix,ZZ,List)" -- see columnPermute,
    -- permute some columns
  * "columnSwap(MutableMatrix,ZZ,ZZ)" -- see columnSwap, --
    interchange columns
  * "compareExchange(AtomicInt,ZZ,ZZ)" -- see compareExchange,
    -- compares and possibly exchanges the value of an atomic
    integer
  * "compositions(ZZ,ZZ)" -- see compositions, -- list the
    compositions of an integer
  * compositions(ZZ) (missing documentation)
  * "concatenate(ZZ)" -- see concatenate, -- join strings
  * "cones(ZZ,Fan)" -- see cones (Polyhedra), -- computes all cones
    of a fan of a certain dimension
  * "conwayPolynomial(ZZ)" -- see conwayPolynomial (ConwayPolynomials),
    -- provide a Conway polynomial
  * "conwayPolynomial(ZZ,ZZ)" -- see conwayPolynomial (ConwayPolynomials),
    -- provide a Conway polynomial
  * cotangentSheaf(ZZ,ProjectiveVariety) (Varieties)
    -- exterior powers
    of the cotangent sheaf of a projective variety
  * "crossPolytope(ZZ)" -- see crossPolytope (Polyhedra),
    -- computes the d-dimensional crosspolytope with diameter 2s
  * "crossPolytope(ZZ,QQ)" -- see crossPolytope (Polyhedra),
    -- computes the d-dimensional crosspolytope with
    diameter 2s
  * "crossPolytope(ZZ,ZZ)" -- see crossPolytope (Polyhedra),
    -- computes the d-dimensional crosspolytope with
    diameter 2s
  * "cyclicPolytope(ZZ,ZZ)" -- see cyclicPolytope (Polyhedra),
    -- computes the d dimensional cyclic polytope
    with n vertices
  * debug(ZZ) (missing documentation)
  * "degreesMonoid(ZZ)" -- see degreesRing(List),
    -- the ring or monoid of degrees
  * "degreesRing(ZZ)" -- see degreesRing(List), --
    the ring or monoid of degrees
  * diagonalMatrix(Ring,ZZ,ZZ,List)
    -- make a diagonal matrix from a
    list
  * "diagonalMatrix(RingFamily,ZZ,ZZ,List)" -- see
    diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a list
  * "diagonalMatrix(ZZ,ZZ,List)" -- see diagonalMatrix(Ring,ZZ,ZZ,List),
    -- make a diagonal matrix from a
    list
  * diff(ProjectiveHilbertPolynomial,ZZ)
  * "divideByVariable(Matrix,RingElement,ZZ)" -- see divideByVariable,
    -- divide all columns by a (power of a) variable
  * "drop(BasicList,ZZ)" -- see drop, -- drop some elements from a
    list or sequence.
  * "emptyPolyhedron(ZZ)" -- see emptyPolyhedron (Polyhedra),
    -- generates the empty polyhedron in n-space
  * "examples(ZZ)" -- see examples, -- list the examples in
    documentation
  * "exchange(AtomicInt,ZZ)" -- see exchange, -- exchange the
    value of an atomic integer
  * Ext^ZZ(CoherentSheaf,CoherentSheaf) (Varieties)
    -- global Ext
  * "Ext^ZZ(CoherentSheaf,SheafOfRings)" -- see
    Ext^ZZ(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Ext
  * "Ext^ZZ(SheafOfRings,CoherentSheaf)" -- see
    Ext^ZZ(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Ext
  * "Ext^ZZ(SheafOfRings,SheafOfRings)" -- see
    Ext^ZZ(CoherentSheaf,CoherentSheaf) (Varieties),
    -- global Ext
  * Ext^ZZ(CoherentSheaf,SheafMap) (missing documentation)
  * Ext^ZZ(CoherentSheaf,SumOfTwists) (Varieties)
    -- global Ext
  * "Ext^ZZ(SheafOfRings,SumOfTwists)" -- see
    Ext^ZZ(CoherentSheaf,SumOfTwists) (Varieties),
    -- global Ext
  * "Ext^ZZ(Matrix,Ideal)" -- see Ext^ZZ(Matrix,Module),
    -- map between Ext modules
  * Ext^ZZ(Matrix,Module) -- map between
    Ext modules
  * "Ext^ZZ(Matrix,Ring)" -- see Ext^ZZ(Matrix,Module),
    -- map between Ext modules
  * "Ext^ZZ(Ideal,Matrix)" -- see Ext^ZZ(Module,Matrix),
    -- map between Ext modules
  * Ext^ZZ(Module,Matrix) -- map between
    Ext modules
  * "Ext^ZZ(Ideal,Ideal)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * "Ext^ZZ(Ideal,Module)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * "Ext^ZZ(Ideal,Ring)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * "Ext^ZZ(Module,Ideal)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * Ext^ZZ(Module,Module) -- Ext module
  * "Ext^ZZ(Module,Ring)" -- see Ext^ZZ(Module,Module),
    -- Ext module
  * Ext^ZZ(Ring,Ideal) (missing documentation)
  * Ext^ZZ(Ring,Matrix) (missing documentation)
  * Ext^ZZ(Ring,Module) (missing documentation)
  * Ext^ZZ(Ring,Ring) (missing documentation)
  * exteriorPower(ZZ,CoherentSheaf) (Varieties)
  * exteriorPower(ZZ,Matrix) -- exterior
    power of a matrix
  * exteriorPower(ZZ,Module) -- exterior
    power of a module
  * "faces(ZZ,PolyhedralObject)" -- see faces (Polyhedra), --
    computes all faces of a certain codimension of a Cone or Polyhedron
  * "facesAsCones(ZZ,Cone)" -- see facesAsCones (Polyhedra),
    -- Returns the faces of a cone as actual cones.
  * "facesAsCones(ZZ,Fan)" -- see facesAsCones (Polyhedra),
    -- Returns the faces of a cone as actual cones.
  * "facesAsPolyhedra(ZZ,Polyhedron)" -- see facesAsPolyhedra (Polyhedra),
    -- Returns the faces of a polyhedron as actual
    polyhedra.
  * "factor(ZZ)" -- see factor(RingElement), --
    factor a ring element
  * Fano(ZZ,Ideal) -- Fano scheme
  * Fano(ZZ,Ideal,Ring) -- Fano scheme
  * fileMode(ZZ,File) -- set file mode
  * fileMode(ZZ,String) -- set file mode
  * "fillMatrix(MutableMatrix,ZZ)" -- see fillMatrix, -- fill
    a mutable matrix with random numbers
  * "fittingIdeal(ZZ,Module)" -- see fittingIdeal, --
    Fitting ideal of a module
  * fittingIdeal(ZZ,Matrix) (missing documentation)
  * "gcd(QQ,ZZ)" -- see gcd, -- greatest common divisor
  * "gcd(RingElement,ZZ)" -- see gcd, -- greatest common divisor
  * "gcd(ZZ,QQ)" -- see gcd, -- greatest common divisor
  * "gcd(ZZ,RingElement)" -- see gcd, -- greatest common divisor
  * "gcdCoefficients(ZZ,ZZ)" -- see gcdCoefficients, --
    gcd with coefficients
  * "Ideal _ ZZ" -- see generators of ideals and modules,
  * "Matrix _ ZZ" -- see generators of ideals and modules,
  * "Module _ ZZ" -- see generators of ideals and modules,
  * "genericMatrix(Ring,RingElement,ZZ,ZZ)" -- see genericMatrix,
    -- make a generic matrix of variables
  * "genericMatrix(Ring,ZZ,ZZ)" -- see genericMatrix, --
    make a generic matrix of variables
  * "genericSkewMatrix(Ring,RingElement,ZZ)" -- see genericSkewMatrix,
    -- make a generic skew symmetric matrix of variables
  * "genericSkewMatrix(Ring,ZZ)" -- see genericSkewMatrix,
    -- make a generic skew symmetric matrix of variables
  * "genericSymmetricMatrix(Ring,RingElement,ZZ)" -- see
    genericSymmetricMatrix, -- make a generic symmetric
    matrix
  * "genericSymmetricMatrix(Ring,ZZ)" -- see genericSymmetricMatrix,
    -- make a generic symmetric matrix
  * "getPrimeWithRootOfUnity(ZZ,ZZ)" -- see getPrimeWithRootOfUnity,
    -- find a prime p with a primitive n-th root of
    unity r in ZZ/p
  * "GF(ZZ)" -- see GF, -- make a finite field
  * "GF(ZZ,ZZ)" -- see GF, -- make a finite field
  * GradedModuleMap == ZZ (missing documentation)
  * Grassmannian(ZZ,ZZ) -- the Grassmannian
    of linear subspaces of a vector space
  * "Grassmannian(ZZ,ZZ,PolynomialRing)" -- see Grassmannian(ZZ,ZZ),
    -- the Grassmannian of linear subspaces of a
    vector space
  * HH^ZZ ChainComplex -- cohomology of a chain
    complex
  * HH^ZZ ChainComplexMap -- cohomology of a
    chain complex map
  * HH^ZZ Module -- local cohomology of a module
  * HH^ZZ SheafMap (missing documentation)
  * HH^ZZ SheafOfRings (Varieties) -- cohomology of a
    sheaf of rings on a projective variety
  * HH^ZZ SumOfTwists (Varieties) -- coherent sheaf
    cohomology module
  * HH^ZZ(AffineVariety,CoherentSheaf) (missing documentation)
  * "HH^ZZ CoherentSheaf" -- see HH^ZZ(ProjectiveVariety,CoherentSheaf) (Varieties),
    -- cohomology of a
    coherent sheaf on a projective variety
  * HH^ZZ(ProjectiveVariety,CoherentSheaf) (Varieties)
    -- cohomology of a
    coherent sheaf on a projective variety
  * HH^ZZ(ProjectiveVariety,SheafMap) (missing documentation)
  * HH^ZZ(ProjectiveVariety,SumOfTwists) (missing documentation)
  * HH^ZZ(Variety,SheafOfRings) (missing documentation)
  * HH_ZZ ChainComplex -- homology of a chain
    complex
  * HH_ZZ ChainComplexMap -- homology of a
    chain complex map
  * HH_ZZ Sequence (missing documentation)
  * "hilbertFunction(ZZ,Ideal)" -- see hilbertFunction,
    -- the Hilbert function
  * "hilbertFunction(ZZ,Module)" -- see hilbertFunction,
    -- the Hilbert function
  * "hilbertFunction(ZZ,Ring)" -- see hilbertFunction,
    -- the Hilbert function
  * "hirzebruch(ZZ)" -- see hirzebruch (Polyhedra), --
    computes the fan of the r-th Hirzebruch surface
  * "hooks(ZZ)" -- see hooks, -- list hooks attached to a key
  * "hypercube(ZZ)" -- see hypercube (Polyhedra), -- Returns
    the d-dimensional hypercube
  * "hypercube(ZZ,QQ)" -- see hypercube (Polyhedra), -- Returns
    the d-dimensional hypercube
  * "hypercube(ZZ,QQ,QQ)" -- see hypercube (Polyhedra), --
    Returns the d-dimensional hypercube
  * "hypercube(ZZ,QQ,ZZ)" -- see hypercube (Polyhedra), --
    Returns the d-dimensional hypercube
  * "hypercube(ZZ,ZZ)" -- see hypercube (Polyhedra), -- Returns
    the d-dimensional hypercube
  * "hypercube(ZZ,ZZ,QQ)" -- see hypercube (Polyhedra), --
    Returns the d-dimensional hypercube
  * "hypercube(ZZ,ZZ,ZZ)" -- see hypercube (Polyhedra), --
    Returns the d-dimensional hypercube
  * "icPIdeal(RingElement,RingElement,ZZ)" -- see icPIdeal (IntegralClosure),
    -- compute the integral closure in prime
    characteristic of a principal ideal
  * Ideal * ZZ (missing documentation)
  * Ideal == ZZ (missing documentation)
  * Ideal ^ ZZ -- power of an ideal
  * "MonomialIdeal ^ ZZ" -- see Ideal ^ ZZ, -- power of an
    ideal
  * "imaginaryPart(ZZ)" -- see imaginaryPart, -- imaginary
    part
  * "insert(ZZ,Thing,BasicList)" -- see insert, -- copy a list,
    inserting an element
  * integralClosure(Ideal,RingElement,ZZ) (IntegralClosure)
    -- integral
    closure of an ideal in an affine domain
  * "integralClosure(Ideal,ZZ)" -- see
    integralClosure(Ideal,RingElement,ZZ) (IntegralClosure),
    -- integral
    closure of an ideal in an affine domain
  * "interval(QQ,ZZ)" -- see interval, -- construct an interval
  * "interval(RR,ZZ)" -- see interval, -- construct an interval
  * "interval(ZZ)" -- see interval, -- construct an interval
  * "interval(ZZ,QQ)" -- see interval, -- construct an interval
  * "interval(ZZ,RR)" -- see interval, -- construct an interval
  * "interval(ZZ,ZZ)" -- see interval, -- construct an interval
  * "inverseSystem(ZZ,Ideal)" -- see inverseSystem (InverseSystems),
    -- Inverse systems with equivariance
  * "inverseSystem(ZZ,Matrix)" -- see inverseSystem (InverseSystems),
    -- Inverse systems with equivariance
  * isLiftable(SheafMap,ZZ) (missing documentation)
  * "isMember(ZZ,RRi)" -- see isMember(QQ,RRi),
    -- membership test in an interval
  * "isPrime(ZZ)" -- see isPrime, -- whether a integer or
    polynomial is prime
  * isPseudoprime(ZZ) -- whether an integer is
    probably prime
  * "isReal(ZZ)" -- see isReal, -- whether a number is real
  * "isUnit(ZZ)" -- see isUnit, -- whether a ring element is a
    unit
  * kill(ZZ) -- kill a process
  * koszul(ZZ,Matrix) -- a differential in a
    Koszul complex
  * "lcm(QQ,ZZ)" -- see lcm, -- least common multiple
  * "lcm(RingElement,ZZ)" -- see lcm, -- least common multiple
  * "lcm(ZZ,QQ)" -- see lcm, -- least common multiple
  * "lcm(ZZ,RingElement)" -- see lcm, -- least common multiple
  * "lcm(ZZ,ZZ)" -- see lcm, -- least common multiple
  * leadTerm(ZZ,Ideal) -- get the ideal of
    lead polynomials
  * leadTerm(ZZ,Matrix) -- get the matrix of
    lead polynomials of each column
  * leadTerm(ZZ,RingElement) -- get the
    lead polynomials using part of the monomial order
  * "CC << ZZ" -- see left shift,
  * "RR << ZZ" -- see left shift,
  * "RRi << ZZ" -- see left shift,
  * "ZZ << ZZ" -- see left shift,
  * "lift(CC,type of ZZ)" -- see lift, -- lift to another ring
  * "lift(Ideal,type of ZZ)" -- see lift, -- lift to another ring
  * "lift(Matrix,type of CC_*,type of ZZ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of QQ,type of ZZ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of RR_*,type of ZZ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of RRi_*,type of ZZ)" -- see lift, -- lift to
    another ring
  * "lift(Matrix,type of ZZ,type of ZZ)" -- see lift, -- lift to
    another ring
  * "lift(QQ,type of ZZ)" -- see lift, -- lift to another ring
  * "lift(RR,type of ZZ)" -- see lift, -- lift to another ring
  * "lift(RRi,type of ZZ)" -- see lift, -- lift to another ring
  * "lift(ZZ,type of ZZ)" -- see lift, -- lift to another ring
  * List # ZZ (missing documentation)
  * List #? ZZ (missing documentation)
  * "locate(ZZ)" -- see locate, -- locate source code
  * map(CoherentSheaf,CoherentSheaf,Matrix,ZZ) (missing documentation)
  * "map(Module,Module,ZZ)" -- see map(Module,Module,RingElement),
    -- construct the map induced by
    multiplication by a ring element on the generators
  * "map(Module,ZZ,ZZ)" -- see map(Module,Module,RingElement),
    -- construct the map induced by
    multiplication by a ring element on the generators
  * map(Module,ZZ,Function) -- create a
    matrix from a free module by specifying a function that gives each entry
  * map(Module,ZZ,List) -- create a matrix
    by giving a sparse or dense list of entries
  * Matrix == ZZ (missing documentation)
  * Matrix ^ ZZ -- power
  * minors(ZZ,Matrix) -- ideal generated by
    minors
  * Module * ZZ (missing documentation)
  * Module == ZZ (missing documentation)
  * Module ^ ZZ -- direct sum
  * Module ^** ZZ -- tensor power
  * MonoidElement * ZZ (missing documentation)
  * MonoidElement == ZZ (missing documentation)
  * MonoidElement ^ ZZ (missing documentation)
  * MonomialIdeal == ZZ (missing documentation)
  * mutableIdentity(Ring,ZZ) -- make a
    mutable identity matrix
  * "mutableIdentity(RingFamily,ZZ)" -- see mutableIdentity(Ring,ZZ),
    -- make a mutable identity matrix
  * MutableMatrix * ZZ (missing documentation)
  * MutableMatrix == ZZ (missing documentation)
  * MutableMatrix ^ ZZ (missing documentation)
  * mutableMatrix(Ring,ZZ,ZZ) -- make
    a mutable matrix filled with zeroes
  * "mutableMatrix(RingFamily,ZZ,ZZ)" -- see mutableMatrix(Ring,ZZ,ZZ),
    -- make a mutable matrix filled with
    zeroes
  * Net # ZZ (missing documentation)
  * Net #? ZZ (missing documentation)
  * Net ^ ZZ -- raise a net or string
  * "String ^ ZZ" -- see Net ^ ZZ, -- raise a net or string
  * "String | ZZ" -- see Net | Net, -- join strings or nets
  * "ZZ | String" -- see Net | Net, -- join strings or nets
  * new AtomicInt from ZZ -- initialize an atomic
    integer
  * new ZZ from AtomicInt -- load an atomic
    integer
  * "numeric(ZZ,CC)" -- see numeric, -- convert to floating
    point
  * "numeric(ZZ,Constant)" -- see numeric, -- convert to
    floating point
  * "numeric(ZZ,IndeterminateNumber)" -- see numeric, -- convert
    to floating point
  * "numeric(ZZ,InfiniteNumber)" -- see numeric, -- convert to
    floating point
  * "numeric(ZZ,Matrix)" -- see numeric, -- convert to floating
    point
  * "numeric(ZZ,Number)" -- see numeric, -- convert to floating
    point
  * "numeric(ZZ,RRi)" -- see numeric, -- convert to floating
    point
  * "numeric(ZZ,Vector)" -- see numeric, -- convert to floating
    point
  * "numeric(ZZ,VisibleList)" -- see numeric, -- convert to
    floating point
  * "numericInterval(ZZ,Constant)" -- see numericInterval,
    -- converts to an interval
  * "options(ZZ)" -- see options(Command), -- get
    optional arguments and default values of functions and methods
  * "pack(BasicList,ZZ)" -- see pack, -- pack elements of a list or
    string into several shorter lists or strings
  * "pack(String,ZZ)" -- see pack, -- pack elements of a list or
    string into several shorter lists or strings
  * "pack(ZZ,BasicList)" -- see pack, -- pack elements of a list or
    string into several shorter lists or strings
  * "pack(ZZ,String)" -- see pack, -- pack elements of a list or
    string into several shorter lists or strings
  * "pad(Net,ZZ)" -- see pad, -- pad a string or net with spaces
  * "pad(String,ZZ)" -- see pad, -- pad a string or net with spaces
  * "pad(ZZ,Net)" -- see pad, -- pad a string or net with spaces
  * "pad(ZZ,String)" -- see pad, -- pad a string or net with spaces
  * "part(InfiniteNumber,ZZ,RingElement)" -- see part, -- select
    terms of a polynomial by degree(s) or weight(s)
  * "part(InfiniteNumber,ZZ,VisibleList,RingElement)" -- see part,
    -- select terms of a polynomial by degree(s) or weight(s)
  * "part(Nothing,ZZ,RingElement)" -- see part, -- select terms of
    a polynomial by degree(s) or weight(s)
  * "part(Nothing,ZZ,VisibleList,RingElement)" -- see part, --
    select terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,InfiniteNumber,RingElement)" -- see part, -- select
    terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,InfiniteNumber,VisibleList,RingElement)" -- see part,
    -- select terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,Nothing,RingElement)" -- see part, -- select terms of
    a polynomial by degree(s) or weight(s)
  * "part(ZZ,Nothing,VisibleList,RingElement)" -- see part, --
    select terms of a polynomial by degree(s) or weight(s)
  * "part(ZZ,RingElement)" -- see part, -- select terms of a
    polynomial by degree(s) or weight(s)
  * "part(ZZ,VisibleList,RingElement)" -- see part, -- select terms
    of a polynomial by degree(s) or weight(s)
  * "part(ZZ,ZZ,RingElement)" -- see part, -- select terms of a
    polynomial by degree(s) or weight(s)
  * "part(ZZ,ZZ,VisibleList,RingElement)" -- see part, -- select
    terms of a polynomial by degree(s) or weight(s)
  * part(InfiniteNumber,ZZ,Number) (missing documentation)
  * part(ZZ,InfiniteNumber,Number) (missing documentation)
  * part(ZZ,Number) (missing documentation)
  * part(ZZ,ZZ,Number) (missing documentation)
  * Partition _ ZZ -- get element
  * "partitions(ZZ)" -- see partitions, -- list the
    partitions of an integer
  * "partitions(ZZ,ZZ)" -- see partitions, -- list the
    partitions of an integer
  * "peek'(ZZ,Thing)" -- see peek', -- examine contents of an
    object
  * "permanents(ZZ,Matrix)" -- see permanents, -- ideal
    generated by square permanents of a matrix
  * "permutations(ZZ)" -- see permutations, -- produce all
    permutations of a list
  * "pfaffians(ZZ,Matrix)" -- see pfaffians, -- ideal
    generated by Pfaffians
  * "polyhedra(ZZ,PolyhedralComplex)" -- see polyhedra (Polyhedra),
    -- computes all polyhedra of a polyhedral complex of
    a certain dimension
  * "position(ZZ,Function)" -- see position, -- the first
    element of a list satisfying a condition
  * "posOrthant(ZZ)" -- see posOrthant (Polyhedra), --
    generates the positive orthant in n-space
  * "RingMap ^ ZZ" -- see powers,
  * product(ZZ,Function) -- product of
    consecutive values of a function
  * "projectiveHilbertPolynomial(ZZ)" -- see projectiveHilbertPolynomial,
    -- Hilbert polynomial of projective space
  * "projectiveHilbertPolynomial(ZZ,ZZ)" -- see
    projectiveHilbertPolynomial, -- Hilbert
    polynomial of projective space
  * ProjectiveHilbertPolynomial == ZZ (missing documentation)
  * ProjectiveHilbertPolynomial ZZ, --
    value of polynomial
  * Pseudocode _ ZZ (missing documentation)
  * "ZZ * Polyhedron" -- see QQ * Polyhedron (Polyhedra),
    -- rescales a polyhedron by a given positive factor
  * QQ == ZZ (missing documentation)
  * "quotientRemainder(ZZ,ZZ)" -- see
    quotientRemainder(RingElement,RingElement),
    -- quotient and remainder
  * random(ZZ,Ideal) -- get a random homogeneous
    element from a graded ideal
  * random(ZZ,Ring) -- get a random homogeneous
    element from a graded ring
  * randomMutableMatrix(ZZ,ZZ,RR,ZZ)
    -- a random mutable matrix of
    integers
  * read(File,ZZ) -- read from a file
  * "realPart(ZZ)" -- see realPart, -- real part
  * "regex(String,ZZ,String)" -- see regex, -- evaluate a regular
    expression search
  * "regex(String,ZZ,ZZ,String)" -- see regex, -- evaluate a
    regular expression search
  * "regSeqInIdeal(Ideal,ZZ)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * "regSeqInIdeal(Ideal,ZZ,ZZ,ZZ)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * "remove(MutableList,ZZ)" -- see remove, -- remove an entry
    from a mutable hash table, list, or database
  * replace(ZZ,Thing,BasicList), --
    copy a list, replacing an element
  * "CC >> ZZ" -- see right shift,
  * "RR >> ZZ" -- see right shift,
  * "RRi >> ZZ" -- see right shift,
  * "ZZ >> ZZ" -- see right shift,
  * "Ring / ZZ" -- see Ring / Ideal, -- make a quotient
    ring
  * Ring == ZZ (missing documentation)
  * Ring ^ ZZ -- make a free module
  * "RingFamily ^ ZZ" -- see Ring ^ ZZ, -- make a free module
  * Ring _ ZZ -- get a ring variable by index
  * RingElement == ZZ (missing documentation)
  * RingElement ^ ZZ -- power
  * RingMap == ZZ (missing documentation)
  * rotate(ZZ,VisibleList) -- rotate a
    list
  * "round(ZZ)" -- see round, -- round a number
  * "round(ZZ,RR)" -- see round, -- round a number
  * "rowAdd(MutableMatrix,ZZ,Number,ZZ)" -- see rowAdd, -- add a
    multiple of one row to another
  * "rowAdd(MutableMatrix,ZZ,RingElement,ZZ)" -- see rowAdd, --
    add a multiple of one row to another
  * "rowMult(MutableMatrix,ZZ,Number)" -- see rowMult, --
    multiply a row by a ring element
  * "rowMult(MutableMatrix,ZZ,RingElement)" -- see rowMult, --
    multiply a row by a ring element
  * "rowPermute(MutableMatrix,ZZ,List)" -- see rowPermute, --
    permute some rows
  * "rowSwap(MutableMatrix,ZZ,ZZ)" -- see rowSwap, --
    interchange rows
  * RR == ZZ (missing documentation)
  * RRi == ZZ (missing documentation)
  * "scan(ZZ,Function)" -- see scan, -- apply a function to each
    element in a list or sequence
  * Schubert(ZZ,ZZ,VisibleList), --
    find the Plücker ideal of a Schubert variety
  * select(ZZ,BasicList,Function),
    -- select a limited number of elements from a list
  * select(ZZ,Function) -- select integers
  * select(ZZ,HashTable,Function),
    -- select a limited number of pairs from a hash table
  * "selectValues(ZZ,HashTable,Function)" -- see
    select(ZZ,HashTable,Function), --
    select a limited number of pairs from a hash table
  * select(ZZ,Set,Function) -- select a
    part of a set
  * "selectInSubring(ZZ,Matrix)" -- see selectInSubring,
    -- select columns in a subring
  * "selectKeys(ZZ,HashTable,Function)" -- see selectKeys, --
    select a part of a hash table by keys
  * "selectPairs(ZZ,HashTable,Function)" -- see selectPairs,
    -- select a part of a hash table by pairs
  * "separate(String,ZZ,String)" -- see separate, -- split a
    string into substrings using a regular expression
  * Sequence # ZZ (missing documentation)
  * Sequence #? ZZ (missing documentation)
  * "setRandomSeed(ZZ)" -- see setRandomSeed, -- set
    starting point for random number generator
  * "sheafExt^ZZ(CoherentSheaf,CoherentSheaf)" -- see sheafExt (Varieties),
    -- sheaf Ext of coherent sheaves
  * "sheafExt^ZZ(CoherentSheaf,SheafOfRings)" -- see sheafExt (Varieties),
    -- sheaf Ext of coherent sheaves
  * "sheafExt^ZZ(SheafOfRings,CoherentSheaf)" -- see sheafExt (Varieties),
    -- sheaf Ext of coherent sheaves
  * "sheafExt^ZZ(SheafOfRings,SheafOfRings)" -- see sheafExt (Varieties),
    -- sheaf Ext of coherent sheaves
  * SheafMap == ZZ (missing documentation)
  * SheafMap ^ ZZ (missing documentation)
  * SheafMap ZZ (missing documentation)
  * sheafMap(Matrix,ZZ) (missing documentation)
  * "simpleDocFrob(ZZ,Matrix)" -- see simpleDocFrob (SimpleDoc),
    -- a sample documentation node
  * "simplex(ZZ)" -- see simplex (Polyhedra), -- Produces a
    full-dimensional simplex
  * "simplex(ZZ,QQ)" -- see simplex (Polyhedra), -- Produces a
    full-dimensional simplex
  * "simplex(ZZ,ZZ)" -- see simplex (Polyhedra), -- Produces a
    full-dimensional simplex
  * "skeleton(ZZ,Fan)" -- see skeleton (Polyhedra), -- computes
    the k-skeleton of a Fan or PolyhedralComplex
  * "skeleton(ZZ,PolyhedralComplex)" -- see skeleton (Polyhedra),
    -- computes the k-skeleton of a Fan or
    PolyhedralComplex
  * "someTerms(RingElement,ZZ,ZZ)" -- see someTerms, -- select
    some terms of a polynomial
  * "stdSimplex(ZZ)" -- see stdSimplex (Polyhedra), --
    generates the d-dimensional standard simplex
  * "store(AtomicInt,ZZ)" -- see store, -- store the value of an
    atomic integer
  * String _ ZZ -- get element from string
  * "submatrixByDegrees(Matrix,ZZ,ZZ)" -- see submatrixByDegrees,
    -- submatrix consisting of rows and columns in an
    interval or box of degrees
  * "subsets(List,ZZ)" -- see subsets, -- produce the subsets of
    a set or list
  * "subsets(Sequence,ZZ)" -- see subsets, -- produce the
    subsets of a set or list
  * "subsets(Set,ZZ)" -- see subsets, -- produce the subsets of
    a set or list
  * "subsets(ZZ)" -- see subsets, -- produce the subsets of a
    set or list
  * "subsets(ZZ,ZZ)" -- see subsets, -- produce the subsets of a
    set or list
  * "substitute(Matrix,ZZ)" -- see substitute, --
    substituting values for variables
  * "substring(String,ZZ)" -- see substring, -- extract part
    of a string
  * "substring(String,ZZ,ZZ)" -- see substring, -- extract
    part of a string
  * "substring(ZZ,String)" -- see substring, -- extract part
    of a string
  * "substring(ZZ,ZZ,String)" -- see substring, -- extract
    part of a string
  * sum(ZZ,Function) -- sum consecutive values
    of a function
  * "switch(ZZ,ZZ,BasicList)" -- see switch, -- copy a list,
    switching two elements
  * "symmetricPower(ZZ,Matrix)" -- see symmetricPower, --
    symmetric power
  * "symmetricPower(ZZ,Module)" -- see symmetricPower, --
    symmetric power
  * symmetricPower(ZZ,CoherentSheaf) (missing documentation)
  * "take(BasicList,ZZ)" -- see take, -- Take some elements from a
    list or sequence.
  * "take(Thing,ZZ)" -- see take, -- Take some elements from a list
    or sequence.
  * "Monoid ^** ZZ" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "Ring ^** ZZ" -- see tensor(Monoid,Monoid),
    -- tensor product of monoids
  * "tests(ZZ,Package)" -- see tests, -- locate a package's tests
  * "tests(ZZ,String)" -- see tests, -- locate a package's tests
  * "toCC(ZZ)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,CC)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,QQ)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,QQ,QQ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,QQ,RR)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,QQ,ZZ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,RR)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,RR,QQ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,RR,RR)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,RR,ZZ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,ZZ)" -- see toCC, -- convert to high-precision complex
    number
  * "toCC(ZZ,ZZ,QQ)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,ZZ,RR)" -- see toCC, -- convert to high-precision
    complex number
  * "toCC(ZZ,ZZ,ZZ)" -- see toCC, -- convert to high-precision
    complex number
  * "toDual(ZZ,Ideal)" -- see toDual (InverseSystems), -- finds
    the inverse system to an ideal up to a given degree
  * "toDual(ZZ,Matrix)" -- see toDual (InverseSystems), -- finds
    the inverse system to an ideal up to a given degree
  * topComponents(Module,ZZ) (missing documentation)
  * Tor_ZZ(Ideal,Matrix) (missing documentation)
  * Tor_ZZ(Matrix,Ideal) (missing documentation)
  * Tor_ZZ(Matrix,Module) (missing documentation)
  * Tor_ZZ(Matrix,Ring) (missing documentation)
  * Tor_ZZ(Module,Matrix) (missing documentation)
  * "Tor_ZZ(Ideal,Ideal)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * "Tor_ZZ(Ideal,Module)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * "Tor_ZZ(Ideal,Ring)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * "Tor_ZZ(Module,Ideal)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * Tor_ZZ(Module,Module) -- compute a
    Tor module
  * "Tor_ZZ(Module,Ring)" -- see Tor_ZZ(Module,Module),
    -- compute a Tor module
  * Tor_ZZ(Ring,Ideal) (missing documentation)
  * Tor_ZZ(Ring,Matrix) (missing documentation)
  * Tor_ZZ(Ring,Module) (missing documentation)
  * Tor_ZZ(Ring,Ring) (missing documentation)
  * truncate(BettiTally,InfiniteNumber,ZZ) (missing documentation)
  * truncate(BettiTally,ZZ,InfiniteNumber) (missing documentation)
  * truncate(BettiTally,ZZ,ZZ) (missing documentation)
  * truncate(Cone,List,ZZ) (missing documentation)
  * "truncate(ZZ,Matrix)" -- see truncate(List,Matrix) (Truncations),
    -- truncation of a map of free
    modules
  * "truncate(ZZ,Ideal)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * "truncate(ZZ,Module)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * "truncate(ZZ,Ring)" -- see truncate(List,Module) (Truncations),
    -- truncation of the graded ring,
    ideal or module at a specified degree or set of degrees
  * "truncateOutput(ZZ)" -- see truncateOutput,
  * "uniquePermutations(ZZ)" -- see uniquePermutations,
    -- produce all unique permutations of a list
  * "vars(ZZ)" -- see vars(List), -- a sequence of
    variables
  * VirtualTally == ZZ (missing documentation)
  * VirtualTally ? ZZ (missing documentation)
  * VirtualTally ^** ZZ -- Cartesian power of
    sets and tallies
  * VisibleList _ ZZ -- get element from list
  * wedgeProduct(ZZ,ZZ,Module), --
    the exterior multiplication map
  * ZZ * MonoidElement (missing documentation)
  * ZZ * MutableMatrix (missing documentation)
  * ZZ .. ZZ -- sequences of consecutive integers
  * ZZ ..< ZZ -- sequences of consecutive integers
  * ZZ _colon_ Thing -- repeat an item
  * ZZ == CC (missing documentation)
  * ZZ == ChainComplex (missing documentation)
  * ZZ == ChainComplexMap (missing documentation)
  * ZZ == CoherentSheaf (missing documentation)
  * ZZ == GradedModuleMap (missing documentation)
  * ZZ == Ideal (missing documentation)
  * ZZ == Module (missing documentation)
  * ZZ == MonoidElement (missing documentation)
  * ZZ == MonomialIdeal (missing documentation)
  * ZZ == MutableMatrix (missing documentation)
  * ZZ == ProjectiveHilbertPolynomial (missing documentation)
  * ZZ == QQ (missing documentation)
  * ZZ == Ring (missing documentation)
  * ZZ == RingElement (missing documentation)
  * ZZ == RingMap (missing documentation)
  * ZZ == RR (missing documentation)
  * ZZ == RRi (missing documentation)
  * ZZ == SheafMap (missing documentation)
  * ZZ == VirtualTally (missing documentation)
  * ZZ == ZZ (missing documentation)
  * ZZ ? VirtualTally (missing documentation)
  * ZZ _ Module -- integers or zero element
  * ZZ | ZZ -- logical or
  * ZZ ~ -- logical not

For the programmer
==================

The object ZZ, is a ring, with ancestor classes
Number, < Thing.

ZZ & ZZ -- logical and
**********************

Synopsis
========

  * Operator: &,
  * Usage:
        m & n
  * Inputs:
      * m
      * n
  * Outputs:
      * an integer, obtained from the bits of the integers m and n
        by logical 'and'.

Description
===========

+---------------------------------------------------------------+
|i1 : (2^15 + 2^13 + 2^42) & (2^15 + 2^23 + 2^42) == 2^15 + 2^42|
|                                                               |
|o1 = true                                                      |
+---------------------------------------------------------------+

See also
========

  * ZZ | ZZ -- logical or
  * ZZ ^^ ZZ -- logical exclusive-or
  * ZZ ~ -- logical not

Ways to use this method:
========================

  * ZZ & ZZ -- logical and

ZZ .. ZZ -- sequences of consecutive integers
*********************************************

Synopsis
========

  * Operator: ..,
  * Usage:
        s .. t
  * Inputs:
      * s
      * t
  * Outputs:
      * the sequence of consecutive integers from s to t, inclusive

Description
===========

+------------------------------------+
|i1 : 1 .. 10                        |
|                                    |
|o1 = (1, 2, 3, 4, 5, 6, 7, 8, 9, 10)|
|                                    |
|o1 : Sequence                       |
+------------------------------------+

Ways to use this method:
========================

  * ZZ .. ZZ -- sequences of consecutive integers

ZZ ..< ZZ -- sequences of consecutive integers
**********************************************

Synopsis
========

  * Operator: ..<,
  * Usage:
        s ..< t
  * Inputs:
      * s
      * t
  * Outputs:
      * the sequence of consecutive integers from s to t, not including the
        endpoint

Description
===========

+-----------------------------------+
|i1 : 0 ..< 10                      |
|                                   |
|o1 = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9)|
|                                   |
|o1 : Sequence                      |
+-----------------------------------+

The indices valid for a list of length n can be obtained with 0 ..< n.

+------------------------------+
|i2 : x = {a,c,e,f}            |
|                              |
|o2 = {a, c, e, f}             |
|                              |
|o2 : List                     |
+------------------------------+
|i3 : 0 ..< #x                 |
|                              |
|o3 = (0, 1, 2, 3)             |
|                              |
|o3 : Sequence                 |
+------------------------------+
|i4 : apply(0 ..< #x, i -> x#i)|
|                              |
|o4 = (a, c, e, f)             |
|                              |
|o4 : Sequence                 |
+------------------------------+

Ways to use this method:
========================

  * ZZ ..< ZZ -- sequences of consecutive integers

ZZ : Thing -- repeat an item
****************************

Synopsis
========

  * Operator: _colon_,

Description
===========

n : x repetition n times of x in a sequence

If n is an integer and x is anything, return a sequence consisting of x
repeated n times.  A negative value for n will silently be treated as zero.

Warning: such sequences do not get automatically spliced into lists containing
them.

+------------------------------------------------------+
|i1 : {5:a,10:b}                                       |
|                                                      |
|o1 = {(a, a, a, a, a), (b, b, b, b, b, b, b, b, b, b)}|
|                                                      |
|o1 : List                                             |
+------------------------------------------------------+
|i2 : splice {5:a,10:b}                                |
|                                                      |
|o2 = {a, a, a, a, a, b, b, b, b, b, b, b, b, b, b}    |
|                                                      |
|o2 : List                                             |
+------------------------------------------------------+

See also
========

  * splice -- remove subsequences from a sequence or list
  * ZZ .. ZZ -- sequences of consecutive integers
  * lists and sequences -- a detailed overview of
    lists and sequences in Macaulay2

Ways to use this method:
========================

  * ZZ _colon_ Thing -- repeat an item

ZZ _ Module -- integers or zero element
***************************************

Synopsis
========

  * Operator: _,
  * Usage:
        0_M
  * Inputs:
      * an integer,
      * a module,
  * Outputs:
      * a vector,

Description
===========

0_M provides the zero element of the module M.

The return value is either a ring element, or a
vector.

+-------------+
|i1 : 0_(ZZ^3)|
|             |
|o1 = 0       |
|             |
|       3     |
|o1 : ZZ      |
+-------------+

Ways to use this method:
========================

  * ZZ _ Module -- integers or zero element

ZZ | ZZ -- logical or
*********************

Synopsis
========

  * Operator: |,
  * Usage:
        m | n
  * Inputs:
      * m
      * n
  * Outputs:
      * an integer, obtained from the bits of the integers m and n
        by logical 'or'.

Description
===========

+-------------------------------+
|i1 : 2^42 | 2^15 == 2^42 + 2^15|
|                               |
|o1 = true                      |
+-------------------------------+

See also
========

  * ZZ & ZZ -- logical and
  * ZZ ^^ ZZ -- logical exclusive-or
  * ZZ ~ -- logical not

Ways to use this method:
========================

  * ZZ | ZZ -- logical or

ZZ ~ -- logical not
*******************

Synopsis
========

  * Operator: ~,
  * Usage:
        n~
  * Inputs:
      * n, an integer,
  * Outputs:
      * an integer, the bitwise complement of n;

Description
===========

+-------+
|i1 : 7~|
|       |
|o1 = -8|
+-------+

Note that ~ has higher precedence, than -, so
enclose negative integers in parentheses.

+-----------+
|i2 : (-12)~|
|           |
|o2 = 11    |
+-----------+

See also
========

  * ZZ & ZZ -- logical and
  * ZZ | ZZ -- logical or
  * ZZ ^^ ZZ -- logical exclusive-or

Ways to use this method:
========================

  * ZZ ~ -- logical not