This is Divisor.info, produced by Macaulay2, version 1.22

Divisor -- divisors
*******************

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

Divisor is a package for working with (Q/R)-Weil divisors on normal affine and
projective varieties (equivalently, on commutative, normal and graded rings).

This package introduces a type WeilDivisor, which lets the
user work with Weil divisors similar to the way one might in algebraic
geometry.  We highlight a few important functions below.

Useful functions:
  * isCartier, or isQCartier, can let you
    determine if a divisor is Cartier or if a power is Cartier.
  * isVeryAmple, lets you check if a divisor is very ample.
  * baseLocus, lets you compute the base locus of the complete
    linear system corresponding to a divisor on a projective variety.
  * mapToProjectiveSpace, returns the map to
    projective space determined by the complete linear system determined by the
    divisor.
  * canonicalDivisor, lets you compute the canonical
    divisor on some affine or projective variety.
  * ramificationDivisor, lets you compute the
    relative canonical divisor of a finite map varieties.

This package also includes some functions for interacting with ideals and
modules which might be independently useful.
  * embedAsIdeal, embeds a rank one module as an ideal.
  * reflexify, computes the reflexification, Hom(Hom(M, R), R)
    of a module M or ideal.
  * reflexivePower, computes the reflexification of a
    power of an ideal quickly.
  * torsionSubmodule, find the torsion submodule of a
    module.

We emphasize once more that the functions in this package might produce
unexpected results on non-normal rings.

Acknowledgements:

The authors would like to thank Tommaso de Fernex, David Eisenbud, Daniel
Grayson, Anurag Singh, Greg Smith, Mike Stillman and the referee for useful
conversations and comments on the development of this package.

Authors
=======

  * Karl Schwede (see http://www.math.utah.edu/~schwede ) <kschwede@gmail.com>
  * Zhaoning Yang <zyy5054@gmail.com>

Certification a gold star
=========================

Version 0.3 of this package was accepted for publication in volume 8 (see
https://msp.org/jsag/2018/8-1/ ) of The Journal of Software for Algebra and
Geometry (see http://j-sag.org/ ) on 31 August 2018, in the article Divisor
Package for Macaulay2 (see https://msp.org/jsag/2018/8-1/p09.xhtml ). That
version can be obtained from the journal (see
https://msp.org/jsag/2018/8-1/jsag-v8-n1-x09-Divisor.m2 ) or from the Macaulay2
source code repository (see
http://github.com/Macaulay2/M2/blob/0e40b423ff375d6eb0a98d6fbbe7be8b2db95a98/M2
/Macaulay2/packages/Divisor.m2 ).

Version
=======

This documentation describes version 0.3 of Divisor.

Source code
===========

The source code from which this documentation is derived is in the file
Divisor.m2 (see common/share/Macaulay2/Divisor.m2 ).

Exports
=======

  * Types
      * BasicDivisor -- the Types of divisors
      * "QWeilDivisor" -- see BasicDivisor, -- the Types of
        divisors
      * "RWeilDivisor" -- see BasicDivisor, -- the Types of
        divisors
      * "WeilDivisor" -- see BasicDivisor, -- the Types of
        divisors
  * Functions and commands
      * applyToCoefficients -- apply a function to
        the coefficients of a divisor
      * baseLocus -- compute the locus where a graded module
        (or O(D) of a Weil divisor) is not globally generated
      * canonicalDivisor -- compute a canonical
        divisor of a ring
      * cleanSupport -- removes primes with coefficient
        zero from a divisor
      * clearCache -- creates a new divisor with most
        entries from the cache removed
      * divisor -- constructor for (Weil/Q/R)-divisors
      * dualize -- finds an ideal or module isomorphic to
        Hom(M, R)
      * embedAsIdeal -- embed a module as an ideal of a
        ring
      * findElementOfDegree -- find an element of a
        specified degree
      * gbs -- get the list of Groebner bases corresponding to the
        height-one primes in the support of a divisor
      * getLinearDiophantineSolution, --
        find a solution of the linear Diophantine equation Ax = b
      * getPrimeCount -- get the number of height-one
        primes in the support of the divisor
      * getPrimeDivisors -- get the list of prime
        divisors of a given divisor
      * idealPower -- compute the ideal generated by the
        generators of the ideal raised to a power
      * isCartier -- whether a Weil divisor is Cartier
      * isDomain -- whether a ring is a domain
      * isEffective -- whether a divisor is effective
      * isLinearEquivalent -- whether two Weil
        divisors are linearly equivalent
      * isPrincipal -- whether a Weil divisor is globally
        principal
      * isQCartier -- whether m times a divisor is Cartier
        for any m from 1 to a fixed positive integer n1.
      * isQLinearEquivalent -- whether two
        Q-divisors are linearly equivalent
      * isReduced -- whether a divisor is reduced
      * isReflexive -- whether an ideal or module is
        reflexive
      * isSmooth -- whether R mod the ideal is smooth
      * isSNC -- whether the divisor is simple normal crossings
      * isVeryAmple -- whether a divisor is very ample.
      * isWeilDivisor -- whether a rational/real divisor
        is in actuality a Weil divisor
      * isZeroDivisor -- whether the divisor is the zero
        divisor
      * mapToProjectiveSpace -- compute the map to
        projective space associated with the global sections of a Cartier
        divisor
      * nonCartierLocus -- the non-Cartier locus of a
        Weil divisor
      * "negativePart" -- see positivePart, -- get the
        effective part or anti-effective part of a divisor
      * positivePart -- get the effective part or
        anti-effective part of a divisor
      * primes -- get the list of height-one primes in the
        support of a divisor
      * pullback -- pullback a divisor under a ring map
      * ramificationDivisor -- compute the
        ramification divisor of a finite inclusion of normal domains or a
        blowup over a smooth base
      * reflexify -- calculate the double dual of an ideal or
        module Hom(Hom(M, R), R)
      * reflexivePower -- computes a reflexive power of
        an ideal in a normal domain
      * toQWeilDivisor -- create a Q-Weil divisor from a
        Weil divisor
      * torsionSubmodule -- create the torsion
        submodule of a module
      * toRWeilDivisor -- create a R-divisor from a Q or
        Weil divisor
      * toWeilDivisor -- create a Weil divisor from a Q
        or R-divisor
      * zeroDivisor -- constructs the zero Weil divisor for
        the ring
  * Methods
      * "applyToCoefficients(BasicDivisor,Function)" -- see
        applyToCoefficients, -- apply a function to the
        coefficients of a divisor
      * "baseLocus(Module)" -- see baseLocus, -- compute the
        locus where a graded module (or O(D) of a Weil divisor) is not globally
        generated
      * "baseLocus(WeilDivisor)" -- see baseLocus, -- compute
        the locus where a graded module (or O(D) of a Weil divisor) is not
        globally generated
      * "- BasicDivisor" -- see BasicDivisor + BasicDivisor,
        -- add or subtract two divisors, or negate a divisor
      * BasicDivisor + BasicDivisor -- add
        or subtract two divisors, or negate a divisor
      * "BasicDivisor - BasicDivisor" -- see BasicDivisor + BasicDivisor,
        -- add or subtract two divisors, or negate
        a divisor
      * "canonicalDivisor(Ring)" -- see canonicalDivisor,
        -- compute a canonical divisor of a ring
      * ceiling(RWeilDivisor) -- produce a
        WeilDivisor whose coefficients are ceilings or floors of the divisor
      * "floor(RWeilDivisor)" -- see ceiling(RWeilDivisor),
        -- produce a WeilDivisor whose coefficients
        are ceilings or floors of the divisor
      * "cleanSupport(BasicDivisor)" -- see cleanSupport,
        -- removes primes with coefficient zero from a divisor
      * "clearCache(BasicDivisor)" -- see clearCache, --
        creates a new divisor with most entries from the cache removed
      * coefficient(BasicList,BasicDivisor)
        -- get the coefficient of an
        ideal for a fixed divisor
      * coefficient(Ideal,BasicDivisor)
        -- get the coefficient of an
        ideal for a fixed divisor
      * coefficients(BasicDivisor), --
        get the list of coefficients of a divisor
      * "divisor(BasicList)" -- see divisor, -- constructor for
        (Weil/Q/R)-divisors
      * "divisor(BasicList,BasicList)" -- see divisor, --
        constructor for (Weil/Q/R)-divisors
      * "divisor(Ideal)" -- see divisor, -- constructor for
        (Weil/Q/R)-divisors
      * "divisor(Matrix)" -- see divisor, -- constructor for
        (Weil/Q/R)-divisors
      * "divisor(Module)" -- see divisor, -- constructor for
        (Weil/Q/R)-divisors
      * "divisor(RingElement)" -- see divisor, -- constructor
        for (Weil/Q/R)-divisors
      * "dualize(Ideal)" -- see dualize, -- finds an ideal or
        module isomorphic to Hom(M, R)
      * "dualize(Module)" -- see dualize, -- finds an ideal or
        module isomorphic to Hom(M, R)
      * "embedAsIdeal(Matrix)" -- see embedAsIdeal, --
        embed a module as an ideal of a ring
      * "embedAsIdeal(Module)" -- see embedAsIdeal, --
        embed a module as an ideal of a ring
      * "embedAsIdeal(Ring,Matrix)" -- see embedAsIdeal, --
        embed a module as an ideal of a ring
      * "embedAsIdeal(Ring,Module)" -- see embedAsIdeal, --
        embed a module as an ideal of a ring
      * "findElementOfDegree(BasicList,Ring)" -- see findElementOfDegree,
        -- find an element of a specified degree
      * "findElementOfDegree(ZZ,Ring)" -- see findElementOfDegree,
        -- find an element of a specified degree
      * "gbs(BasicDivisor)" -- see gbs, -- get the list of Groebner
        bases corresponding to the height-one primes in the support of a
        divisor
      * "getLinearDiophantineSolution(BasicList,BasicList)" -- see
        getLinearDiophantineSolution, -- find a
        solution of the linear Diophantine equation Ax = b
      * "getLinearDiophantineSolution(BasicList,Matrix)" -- see
        getLinearDiophantineSolution, -- find a
        solution of the linear Diophantine equation Ax = b
      * "getPrimeCount(BasicDivisor)" -- see getPrimeCount,
        -- get the number of height-one primes in the support of
        the divisor
      * "getPrimeDivisors(BasicDivisor)" -- see getPrimeDivisors,
        -- get the list of prime divisors of a given divisor
      * "ideal(QWeilDivisor)" -- see ideal(RWeilDivisor),
        -- calculate the corresponding module of a
        divisor and represent it as an ideal
      * ideal(RWeilDivisor) -- calculate the
        corresponding module of a divisor and represent it as an ideal
      * "ideal(WeilDivisor)" -- see ideal(RWeilDivisor),
        -- calculate the corresponding module of a
        divisor and represent it as an ideal
      * "idealPower(ZZ,Ideal)" -- see idealPower, -- compute
        the ideal generated by the generators of the ideal raised to a power
      * "isCartier(WeilDivisor)" -- see isCartier, -- whether
        a Weil divisor is Cartier
      * "isDomain(Ring)" -- see isDomain, -- whether a ring is
        a domain
      * "isEffective(BasicDivisor)" -- see isEffective, --
        whether a divisor is effective
      * isHomogeneous(BasicDivisor), --
        whether the divisor is graded (homogeneous)
      * "isLinearEquivalent(WeilDivisor,WeilDivisor)" -- see
        isLinearEquivalent, -- whether two Weil divisors
        are linearly equivalent
      * isPrime(BasicDivisor) -- whether a
        divisor is prime
      * "isPrincipal(WeilDivisor)" -- see isPrincipal, --
        whether a Weil divisor is globally principal
      * "isQCartier(ZZ,QWeilDivisor)" -- see isQCartier, --
        whether m times a divisor is Cartier for any m from 1 to a fixed
        positive integer n1.
      * "isQCartier(ZZ,WeilDivisor)" -- see isQCartier, --
        whether m times a divisor is Cartier for any m from 1 to a fixed
        positive integer n1.
      * "isQLinearEquivalent(ZZ,QWeilDivisor,QWeilDivisor)" -- see
        isQLinearEquivalent, -- whether two Q-divisors are
        linearly equivalent
      * "isReduced(BasicDivisor)" -- see isReduced, -- whether
        a divisor is reduced
      * "isReflexive(Ideal)" -- see isReflexive, -- whether
        an ideal or module is reflexive
      * "isReflexive(Module)" -- see isReflexive, -- whether
        an ideal or module is reflexive
      * "isSmooth(Ideal)" -- see isSmooth, -- whether R mod the
        ideal is smooth
      * "isSNC(BasicDivisor)" -- see isSNC, -- whether the divisor
        is simple normal crossings
      * "isVeryAmple(WeilDivisor)" -- see isVeryAmple, --
        whether a divisor is very ample.
      * "isWeilDivisor(RWeilDivisor)" -- see isWeilDivisor,
        -- whether a rational/real divisor is in actuality a
        Weil divisor
      * isWellDefined(BasicDivisor), --
        whether a divisor is valid
      * "isZeroDivisor(BasicDivisor)" -- see isZeroDivisor,
        -- whether the divisor is the zero divisor
      * "mapToProjectiveSpace(WeilDivisor)" -- see mapToProjectiveSpace,
        -- compute the map to projective space associated
        with the global sections of a Cartier divisor
      * "nonCartierLocus(WeilDivisor)" -- see nonCartierLocus,
        -- the non-Cartier locus of a Weil divisor
      * Number * BasicDivisor -- multiply a
        divisor by a number
      * "QQ * RWeilDivisor" -- see Number * BasicDivisor,
        -- multiply a divisor by a number
      * "QQ * WeilDivisor" -- see Number * BasicDivisor,
        -- multiply a divisor by a number
      * "RR * QWeilDivisor" -- see Number * BasicDivisor,
        -- multiply a divisor by a number
      * "RR * RWeilDivisor" -- see Number * BasicDivisor,
        -- multiply a divisor by a number
      * OO RWeilDivisor -- calculate module
        corresponding to divisor
      * "negativePart(RWeilDivisor)" -- see positivePart,
        -- get the effective part or anti-effective part of a divisor
      * "positivePart(RWeilDivisor)" -- see positivePart,
        -- get the effective part or anti-effective part of a divisor
      * "primes(BasicDivisor)" -- see primes, -- get the list of
        height-one primes in the support of a divisor
      * "pullback(RingMap,RWeilDivisor)" -- see pullback, --
        pullback a divisor under a ring map
      * "ramificationDivisor(RingMap)" -- see ramificationDivisor,
        -- compute the ramification divisor of a finite
        inclusion of normal domains or a blowup over a smooth base
      * "reflexify(Ideal)" -- see reflexify, -- calculate the
        double dual of an ideal or module Hom(Hom(M, R), R)
      * "reflexify(Module)" -- see reflexify, -- calculate the
        double dual of an ideal or module Hom(Hom(M, R), R)
      * "reflexivePower(ZZ,Ideal)" -- see reflexivePower,
        -- computes a reflexive power of an ideal in a normal domain
      * ring(BasicDivisor) -- get the ambient
        ring of a divisor
      * RWeilDivisor == RWeilDivisor, --
        whether two divisors are equal
      * "toQWeilDivisor(QWeilDivisor)" -- see toQWeilDivisor,
        -- create a Q-Weil divisor from a Weil divisor
      * "toQWeilDivisor(WeilDivisor)" -- see toQWeilDivisor,
        -- create a Q-Weil divisor from a Weil divisor
      * "torsionSubmodule(Module)" -- see torsionSubmodule,
        -- create the torsion submodule of a module
      * "toRWeilDivisor(QWeilDivisor)" -- see toRWeilDivisor,
        -- create a R-divisor from a Q or Weil divisor
      * "toRWeilDivisor(RWeilDivisor)" -- see toRWeilDivisor,
        -- create a R-divisor from a Q or Weil divisor
      * "toRWeilDivisor(WeilDivisor)" -- see toRWeilDivisor,
        -- create a R-divisor from a Q or Weil divisor
      * "toWeilDivisor(RWeilDivisor)" -- see toWeilDivisor,
        -- create a Weil divisor from a Q or R-divisor
      * trim(BasicDivisor) -- trims the ideals
        displayed to the user and removes primes with coefficient zero
      * "zeroDivisor(Ring)" -- see zeroDivisor, --
        constructs the zero Weil divisor for the ring
  * Symbols
      * AmbientRing -- an option used to tell divisor
        construction that a particular ambient ring is expected.
      * CoefficientType -- an option used to tell
        divisor construction that a particular type of coefficients are
        expected.
      * ideals -- a symbol used as a key within the divisor
        cache
      * IdealStrategy -- a valid value for the Strategy
        option in dualize or reflexify
      * "ModuleStrategy" -- see IdealStrategy, -- a valid
        value for the Strategy option in dualize or reflexify
      * "NoStrategy" -- see IdealStrategy, -- a valid
        value for the Strategy option in dualize or reflexify
      * IsGraded -- an option used by numerous functions which
        tells it to treat the divisors as if we were working on the Proj of the
        ambient ring.
      * KnownCartier -- an option used to specify to
        certain functions that we know that the divisor is Cartier
      * KnownDomain -- an option used to specify to certain
        functions that we know that the ring is a domain
      * MTries -- an option used by embedAsIdeal how many times
        to try embedding the module as an ideal in a random way.
      * Primes -- a value for the option Strategy for the
        pullback method
      * ReturnMap -- an option for embedAsIdeal
      * Safe -- an option used to tell functions whether not to do
        checks.
      * Section -- an option used in a number of functions
      * Sheaves -- a value for the option Strategy for the
        pullback method

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

The object Divisor, is a package (Macaulay2Doc).

AmbientRing -- an option used to tell divisor construction that a particular ambient ring is expected.
******************************************************************************************************

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

If set to a ring, then when calling divisor, the primes are all checked whether
they are ideals in that ring.

Functions with optional argument named AmbientRing :
====================================================

  * "divisor(...,AmbientRing=>...)" -- see divisor, --
    constructor for (Weil/Q/R)-divisors

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

The object AmbientRing, is a symbol (Macaulay2Doc).

applyToCoefficients -- apply a function to the coefficients of a divisor
************************************************************************

Synopsis
========

  * Usage:
        applyToCoefficients(D1, h)
  * Inputs:
      * D1, an instance of the type BasicDivisor,
      * h, a function (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CoefficientType => a number (Macaulay2Doc), default value
        null, specifies what the coefficients of the output divisor should be
      * Safe => a Boolean value (Macaulay2Doc), default value
        false, specifies that the system checks whether the output is a valid
        divisor
  * Outputs:
      * an instance of the type WeilDivisor,

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

applyToCoefficients applies the function h to the coefficients of the divisor
of D1.  Specifying the CoefficientType=>ZZ, CoefficientType=>QQ,
CoefficientType=>RR, will force the returned divisor to be of a certain form
(WeilDivisor, QWeilDivisor, RWeilDivisor respectively), otherwise the class of
the output D is the same as the class of the input D1 (WeilDivisor,
QWeilDivisor, RWeilDivisor, BasicDivisor).  If Safe is set to true (the default
is false), then the function will check to make sure the output is a valid
divisor.

+-------------------------------------+
|i1 : R = QQ[x, y, z];                |
+-------------------------------------+
|i2 : D = divisor(x*y^2/z)            |
|                                     |
|o2 = -Div(z) + 2*Div(y) + Div(x)     |
|                                     |
|o2 : WeilDivisor on R                |
+-------------------------------------+
|i3 : applyToCoefficients(D, u->5*u)  |
|                                     |
|o3 = 10*Div(y) + -5*Div(z) + 5*Div(x)|
|                                     |
|o3 : WeilDivisor on R                |
+-------------------------------------+

See also
========

  * floor(RWeilDivisor) -- produce a
    WeilDivisor whose coefficients are ceilings or floors of the divisor
  * ceiling(RWeilDivisor) -- produce a
    WeilDivisor whose coefficients are ceilings or floors of the divisor

Ways to use applyToCoefficients :
=================================

  * "applyToCoefficients(BasicDivisor,Function)"

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

The object applyToCoefficients, is a method function with options (Macaulay2Doc).

baseLocus -- compute the locus where a graded module (or O(D) of a Weil divisor) is not globally generated
**********************************************************************************************************

Synopsis
========

  * Usage:
        I = baseLocus(D)
        I = baseLocus(M)
  * Inputs:
      * D, an instance of the type WeilDivisor,
      * M, a module (Macaulay2Doc),
  * Outputs:
      * I, an ideal (Macaulay2Doc),

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

Given a graded module $M$ with degree 0 global sections $s1, ..., sd$, this
computes the locus where the $si$ do not generate $M$.  Given a Weil divisor
$D$, this computes the base locus of $O(D)$.  For example, consider the rulings
on $P^1 \times P^1$.

+------------------------------------+
|i1 : R = QQ[x,y,u,v]/ideal(x*y-u*v);|
+------------------------------------+
|i2 : D = divisor( ideal(x,u) )      |
|                                    |
|o2 = Div(x, u)                      |
|                                    |
|o2 : WeilDivisor on R               |
+------------------------------------+
|i3 : baseLocus(D)                   |
|                                    |
|o3 = ideal 1                        |
|                                    |
|o3 : Ideal of R                     |
+------------------------------------+

Next we consider an example of a point on an elliptic curve.

+----------------------------------------------+
|i4 : R = QQ[x,y,z]/ideal(y^2*z-x*(x+z)*(x-z));|
+----------------------------------------------+
|i5 : D = divisor(ideal(y, x))                 |
|                                              |
|o5 = Div(y, x)                                |
|                                              |
|o5 : WeilDivisor on R                         |
+----------------------------------------------+
|i6 : baseLocus(D)                             |
|                                              |
|o6 = ideal (y, x)                             |
|                                              |
|o6 : Ideal of R                               |
+----------------------------------------------+
|i7 : baseLocus(2*D)                           |
|                                              |
|o7 = ideal 1                                  |
|                                              |
|o7 : Ideal of R                               |
+----------------------------------------------+

Ways to use baseLocus :
=======================

  * "baseLocus(Module)"
  * "baseLocus(WeilDivisor)"

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

The object baseLocus, is a method function (Macaulay2Doc).

BasicDivisor -- the Types of divisors
*************************************

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

The BasicDivisor is the class of divisors whose coefficients are unspecified, a
base class.  Not typically for use.  All subtypes have the same essential
structure.

RWeilDivisor is a subclass which has real coefficients.

QWeilDivisor is a further subclass with rational coefficients.

WeilDivisor is a subclass with integer coefficients.

The basic structure is a HashTable.  There is one key which has a value which
specifies the ambient ring.  Another key is cache which points to a CacheTable.
The remaining keys are a Groebner basis $L$ for each prime ideal $P$ in the
support with corresponding value a list with one entry {$n$} where $n$ is the
coefficient of the height one prime.

+--------------------------------------------+
|i1 : R = QQ[x,y,z];                         |
+--------------------------------------------+
|i2 : D = divisor(x*y^2*z^3)                 |
|                                            |
|o2 = 2*Div(y) + 3*Div(z) + Div(x)           |
|                                            |
|o2 : WeilDivisor on R                       |
+--------------------------------------------+
|i3 : H = new HashTable from D               |
|                                            |
|o3 = HashTable{{x} => {1}                  }|
|               {y} => {2}                   |
|               {z} => {3}                   |
|               cache => CacheTable{...1...} |
|               ring => R                    |
|                                            |
|o3 : HashTable                              |
+--------------------------------------------+
|i4 : (2/3)*D                                |
|                                            |
|o4 = 2*Div(z) + 4/3*Div(y) + 2/3*Div(x)     |
|                                            |
|o4 : QWeilDivisor on R                      |
+--------------------------------------------+
|i5 : 0.6*D                                  |
|                                            |
|o5 = 1.8*Div(z) + 1.2*Div(y) + .6*Div(x)    |
|                                            |
|o5 : RWeilDivisor on R                      |
+--------------------------------------------+

Types of BasicDivisor :
=======================

  * "RWeilDivisor"

Functions and methods returning an object of class BasicDivisor :
=================================================================

  * "applyToCoefficients(BasicDivisor,Function)" -- see
    applyToCoefficients, -- apply a function to the
    coefficients of a divisor
  * "- BasicDivisor" -- see BasicDivisor + BasicDivisor,
    -- add or subtract two divisors, or negate a divisor
  * BasicDivisor + BasicDivisor -- add or
    subtract two divisors, or negate a divisor
  * "BasicDivisor - BasicDivisor" -- see BasicDivisor + BasicDivisor,
    -- add or subtract two divisors, or negate a
    divisor
  * "cleanSupport(BasicDivisor)" -- see cleanSupport, --
    removes primes with coefficient zero from a divisor
  * "clearCache(BasicDivisor)" -- see clearCache, -- creates
    a new divisor with most entries from the cache removed
  * "divisor(BasicList)" -- see divisor, -- constructor for
    (Weil/Q/R)-divisors
  * "divisor(BasicList,BasicList)" -- see divisor, --
    constructor for (Weil/Q/R)-divisors
  * Number * BasicDivisor -- multiply a divisor
    by a number
  * "pullback(RingMap,RWeilDivisor)" -- see pullback, --
    pullback a divisor under a ring map
  * trim(BasicDivisor) -- trims the ideals
    displayed to the user and removes primes with coefficient zero
  * "zeroDivisor(Ring)" -- see zeroDivisor, -- constructs
    the zero Weil divisor for the ring

Methods that use an object of class BasicDivisor :
==================================================

  * coefficient(BasicList,BasicDivisor)
    -- get the coefficient of an
    ideal for a fixed divisor
  * coefficient(Ideal,BasicDivisor)
    -- get the coefficient of an ideal
    for a fixed divisor
  * coefficients(BasicDivisor) -- get
    the list of coefficients of a divisor
  * "gbs(BasicDivisor)" -- see gbs, -- get the list of Groebner
    bases corresponding to the height-one primes in the support of a divisor
  * "getPrimeCount(BasicDivisor)" -- see getPrimeCount, --
    get the number of height-one primes in the support of the divisor
  * "getPrimeDivisors(BasicDivisor)" -- see getPrimeDivisors,
    -- get the list of prime divisors of a given divisor
  * "isEffective(BasicDivisor)" -- see isEffective, --
    whether a divisor is effective
  * isHomogeneous(BasicDivisor), --
    whether the divisor is graded (homogeneous)
  * isPrime(BasicDivisor) -- whether a
    divisor is prime
  * "isReduced(BasicDivisor)" -- see isReduced, -- whether a
    divisor is reduced
  * "isSNC(BasicDivisor)" -- see isSNC, -- whether the divisor is
    simple normal crossings
  * isWellDefined(BasicDivisor), --
    whether a divisor is valid
  * "isZeroDivisor(BasicDivisor)" -- see isZeroDivisor, --
    whether the divisor is the zero divisor
  * net(BasicDivisor) (missing documentation)
  * "primes(BasicDivisor)" -- see primes, -- get the list of
    height-one primes in the support of a divisor
  * ring(BasicDivisor) -- get the ambient ring
    of a divisor

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

The object BasicDivisor, is a type (Macaulay2Doc),
with ancestor classes HashTable (Macaulay2Doc),
< Thing (Macaulay2Doc).

BasicDivisor + BasicDivisor -- add or subtract two divisors, or negate a divisor
********************************************************************************

Synopsis
========

  * Operator: + (Macaulay2Doc),
  * Usage:
        A + B
        A - B
        -A
  * Inputs:
      * A, an instance of the type BasicDivisor,
      * B, an instance of the type BasicDivisor,
  * Outputs:
      * an instance of the type BasicDivisor,

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

We can add or subtract two divisors:

+--------------------------------------------------------------+
|i1 : R = QQ[x, y, z];                                         |
+--------------------------------------------------------------+
|i2 : D1 = divisor({1, 3, 2}, {ideal(x), ideal(y), ideal(z)})  |
|                                                              |
|o2 = 3*Div(y) + 2*Div(z) + Div(x)                             |
|                                                              |
|o2 : WeilDivisor on R                                         |
+--------------------------------------------------------------+
|i3 : D2 = divisor({-2, 3, -5}, {ideal(z), ideal(y), ideal(x)})|
|                                                              |
|o3 = -2*Div(z) + 3*Div(y) + -5*Div(x)                         |
|                                                              |
|o3 : WeilDivisor on R                                         |
+--------------------------------------------------------------+
|i4 : D1 + D2                                                  |
|                                                              |
|o4 = 6*Div(y) + -4*Div(x)                                     |
|                                                              |
|o4 : WeilDivisor on R                                         |
+--------------------------------------------------------------+
|i5 : D1 - D2                                                  |
|                                                              |
|o5 = 4*Div(z) + 6*Div(x)                                      |
|                                                              |
|o5 : WeilDivisor on R                                         |
+--------------------------------------------------------------+

We can also add or subtract divisors with different coefficients.

+-----------------------------------------------------------------------+
|i6 : R = QQ[x,y];                                                      |
+-----------------------------------------------------------------------+
|i7 : D1 = divisor({3, 1}, {ideal(x), ideal(y)})                        |
|                                                                       |
|o7 = 3*Div(x) + Div(y)                                                 |
|                                                                       |
|o7 : WeilDivisor on R                                                  |
+-----------------------------------------------------------------------+
|i8 : D2 = divisor({3/2, -1}, {ideal(x), ideal(y)}, CoefficientType=>QQ)|
|                                                                       |
|o8 = 3/2*Div(x) + -Div(y)                                              |
|                                                                       |
|o8 : QWeilDivisor on R                                                 |
+-----------------------------------------------------------------------+
|i9 : D3 = divisor({1.25}, {ideal(x)}, CoefficientType=>RR)             |
|                                                                       |
|o9 = 1.25*Div(x)                                                       |
|                                                                       |
|o9 : RWeilDivisor on R                                                 |
+-----------------------------------------------------------------------+
|i10 : D1+D2                                                            |
|                                                                       |
|o10 = 9/2*Div(x)                                                       |
|                                                                       |
|o10 : QWeilDivisor on R                                                |
+-----------------------------------------------------------------------+
|i11 : D1+D3                                                            |
|                                                                       |
|o11 = Div(y) + 4.25*Div(x)                                             |
|                                                                       |
|o11 : RWeilDivisor on R                                                |
+-----------------------------------------------------------------------+
|i12 : D2+D3                                                            |
|                                                                       |
|o12 = -Div(y) + 2.75*Div(x)                                            |
|                                                                       |
|o12 : RWeilDivisor on R                                                |
+-----------------------------------------------------------------------+

Finally, we can negate a divisor.

+------------------------------------------------------------------------+
|i13 : R = ZZ/3[x,y,z]/ideal(x^2-y*z);                                   |
+------------------------------------------------------------------------+
|i14 : D = divisor({3, 0, -1}, {ideal(x,z), ideal(y,z), ideal(x-y, x-z)})|
|                                                                        |
|o14 = 0*Div(y, z) + -Div(x-y, x-z) + 3*Div(x, z)                        |
|                                                                        |
|o14 : WeilDivisor on R                                                  |
+------------------------------------------------------------------------+
|i15 : -D                                                                |
|                                                                        |
|o15 = Div(x-y, x-z) + -3*Div(x, z)                                      |
|                                                                        |
|o15 : WeilDivisor on R                                                  |
+------------------------------------------------------------------------+
|i16 : E = divisor({3/2, -2/3}, {ideal(x, z), ideal(y, z)})              |
|                                                                        |
|o16 = -2/3*Div(y, z) + 3/2*Div(x, z)                                    |
|                                                                        |
|o16 : WeilDivisor on R                                                  |
+------------------------------------------------------------------------+
|i17 : -E                                                                |
|                                                                        |
|o17 = 2/3*Div(y, z) + -3/2*Div(x, z)                                    |
|                                                                        |
|o17 : WeilDivisor on R                                                  |
+------------------------------------------------------------------------+

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

  * BasicDivisor + BasicDivisor -- add or
    subtract two divisors, or negate a divisor

canonicalDivisor -- compute a canonical divisor of a ring
*********************************************************

Synopsis
========

  * Usage:
        canonicalDivisor( R )
  * Inputs:
      * R, a ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * IsGraded => a Boolean value (Macaulay2Doc), default
        value false, specify that the returned canonical divisor should reflect
        the grading of the ring
  * Outputs:
      * an instance of the type WeilDivisor,

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

Compute the canonical divisor of a ring (warning, the canonical divisor is not
unique, but only unique up to linear equivalence).  If the IsGraded option is
set to true (default false), then it will return a canonical divisor for the
$Proj$ of $R$, otherwise it will return one for only the $Spec$.  The graded
version only works reliably for graded rings over a field (for instance, if you
have a Rees algebra you will need to flatten the variables).

+----------------------------------------+
|i1 : R = QQ[x,y,z];                     |
+----------------------------------------+
|i2 : canonicalDivisor(R)                |
|                                        |
|o2 = 0, the zero divisor                |
|                                        |
|o2 : WeilDivisor on R                   |
+----------------------------------------+
|i3 : canonicalDivisor(R, IsGraded=>true)|
|                                        |
|o3 = -3*Div(x)                          |
|                                        |
|o3 : WeilDivisor on R                   |
+----------------------------------------+

Note the IsGraded option makes a difference.  Consider now a non-Gorenstein
singularity.

+------------------------------------------------------+
|i4 : R = QQ[a,b,c,d]/ideal(c^2-b*d, b*c-a*d, b^2-a*c);|
+------------------------------------------------------+
|i5 : canonicalDivisor(R)                              |
|                                                      |
|o5 = -2*Div(d, c, b)                                  |
|                                                      |
|o5 : WeilDivisor on R                                 |
+------------------------------------------------------+

Caveat
======

Text This function assumes that the coefficientRing of the ambient ring is a
field (or at least Gorenstein).  If the coefficientRing is a more general ring,
this function will  produce a relative canonical divisor of the ring over its
coefficientRing.

Ways to use canonicalDivisor :
==============================

  * "canonicalDivisor(Ring)"

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

The object canonicalDivisor, is a method function with options (Macaulay2Doc).

ceiling(RWeilDivisor) -- produce a WeilDivisor whose coefficients are ceilings or floors of the divisor
*******************************************************************************************************

Synopsis
========

  * Function: ceiling (Macaulay2Doc),
  * Usage:
        ceiling( E1 )
        floor( E1 )
  * Inputs:
      * E1, an instance of the type RWeilDivisor,
  * Outputs:
      * an instance of the type WeilDivisor,

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

Start with a rational or real Weil divisor.  We form a new divisor whose
coefficients are obtained by applying the ceiling or floor function to them.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y, z] / ideal(x *y - z^2);                                    |
+-----------------------------------------------------------------------------+
|i2 : D = divisor({1/2, 4/3}, {ideal(x, z), ideal(y, z)}, CoefficientType =>  |
|                                                                             |
|o2 = 1/2*Div(x, z) + 4/3*Div(y, z)                                           |
|                                                                             |
|o2 : QWeilDivisor on R                                                       |
|-----------------------------------------------------------------------------|
|QQ)                                                                          |
+-----------------------------------------------------------------------------+
|i3 : ceiling( D )                                                            |
|                                                                             |
|o3 = Div(x, z) + 2*Div(y, z)                                                 |
|                                                                             |
|o3 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i4 : floor( D )                                                              |
|                                                                             |
|o4 = Div(y, z)                                                               |
|                                                                             |
|o4 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i5 : E = divisor({0.3, -0.7}, {ideal(x, z), ideal(y,z)}, CoefficientType =>  |
|                                                                             |
|o5 = .3*Div(x, z) + -.7*Div(y, z)                                            |
|                                                                             |
|o5 : RWeilDivisor on R                                                       |
|-----------------------------------------------------------------------------|
|RR)                                                                          |
+-----------------------------------------------------------------------------+
|i6 : ceiling( E )                                                            |
|                                                                             |
|o6 = Div(x, z)                                                               |
|                                                                             |
|o6 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i7 : floor( E )                                                              |
|                                                                             |
|o7 = -Div(z, y)                                                              |
|                                                                             |
|o7 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+

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

  * ceiling(RWeilDivisor) -- produce a
    WeilDivisor whose coefficients are ceilings or floors of the divisor

cleanSupport -- removes primes with coefficient zero from a divisor
*******************************************************************

Synopsis
========

  * Usage:
        cleanSupport( D1 )
  * Inputs:
      * D1, an instance of the type BasicDivisor,
  * Outputs:
      * an instance of the type BasicDivisor,

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

This function returns a divisor where all entries with coefficient zero are
removed.

+----------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                       |
+----------------------------------------------------------+
|i2 : D = divisor({1,0,-2}, {ideal(x), ideal(y), ideal(z)})|
|                                                          |
|o2 = 0*Div(y) + -2*Div(z) + Div(x)                        |
|                                                          |
|o2 : WeilDivisor on R                                     |
+----------------------------------------------------------+
|i3 : cleanSupport(D)                                      |
|                                                          |
|o3 = -2*Div(z) + Div(x)                                   |
|                                                          |
|o3 : WeilDivisor on R                                     |
+----------------------------------------------------------+

Ways to use cleanSupport :
==========================

  * "cleanSupport(BasicDivisor)"

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

The object cleanSupport, is a method function (Macaulay2Doc).

clearCache -- creates a new divisor with most entries from the cache removed
****************************************************************************

Synopsis
========

  * Usage:
        clearCache( D1 )
  * Inputs:
      * D1, an instance of the type BasicDivisor,
  * Outputs:
      * an instance of the type BasicDivisor,

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

This function returns a divisor where the only entries left in the cache is the
key ideals (which points to how the ideals should be displayed to the user).

+----------------------------------------------------+
|i1 : R = QQ[x,y,z];                                 |
+----------------------------------------------------+
|i2 : D = divisor(x);                                |
|                                                    |
|o2 : WeilDivisor on R                               |
+----------------------------------------------------+
|i3 : isPrincipal(D)                                 |
|                                                    |
|o3 = true                                           |
+----------------------------------------------------+
|i4 : peek (D#cache)                                 |
|                                                    |
|o4 = CacheTable{ideals => MutableHashTable{...1...}}|
|                isPrincipal => {false, true}        |
|                                    1               |
|                divisorToModule => R                |
+----------------------------------------------------+
|i5 : E = clearCache(D);                             |
|                                                    |
|o5 : WeilDivisor on R                               |
+----------------------------------------------------+
|i6 : peek (E#cache)                                 |
|                                                    |
|o6 = CacheTable{ideals => MutableHashTable{...1...}}|
+----------------------------------------------------+

Ways to use clearCache :
========================

  * "clearCache(BasicDivisor)"

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

The object clearCache, is a method function (Macaulay2Doc).

coefficient(BasicList,BasicDivisor) -- get the coefficient of an ideal for a fixed divisor
******************************************************************************************

Synopsis
========

  * Function: coefficient (Macaulay2Doc),
  * Usage:
        coefficient(L, D)
  * Inputs:
      * L, a basic list (Macaulay2Doc), the list of elements
        in a Grobner basis of a height one prime ideal that we want to find the
        coefficient of
      * D, an instance of the type BasicDivisor, the
        divisor in question
  * Outputs:
      * a number (Macaulay2Doc),

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

This function returns the coefficient of $D$ along the prime divisor generated
by $L$ assuming $L$ is the ordered list of an element

+----------------------------------------+
|i1 : R = QQ[x,y,u,v]/ideal(x*y-u*v);    |
+----------------------------------------+
|i2 : E = divisor(x*u)                   |
|                                        |
|o2 = Div(v, x) + Div(u, y) + 2*Div(u, x)|
|                                        |
|o2 : WeilDivisor on R                   |
+----------------------------------------+
|i3 : coefficient({u, x}, E)             |
|                                        |
|o3 = 2                                  |
+----------------------------------------+
|i4 : coefficient({x, u}, E)             |
|                                        |
|o4 = 0                                  |
+----------------------------------------+

See also
========

  * coefficient(Ideal,BasicDivisor)
    -- get the coefficient of an ideal
    for a fixed divisor
  * coefficients(BasicDivisor) -- get
    the list of coefficients of a divisor

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

  * coefficient(BasicList,BasicDivisor)
    -- get the coefficient of an
    ideal for a fixed divisor

coefficient(Ideal,BasicDivisor) -- get the coefficient of an ideal for a fixed divisor
**************************************************************************************

Synopsis
========

  * Function: coefficient (Macaulay2Doc),
  * Usage:
        coefficient(P, D)
  * Inputs:
      * P, an ideal (Macaulay2Doc), the height one prime ideal
        that we want to find the coefficient of
      * D, an instance of the type BasicDivisor, the
        divisor in question
  * Outputs:
      * a number (Macaulay2Doc),

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

This function returns the coefficient of $D$ along the prime divisor associated
to $P$.

+----------------------------------------+
|i1 : R = QQ[x,y,u,v]/ideal(x*y-u*v);    |
+----------------------------------------+
|i2 : D = divisor(x)                     |
|                                        |
|o2 = Div(v, x) + Div(u, x)              |
|                                        |
|o2 : WeilDivisor on R                   |
+----------------------------------------+
|i3 : coefficient(ideal(x,u), D)         |
|                                        |
|o3 = 1                                  |
+----------------------------------------+
|i4 : E = divisor(x*u)                   |
|                                        |
|o4 = Div(v, x) + Div(u, y) + 2*Div(u, x)|
|                                        |
|o4 : WeilDivisor on R                   |
+----------------------------------------+
|i5 : coefficient(ideal(x,u), E)         |
|                                        |
|o5 = 2                                  |
+----------------------------------------+

See also
========

  * coefficient(BasicList,BasicDivisor)
    -- get the coefficient of an
    ideal for a fixed divisor
  * coefficients(BasicDivisor) -- get
    the list of coefficients of a divisor

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

  * coefficient(Ideal,BasicDivisor)
    -- get the coefficient of an ideal
    for a fixed divisor

coefficients(BasicDivisor) -- get the list of coefficients of a divisor
***********************************************************************

Synopsis
========

  * Function: coefficients (Macaulay2Doc),
  * Usage:
        coefficients( D1 )
  * Inputs:
      * D1, an instance of the type BasicDivisor,
  * Optional inputs (Macaulay2Doc),:
      * Monomials (Macaulay2Doc), => ..., default value
        null, null
      * Variables (Macaulay2Doc), => ..., default value
        null, null
  * Outputs:
      * a list (Macaulay2Doc),

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

Get the list of coefficients of a BasicDivisor (or a WeilDivisor, QWeilDivisor
or RWeilDivisor).

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y,u,v]/ideal(x*y-u*v);                                         |
+-----------------------------------------------------------------------------+
|i2 : D = divisor(x);                                                         |
|                                                                             |
|o2 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i3 : coefficients(D)                                                         |
|                                                                             |
|o3 = {1, 1}                                                                  |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : E = divisor(x*u);                                                       |
|                                                                             |
|o4 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i5 : coefficients(E)                                                         |
|                                                                             |
|o5 = {1, 1, 2}                                                               |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : F = divisor({0, 1/2, -2/3}, {ideal(y, u), ideal(x,u), ideal(x,v)},      |
|                                                                             |
|o6 = 0*Div(y, u) + 1/2*Div(x, u) + -2/3*Div(x, v)                            |
|                                                                             |
|o6 : QWeilDivisor on R                                                       |
|-----------------------------------------------------------------------------|
|CoefficientType => QQ)                                                       |
+-----------------------------------------------------------------------------+
|i7 : coefficients(F)                                                         |
|                                                                             |
|         1    2                                                              |
|o7 = {0, -, - -}                                                             |
|         2    3                                                              |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : G = divisor({0.5, -0.667}, {ideal(x,u), ideal(x,v)}, CoefficientType => |
|                                                                             |
|o8 = .5*Div(x, u) + -.667*Div(x, v)                                          |
|                                                                             |
|o8 : RWeilDivisor on R                                                       |
|-----------------------------------------------------------------------------|
|RR)                                                                          |
+-----------------------------------------------------------------------------+
|i9 : coefficients(G)                                                         |
|                                                                             |
|o9 = {.5, -.667}                                                             |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * coefficient(Ideal,BasicDivisor)
    -- get the coefficient of an ideal
    for a fixed divisor
  * primes -- get the list of height-one primes in the support
    of a divisor
  * gbs -- get the list of Groebner bases corresponding to the
    height-one primes in the support of a divisor

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

  * coefficients(BasicDivisor) -- get
    the list of coefficients of a divisor

CoefficientType -- an option used to tell divisor construction that a particular type of coefficients are expected.
*******************************************************************************************************************

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

Can be set to ZZ, QQ or RR (or any other Thing) when divisor is called, it
checks whether the coefficient list is a list of instances of this type.  If it
is set to ZZ, QQ or RR then a WeilDivisor, QWeilDivisor or RWeilDivisor are
created.  Default value is ZZ.

Functions with optional argument named CoefficientType :
========================================================

  * "applyToCoefficients(...,CoefficientType=>...)" -- see
    applyToCoefficients, -- apply a function to the
    coefficients of a divisor
  * "divisor(...,CoefficientType=>...)" -- see divisor, --
    constructor for (Weil/Q/R)-divisors

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

The object CoefficientType, is a symbol (Macaulay2Doc).

divisor -- constructor for (Weil/Q/R)-divisors
**********************************************

Synopsis
========

  * Usage:
        divisor(l1, l2)
        divisor( l3)
        divisor( I )
        divisor( f )
        divisor( M )
        divisor( Mat )
  * Inputs:
      * l1, a basic list (Macaulay2Doc), which describes the
        list of coefficients in integers
      * l2, a basic list (Macaulay2Doc), which describes the
        list of height one prime ideals that corresponds to codimension one
        irreducible subspaces
      * l3, a basic list (Macaulay2Doc), a list of pairs {c,
        P} where c is a coefficient and P is a prime ideal
      * I, an ideal (Macaulay2Doc), construct a divisor out of the
        vanishing locus of I
      * f, a ring element (Macaulay2Doc), construct a
        divisor out of the vanishing locus of ideal(f)
      * M, a module (Macaulay2Doc), construct a divisor such that
        O(D) is isomorphic to M
      * Mat, a matrix (Macaulay2Doc), a matrix, construct an
        effective divisor such that O(D) is isomorphic to the target of Mat
        based on the section
  * Optional inputs (Macaulay2Doc),:
      * CoefficientType => an integer (Macaulay2Doc), default value
        ZZ, specify the coefficients of your divisor
      * AmbientRing => a ring (Macaulay2Doc), default value null,
        specify the ambient ring in the divisor constructor
      * Section => a ring element (Macaulay2Doc), default
        value null, specify a global section of the ideal I used to construct
        an effective divisor
      * Section => a matrix (Macaulay2Doc), default value null,
        specify a global section of a module M used to construct an effective
        divisor
      * IsGraded => a Boolean value (Macaulay2Doc), default
        value false, specify a that a divisor constructed from a module should
        view the module as a graded object
  * Outputs:
      * an instance of the type BasicDivisor,

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

This is the general function for constructing divisors.  There are many ways to
call it.  In our first example, we construct divisors on $A^3$ (which can also
be viewed as divisors on $P^2$ since the ideals are homogeneous).  The
following creates the same Weil divisor with coefficients 1, 2 and 3 in five
different ways.

+---------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                            |
+---------------------------------------------------------------+
|i2 : D = divisor({1,2,3}, {ideal(x), ideal(y), ideal(z)})      |
|                                                               |
|o2 = 2*Div(y) + 3*Div(z) + Div(x)                              |
|                                                               |
|o2 : WeilDivisor on R                                          |
+---------------------------------------------------------------+
|i3 : E = divisor(x*y^2*z^3)                                    |
|                                                               |
|o3 = 2*Div(y) + 3*Div(z) + Div(x)                              |
|                                                               |
|o3 : WeilDivisor on R                                          |
+---------------------------------------------------------------+
|i4 : F = divisor(ideal(x*y^2*z^3))                             |
|                                                               |
|o4 = 2*Div(y) + 3*Div(z) + Div(x)                              |
|                                                               |
|o4 : WeilDivisor on R                                          |
+---------------------------------------------------------------+
|i5 : G = divisor({{1, ideal(x)}, {2, ideal(y)}, {3, ideal(z)}})|
|                                                               |
|o5 = 2*Div(y) + 3*Div(z) + Div(x)                              |
|                                                               |
|o5 : WeilDivisor on R                                          |
+---------------------------------------------------------------+
|i6 : H = divisor(x) + 2*divisor(y) + 3*divisor(z)              |
|                                                               |
|o6 = 3*Div(z) + 2*Div(y) + Div(x)                              |
|                                                               |
|o6 : WeilDivisor on R                                          |
+---------------------------------------------------------------+

Next we construct the same divisor in two different ways.  We are working on
the quadric cone, and we are working with a divisor of a ruling of the cone.
This divisor is not Cartier, but 2 times it is.

+-----------------------------------+
|i7 : R = QQ[x,y,z]/ideal(x^2-y*z); |
+-----------------------------------+
|i8 : D = divisor({2}, {ideal(x,y)})|
|                                   |
|o8 = 2*Div(x, y)                   |
|                                   |
|o8 : WeilDivisor on R              |
+-----------------------------------+
|i9 : E = divisor(y)                |
|                                   |
|o9 = 2*Div(y, x)                   |
|                                   |
|o9 : WeilDivisor on R              |
+-----------------------------------+

Here is a similar example in a slightly more complicated Veronese ring.

+-----------------------------------------------------------------------------+
|i10 : R = QQ[x,y,z];                                                         |
+-----------------------------------------------------------------------------+
|i11 : S = QQ[x3,x2y, x2z, xy2, xyz, xz2, y3, y2z, yz2, z3];                  |
+-----------------------------------------------------------------------------+
|i12 : f = map(R, S, {x^3, x^2*y, x^2*z, x*y^2, x*y*z, x*z^2, y^3, y^2*z,     |
|                                                                             |
|o12 : RingMap R <--- S                                                       |
|-----------------------------------------------------------------------------|
|y*z^2, z^3});                                                                |
+-----------------------------------------------------------------------------+
|i13 : A = S/(ker f);                                                         |
+-----------------------------------------------------------------------------+
|i14 : D = divisor(x3)                                                        |
|                                                                             |
|o14 = 3*Div(xz2, xyz, xy2, x2z, x2y, x3)                                     |
|                                                                             |
|o14 : WeilDivisor on A                                                       |
+-----------------------------------------------------------------------------+
|i15 : E = divisor(y2z)                                                       |
|                                                                             |
|o15 = Div(z3, yz2, y2z, xz2, xyz, x2z) + 2*Div(yz2, y2z, y3, xyz, xy2, x2y)  |
|                                                                             |
|o15 : WeilDivisor on A                                                       |
+-----------------------------------------------------------------------------+

We can construct a Q-divisor as well.  Here are two ways to do it (we work in
$A^2$ this time).

+-----------------------------------------------------------------------------+
|i16 : R = ZZ/7[x,y];                                                         |
+-----------------------------------------------------------------------------+
|i17 : D = divisor({-1/2, 2/1}, {ideal(y^2-x^3), ideal(x)},                   |
|                                                                             |
|o17 = 2*Div(x) + -1/2*Div(-x^3+y^2)                                          |
|                                                                             |
|o17 : QWeilDivisor on R                                                      |
|-----------------------------------------------------------------------------|
|CoefficientType=>QQ)                                                         |
+-----------------------------------------------------------------------------+
|i18 : D = (-1/2)*divisor(y^2-x^3) + (2/1)*divisor(x)                         |
|                                                                             |
|o18 = 2*Div(x) + -1/2*Div(-x^3+y^2)                                          |
|                                                                             |
|o18 : QWeilDivisor on R                                                      |
+-----------------------------------------------------------------------------+

Or an R-divisor.  This time we work in the cone over $P^1 \times P^1$.

+-----------------------------------------------------------------------------+
|i19 : R = ZZ/11[x,y,u,v]/ideal(x*y-u*v);                                     |
+-----------------------------------------------------------------------------+
|i20 : D = divisor({1.1, -3.14159}, {ideal(x,u), ideal(x, v)},                |
|                                                                             |
|o20 = 1.1*Div(x, u) + -3.14159*Div(x, v)                                     |
|                                                                             |
|o20 : RWeilDivisor on R                                                      |
|-----------------------------------------------------------------------------|
|CoefficientType=>RR)                                                         |
+-----------------------------------------------------------------------------+
|i21 : D = 1.1*divisor(ideal(x,u)) - 3.14159*divisor(ideal(x,v))              |
|                                                                             |
|o21 = 1.1*Div(x, u) + -3.14159*Div(x, v)                                     |
|                                                                             |
|o21 : RWeilDivisor on R                                                      |
+-----------------------------------------------------------------------------+

You can also pass it an element of the ring or even the fraction field.

+----------------------+
|i22 : R = QQ[x,y];    |
+----------------------+
|i23 : divisor(x)      |
|                      |
|o23 = Div(x)          |
|                      |
|o23 : WeilDivisor on R|
+----------------------+
|i24 : divisor(x/y)    |
|                      |
|o24 = Div(x) + -Div(y)|
|                      |
|o24 : WeilDivisor on R|
+----------------------+

Given a rank 1 reflexive module M, divisor(M) finds a divisor $D$ such that
$O(D)$ is isomorphic to M.  If IsGraded is true (it is false by default) this
assumes we are working on the Proj of the ambient ring.

+-----------------------------------+
|i25 : R = QQ[x,y,z]/ideal(x^2-y*z);|
+-----------------------------------+
|i26 : M = (ideal(y*x,y*z))*R^1;    |
+-----------------------------------+
|i27 : divisor(M)                   |
|                                   |
|o27 = -Div(z, x)                   |
|                                   |
|o27 : WeilDivisor on R             |
+-----------------------------------+
|i28 : divisor(M, IsGraded=>true)   |
|                                   |
|o28 = -2*Div(z, x) + -Div(y, x)    |
|                                   |
|o28 : WeilDivisor on R             |
+-----------------------------------+

Finally, divisor(Matrix) assumes that the matrix is a map from a rank-1 free
module to the module corresponding to $O(D)$.  In that case, this function
returns the effective divisor corresponding to that section.  The same behavior
can also be obtained by calling divisor(Module, Section=>Matrix) where the
Matrix is a map from a rank-1 free module to M.  In the following example, we
demonstrate this by considering a rank-1 module (on the cone of $P^1 \times
P^1$), and considering the map from $R^1$ mapping to the first generator of the
module.

+-------------------------------------+
|i29 : R = QQ[x,y,u,v]/ideal(x*y-u*v);|
+-------------------------------------+
|i30 : M = (ideal(x,u))*R^1;          |
+-------------------------------------+
|i31 : matr = map(M, R^1, {{1},{0}}); |
|                                     |
|o31 : Matrix                         |
+-------------------------------------+
|i32 : divisor(matr)                  |
|                                     |
|o32 = Div(v, x)                      |
|                                     |
|o32 : WeilDivisor on R               |
+-------------------------------------+
|i33 : divisor(M, Section=>matr)      |
|                                     |
|o33 = Div(v, x)                      |
|                                     |
|o33 : WeilDivisor on R               |
+-------------------------------------+

One can also obtain the same behavior (as divisor(Matrix)) by passing the
divisor either an ideal or a module and then specifying a global section of
that object (which will produce the corresponding effective divisor).  In
particular, if the main argument in the divisor is an Ideal, the option
Section=>f specifies that we should find the unique effective divisor $D$ such
that I is isomorphic to $O(D)$ and such that f maps to 1 under that
isomorphism.

+-----------------------------------------+
|i34 : R = QQ[x,y,u,v]/ideal(x*y-u*v)     |
|                                         |
|o34 = R                                  |
|                                         |
|o34 : QuotientRing                       |
+-----------------------------------------+
|i35 : D = divisor(ideal(x,u), Section=>x)|
|                                         |
|o35 = Div(v, x)                          |
|                                         |
|o35 : WeilDivisor on R                   |
+-----------------------------------------+

Note if the section is not in $I$, then it is interpreted as a rational section
and the produced divisor $D$ may not be effective.

If the main argument in the divisor is a module, then the Matrix Mat should be
a matrix mapping a free module to M.  In this case divisor constructs the
unique effective divisor $D$ such that M is isomorphic to $O(D)$ and so that
$1$ in the matrix map is mapped to $1$ in $O(D)$.

+----------------------------------------------+
|i36 : R = QQ[x];                              |
+----------------------------------------------+
|i37 : D = divisor(R^1, Section=>matrix{{x^2}})|
|                                              |
|o37 = 2*Div(x)                                |
|                                              |
|o37 : WeilDivisor on R                        |
+----------------------------------------------+

Ways to use divisor :
=====================

  * "divisor(BasicList)"
  * "divisor(BasicList,BasicList)"
  * "divisor(Ideal)"
  * "divisor(Matrix)"
  * "divisor(Module)"
  * "divisor(RingElement)"

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

The object divisor, is a method function with options (Macaulay2Doc).

dualize -- finds an ideal or module isomorphic to Hom(M, R)
***********************************************************

Synopsis
========

  * Usage:
        dualize( I1 )
        dualize( M1 )
  * Inputs:
      * I1, an ideal (Macaulay2Doc),
      * M1, a module (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * KnownDomain => a Boolean value (Macaulay2Doc), default
        value true, assume the ambient ring is a domain
      * Strategy => a symbol (Macaulay2Doc), default value
        NoStrategy, specify the strategy of dualize
  * Outputs:
      * an ideal (Macaulay2Doc),
      * a module (Macaulay2Doc),

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

This computes $Hom_R(M, R)$.

+----------------------------------+
|i1 : R = QQ[x,y,z]/ideal(x^2-y*z);|
+----------------------------------+
|i2 : m = ideal(x,y,z);            |
|                                  |
|o2 : Ideal of R                   |
+----------------------------------+
|i3 : dualize(m)                   |
|                                  |
|o3 = ideal x                      |
|                                  |
|o3 : Ideal of R                   |
+----------------------------------+
|i4 : I = ideal(x,y);              |
|                                  |
|o4 : Ideal of R                   |
+----------------------------------+
|i5 : dualize(I)                   |
|                                  |
|o5 = ideal (z, x)                 |
|                                  |
|o5 : Ideal of R                   |
+----------------------------------+
|i6 : dualize(I^2)                 |
|                                  |
|o6 = ideal z                      |
|                                  |
|o6 : Ideal of R                   |
+----------------------------------+
|i7 : dualize(I^3)                 |
|                                  |
|             2                    |
|o7 = ideal (z , x*z)              |
|                                  |
|o7 : Ideal of R                   |
+----------------------------------+

If Strategy => IdealStrategy, then dualize assume the module is isomorphic to
an ideal, embeds it as an ideal, and computes the dual by forming a colon.
ModuleStrategy simply computes the Hom.  The default Strategy for modules is
ModuleStrategy, and the default Strategy for ideals is IdealStrategy.  This is
because there is overhead using the opposite strategy (involving embedding
modules as ideals).  Frequently IdealStrategy is faster, but not always.
Consider first a D4 singularity in characteristic 2.

+-------------------------------------------------------------+
|i8 : R = ZZ/2[x,y,z]/ideal(z^2-x*y*z-x^2*y-x*y^2);           |
+-------------------------------------------------------------+
|i9 : m = ideal(x,y,z);                                       |
|                                                             |
|o9 : Ideal of R                                              |
+-------------------------------------------------------------+
|i10 : J = m^9;                                               |
|                                                             |
|o10 : Ideal of R                                             |
+-------------------------------------------------------------+
|i11 : M = J*R^1;                                             |
+-------------------------------------------------------------+
|i12 : time dualize(J, Strategy=>IdealStrategy);              |
|     -- used 0.0347976 seconds                               |
|                                                             |
|o12 : Ideal of R                                             |
+-------------------------------------------------------------+
|i13 : time dualize(J, Strategy=>ModuleStrategy);             |
|     -- used 0.63112 seconds                                 |
|                                                             |
|o13 : Ideal of R                                             |
+-------------------------------------------------------------+
|i14 : time dualize(M, Strategy=>IdealStrategy);              |
|     -- used 0.644135 seconds                                |
+-------------------------------------------------------------+
|i15 : time dualize(M, Strategy=>ModuleStrategy);             |
|     -- used 0.00396864 seconds                              |
+-------------------------------------------------------------+
|i16 : time embedAsIdeal dualize(M, Strategy=>ModuleStrategy);|
|     -- used 0.0025548 seconds                               |
|                                                             |
|o16 : Ideal of R                                             |
+-------------------------------------------------------------+

For monomial ideals in toric rings, frequently ModuleStrategy appears faster.

+------------------------------------------------+
|i17 : R = ZZ/7[x,y,u,v]/ideal(x*y-u*v);         |
+------------------------------------------------+
|i18 : I = ideal(x,u);                           |
|                                                |
|o18 : Ideal of R                                |
+------------------------------------------------+
|i19 : J = I^15;                                 |
|                                                |
|o19 : Ideal of R                                |
+------------------------------------------------+
|i20 : time dualize(J, Strategy=>IdealStrategy); |
|     -- used 0.0677324 seconds                  |
|                                                |
|o20 : Ideal of R                                |
+------------------------------------------------+
|i21 : time dualize(J, Strategy=>ModuleStrategy);|
|     -- used 0.0142182 seconds                  |
|                                                |
|o21 : Ideal of R                                |
+------------------------------------------------+

KnownDomain is an option for dualize.  If it is false (default is true), then
the computer will first check whether the ring is a domain, if it is not then
it will revert to ModuleStrategy.  If KnownDomain is set to true for a
non-domain, then the function can return an incorrect answer.

+------------------------------------+
|i22 : R = QQ[x,y]/ideal(x*y);       |
+------------------------------------+
|i23 : J = ideal(x,y);               |
|                                    |
|o23 : Ideal of R                    |
+------------------------------------+
|i24 : dualize(J, KnownDomain=>true) |
|                                    |
|o24 = ideal x                       |
|                                    |
|o24 : Ideal of R                    |
+------------------------------------+
|i25 : dualize(J, KnownDomain=>false)|
|                                    |
|o25 = ideal (y, x)                  |
|                                    |
|o25 : Ideal of R                    |
+------------------------------------+

See also
========

  * reflexify -- calculate the double dual of an ideal or
    module Hom(Hom(M, R), R)

Ways to use dualize :
=====================

  * "dualize(Ideal)"
  * "dualize(Module)"

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

The object dualize, is a method function with options (Macaulay2Doc).

embedAsIdeal -- embed a module as an ideal of a ring
****************************************************

Synopsis
========

  * Usage:
        I = embedAsIdeal(R, M, MTries=>n, IsGraded=>false)
        L = embedAsIdeal(R, M, MTries=>n, IsGraded=>true)
        L = embedAsIdeal(R, M, MTries=>n, ReturnMap=>true)
        L = embedAsIdeal(R, M, MTries=>n, ReturnMap=>true, IsGraded=>true)
  * Inputs:
      * M, a module (Macaulay2Doc),
      * R, a ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * MTries => an integer (Macaulay2Doc), default value 10, how
        many times random attempts to embed the module should be attempted if
        the first attempt fails
      * IsGraded => a Boolean value (Macaulay2Doc), default
        value false, specify that the module is graded and instruct the
        function to return the degree shift of the embedding
      * ReturnMap => a Boolean value (Macaulay2Doc), default
        value false, specify that the function should also return a map from
        the module to R^1, identifying the embedding
      * Section => a ring element (Macaulay2Doc), default
        value null, used to specify that the function will keep track of a
        certain element
  * Outputs:
      * I, an ideal (Macaulay2Doc), the module embedded as an
        ideal
      * L, a list (Macaulay2Doc), if IsGraded is true, then this
        function returns the degree shift of the embedding as a second entry in
        a list.  Further if ReturnMap is true, then a map from the module to
        the ring is also returned as another entry in this list.  Finally, if a
        matrix defining is passed to the function, then the first entry in the
        list is this ring element.

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

Tries to embed the module $M$ as an ideal in $R$.  It will make several
automatic tries followed by MTries => n attempts (the default n value is 10).
Parts of this function were based on code originally written in the Macaulay2
Divisor tutorial and also based on code by Mordechai Katzman, see the
canonicalIdeal function in
http://katzman.staff.shef.ac.uk/FSplitting/ParameterTestIdeals.m2

+------------------------------+
|i1 : R = QQ[x,y]              |
|                              |
|o1 = R                        |
|                              |
|o1 : PolynomialRing           |
+------------------------------+
|i2 : M = (ideal(x^2,x*y))*R^1 |
|                              |
|o2 = image | x2 xy |          |
|                              |
|                             1|
|o2 : R-module, submodule of R |
+------------------------------+
|i3 : embedAsIdeal(M)          |
|                              |
|o3 = ideal (y, x)             |
|                              |
|o3 : Ideal of R               |
+------------------------------+

It also works for non-domains

+-------------------------------+
|i4 : R = QQ[x,y]/ideal(x*y);   |
+-------------------------------+
|i5 : M = (ideal(x^3, y^5))*R^1;|
+-------------------------------+
|i6 : embedAsIdeal(M)           |
|                               |
|o6 = ideal (y, x)              |
|                               |
|o6 : Ideal of R                |
+-------------------------------+
|i7 : N = (ideal(x,y))*R^1;     |
+-------------------------------+
|i8 : embedAsIdeal(N)           |
|                               |
|o8 = ideal (y, x)              |
|                               |
|o8 : Ideal of R                |
+-------------------------------+

Note that the answer is right even if you don't recognize it at first.  Next,
consider the IsGraded option. If this is set to true, then the system returns
the degree as well (as you can see in the example below).   The default value
for the option IsGraded is false.

+-------------------------------------+
|i9 : R = QQ[x,y];                    |
+-------------------------------------+
|i10 : M = R^{-3};                    |
+-------------------------------------+
|i11 : embedAsIdeal(M, IsGraded=>true)|
|                                     |
|o11 = {ideal 1, {-3}}                |
|                                     |
|o11 : List                           |
+-------------------------------------+

Next consider the ReturnMap option.  What this does is also return the map from
M to R^1 of which the map is based upon.  Note that if both IsGraded and
ReturnMap are enabled, then the map comes after the degree.

+------------------------------------------+
|i12 : R = QQ[x,y];                        |
+------------------------------------------+
|i13 : M = ideal(x^2, x*y)*R^1;            |
+------------------------------------------+
|i14 : L = embedAsIdeal(M, ReturnMap=>true)|
|                                          |
|o14 = {ideal (y, x), | x y |}             |
|                                          |
|o14 : List                                |
+------------------------------------------+
|i15 : target L#1                          |
|                                          |
|       1                                  |
|o15 = R                                   |
|                                          |
|o15 : R-module, free                      |
+------------------------------------------+
|i16 : source L#1                          |
|                                          |
|o16 = image | x2 xy |                     |
|                                          |
|                              1           |
|o16 : R-module, submodule of R            |
+------------------------------------------+

Alternately, instead of passing an ideal you can pass embedAsIdeal a Matrix,
where the source is a free module of rank one and the target is the module you
wish to embed.  (This can also be accomplished by passing the same matrix via
the Section option).  In this case, the first output will be a ring element
corresponding to the section.

+------------------------------------+
|i17 : R = QQ[x,y];                  |
+------------------------------------+
|i18 : M = (ideal(x^2,x*y))*R^1;     |
+------------------------------------+
|i19 : mat = map(M, R^1, {{1}, {1}});|
|                                    |
|o19 : Matrix                        |
+------------------------------------+
|i20 : embedAsIdeal(mat)             |
|                                    |
|o20 = {x + y, ideal (y, x)}         |
|                                    |
|o20 : List                          |
+------------------------------------+
|i21 : embedAsIdeal(M, Section=>mat) |
|                                    |
|o21 = {x + y, ideal (y, x)}         |
|                                    |
|o21 : List                          |
+------------------------------------+

Ways to use embedAsIdeal :
==========================

  * "embedAsIdeal(Matrix)"
  * "embedAsIdeal(Module)"
  * "embedAsIdeal(Ring,Matrix)"
  * "embedAsIdeal(Ring,Module)"

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

The object embedAsIdeal, is a method function with options (Macaulay2Doc).

findElementOfDegree -- find an element of a specified degree
************************************************************

Synopsis
========

  * Usage:
        findElementOfDegree( n, R )
        findElementOfDegree( l, R )
  * Inputs:
      * R, a ring (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
      * l, a basic list (Macaulay2Doc),
  * Outputs:
      * a basic list (Macaulay2Doc),

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

Given a singly graded ring and an integer $n$, this function tries to find an
element of degree $n$.  If successful, it returns a list with two elements
{$a,b$} such that $a/b$ has degree $n$.  If it is impossible, it gives an
error.  If instead of an integer, you pass it a basic list corresponding to a
multi-degree, it still tries to find $a, b$ in R such that $a/b$ has the
provided multidegree.  It only works on rings with flattened variables (ie, no
Rees algebras). First we do an example without multidegrees.

+---------------------------------------+
|i1 : R = ZZ/7[x,y,Degrees=>{3, 5}];    |
+---------------------------------------+
|i2 : output = findElementOfDegree(1, R)|
|                                       |
|       2                               |
|o2 = {x , y}                           |
|                                       |
|o2 : List                              |
+---------------------------------------+
|i3 : output#0/output#1                 |
|                                       |
|      2                                |
|     x                                 |
|o3 = --                                |
|      y                                |
|                                       |
|o3 : frac R                            |
+---------------------------------------+
|i4 : findElementOfDegree(-2, R)        |
|                                       |
|       2   4                           |
|o4 = {y , x }                          |
|                                       |
|o4 : List                              |
+---------------------------------------+

We also do an example with multidegrees

+--------------------------------------------+
|i5 : R = QQ[x,y,Degrees=>{{1,2}, {3, 5}}];  |
+--------------------------------------------+
|i6 : output = findElementOfDegree({1, 3}, R)|
|                                            |
|       4                                    |
|o6 = {x , y}                                |
|                                            |
|o6 : List                                   |
+--------------------------------------------+
|i7 : output#0/output#1                      |
|                                            |
|      4                                     |
|     x                                      |
|o7 = --                                     |
|      y                                     |
|                                            |
|o7 : frac R                                 |
+--------------------------------------------+

See also
========

  * divisor(...,IsGraded=>...) -- constructor for
    (Weil/Q/R)-divisors
  * getLinearDiophantineSolution -- find a
    solution of the linear Diophantine equation Ax = b

Ways to use findElementOfDegree :
=================================

  * "findElementOfDegree(BasicList,Ring)"
  * "findElementOfDegree(ZZ,Ring)"

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

The object findElementOfDegree, is a method function (Macaulay2Doc).

gbs -- get the list of Groebner bases corresponding to the height-one primes in the support of a divisor
********************************************************************************************************

Synopsis
========

  * Usage:
        gbs( D1 )
  * Inputs:
      * D1, an instance of the type BasicDivisor,
  * Outputs:
      * a list (Macaulay2Doc),

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

This function returns the list of Groebner bases associated to the height-one
prime ideals corresponding to the components of a BasicDivisor (or a
WeilDivisor, QWeilDivisor or RWeilDivisor).  Note that this list of Groebner
bases is made when the divisor is constructed.

+--------------------------------------+
|i1 : R = ZZ/7[x,y,u,v]/ideal(x*y-u*v);|
+--------------------------------------+
|i2 : D = divisor(x)                   |
|                                      |
|o2 = Div(v, x) + Div(u, x)            |
|                                      |
|o2 : WeilDivisor on R                 |
+--------------------------------------+
|i3 : gbs(D)                           |
|                                      |
|o3 = {{v, x}, {u, x}}                 |
|                                      |
|o3 : List                             |
+--------------------------------------+

Note, the Grobner basis can be different from a minimal set of generators the
user provides.

+--------------------------------------------------+
|i4 : R = ZZ/2[x,y,z]/ideal(z^2+x*y*z+x^2*y+x*y^2);|
+--------------------------------------------------+
|i5 : J = ideal(x+y, x^2+z);                       |
|                                                  |
|o5 : Ideal of R                                   |
+--------------------------------------------------+
|i6 : D = divisor({2}, {J})                        |
|                                                  |
|o6 = 2*Div(x+y, x^2+z)                            |
|                                                  |
|o6 : WeilDivisor on R                             |
+--------------------------------------------------+
|i7 : gbs(D)                                       |
|                                                  |
|               2                                  |
|o7 = {{x + y, y  + z}}                            |
|                                                  |
|o7 : List                                         |
+--------------------------------------------------+
|i8 : primes(D)                                    |
|                                                  |
|                     2                            |
|o8 = {ideal (x + y, x  + z)}                      |
|                                                  |
|o8 : List                                         |
+--------------------------------------------------+

See also
========

  * coefficients(BasicDivisor) -- get
    the list of coefficients of a divisor
  * primes -- get the list of height-one primes in the support
    of a divisor

Ways to use gbs :
=================

  * "gbs(BasicDivisor)"

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

The object gbs, is a method function (Macaulay2Doc).

getLinearDiophantineSolution -- find a solution of the linear Diophantine equation Ax = b
*****************************************************************************************

Synopsis
========

  * Usage:
        getLinearDiophantineSolution(l, L)
        getLinearDiophantineSolution(l, A)
  * Inputs:
      * L, a basic list (Macaulay2Doc),
      * l, a basic list (Macaulay2Doc),
      * A, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Safe => a Boolean value (Macaulay2Doc), default value
        true, turns on or off routine checks in the function
  * Outputs:
      * a list (Macaulay2Doc),

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

Given a linear Diophantine equation $Ax = b$ (i.e. an integer matrix with
target vector also integer), we want to find a solution of this equation.

+-------------------------------------------------------------------+
|i1 : colList = {{1,3,7}, {2,4,-31}, {1,6,101}, {3,-2,47}, {8,9,1}};|
+-------------------------------------------------------------------+
|i2 : A = transpose matrix colList;                                 |
|                                                                   |
|              3        5                                           |
|o2 : Matrix ZZ  <--- ZZ                                            |
+-------------------------------------------------------------------+
|i3 : b = {1, 2, 3}                                                 |
|                                                                   |
|o3 = {1, 2, 3}                                                     |
|                                                                   |
|o3 : List                                                          |
+-------------------------------------------------------------------+
|i4 : getLinearDiophantineSolution(b, A)                            |
|                                                                   |
|o4 = {-9268, 3946, 1941, -188, 0}                                  |
|                                                                   |
|o4 : List                                                          |
+-------------------------------------------------------------------+
|i5 : sol = getLinearDiophantineSolution(b, colList )               |
|                                                                   |
|o5 = {-9268, 3946, 1941, -188, 0}                                  |
|                                                                   |
|o5 : List                                                          |
+-------------------------------------------------------------------+
|i6 : sum apply(#sol, i->(sol#i)*(colList#i) )                      |
|                                                                   |
|o6 = {1, 2, 3}                                                     |
|                                                                   |
|o6 : List                                                          |
+-------------------------------------------------------------------+

When the context is clear, set the Safe option to false in order to avoid
routine checks.

+--------------------------------------------------------------------+
|i7 : A = matrix{ {1, 0, 0, 0, 0}, {0, 2, 0, 0, 0}, {3, 4, 5, 6, 8} }|
|                                                                    |
|o7 = | 1 0 0 0 0 |                                                  |
|     | 0 2 0 0 0 |                                                  |
|     | 3 4 5 6 8 |                                                  |
|                                                                    |
|              3        5                                            |
|o7 : Matrix ZZ  <--- ZZ                                             |
+--------------------------------------------------------------------+
|i8 : b = {1, 2, 3}                                                  |
|                                                                    |
|o8 = {1, 2, 3}                                                      |
|                                                                    |
|o8 : List                                                           |
+--------------------------------------------------------------------+
|i9 : getLinearDiophantineSolution(b, A, Safe => false)              |
|                                                                    |
|o9 = {1, 1, 16, -14, 0}                                             |
|                                                                    |
|o9 : List                                                           |
+--------------------------------------------------------------------+

See also
========

  * findElementOfDegree -- find an element of a
    specified degree

Ways to use getLinearDiophantineSolution :
==========================================

  * "getLinearDiophantineSolution(BasicList,BasicList)"
  * "getLinearDiophantineSolution(BasicList,Matrix)"

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

The object getLinearDiophantineSolution, is
a method function with options (Macaulay2Doc).

getPrimeCount -- get the number of height-one primes in the support of the divisor
**********************************************************************************

Synopsis
========

  * Usage:
        getPrimeCount( D1 )
  * Inputs:
      * D1, an instance of the type BasicDivisor,
  * Outputs:
      * a list (Macaulay2Doc),

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

This function returns the number of height one prime ideals corresponding to
the components of a BasicDivisor.  Note that if you don't call cleanSupport,
this can return primes with coefficient equal to zero.

+----------------------------------------+
|i1 : R = QQ[x,y,u,v]/ideal(x*y-u*v);    |
+----------------------------------------+
|i2 : D = divisor(x)                     |
|                                        |
|o2 = Div(v, x) + Div(u, x)              |
|                                        |
|o2 : WeilDivisor on R                   |
+----------------------------------------+
|i3 : getPrimeCount(D)                   |
|                                        |
|o3 = 2                                  |
+----------------------------------------+
|i4 : E = divisor(x*u)                   |
|                                        |
|o4 = Div(v, x) + Div(u, y) + 2*Div(u, x)|
|                                        |
|o4 : WeilDivisor on R                   |
+----------------------------------------+
|i5 : getPrimeCount(E)                   |
|                                        |
|o5 = 3                                  |
+----------------------------------------+
|i6 : F = divisor({0}, {ideal(x,u)})     |
|                                        |
|o6 = 0*Div(x, u)                        |
|                                        |
|o6 : WeilDivisor on R                   |
+----------------------------------------+
|i7 : getPrimeCount(F)                   |
|                                        |
|o7 = 1                                  |
+----------------------------------------+
|i8 : getPrimeCount(cleanSupport F)      |
|                                        |
|o8 = 0                                  |
+----------------------------------------+
|i9 : getPrimeCount(1*F)                 |
|                                        |
|o9 = 0                                  |
+----------------------------------------+

This is equivalent to #primes.

See also
========

  * coefficients(BasicDivisor) -- get
    the list of coefficients of a divisor
  * gbs -- get the list of Groebner bases corresponding to the
    height-one primes in the support of a divisor

Ways to use getPrimeCount :
===========================

  * "getPrimeCount(BasicDivisor)"

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

The object getPrimeCount, is a method function (Macaulay2Doc).

getPrimeDivisors -- get the list of prime divisors of a given divisor
*********************************************************************

Synopsis
========

  * Usage:
        getPrimeDivisors( D1 )
  * Inputs:
      * D1, an instance of the type BasicDivisor,
  * Outputs:
      * a list (Macaulay2Doc),

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

This function returns the list of prime divisors of a given divisor.  The prime
divisors are all of the class WeilDivisor.  If you do not call cleanSupport,
you may obtain divisors with zero coefficients.

+----------------------------------------------------------------+
|i1 : R = QQ[x, y, z];                                           |
+----------------------------------------------------------------+
|i2 : D = divisor({-8, 2, 0}, {ideal(x), ideal(y), ideal(x^2+z)})|
|                                                                |
|o2 = 2*Div(y) + 0*Div(x^2+z) + -8*Div(x)                        |
|                                                                |
|o2 : WeilDivisor on R                                           |
+----------------------------------------------------------------+
|i3 : getPrimeDivisors( D )                                      |
|                                                                |
|o3 = {Div(y), Div(x^2+z), Div(x)}                               |
|                                                                |
|o3 : List                                                       |
+----------------------------------------------------------------+
|i4 : getPrimeDivisors( cleanSupport D )                         |
|                                                                |
|o4 = {Div(y), Div(x)}                                           |
|                                                                |
|o4 : List                                                       |
+----------------------------------------------------------------+

Ways to use getPrimeDivisors :
==============================

  * "getPrimeDivisors(BasicDivisor)"

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

The object getPrimeDivisors, is a method function (Macaulay2Doc).

ideal(RWeilDivisor) -- calculate the corresponding module of a divisor and represent it as an ideal
***************************************************************************************************

Synopsis
========

  * Function: ideal (Macaulay2Doc),
  * Usage:
        ideal( D1 )
  * Inputs:
      * D1, an instance of the type RWeilDivisor,
  * Outputs:
      * an ideal (Macaulay2Doc),

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

Get an ideal associated to $O(-D)$ of a Weil Divisor $D$.  Recall that on an
affine scheme, $O(-D)$ is by definition the subset of the fraction field made
up of elements such that $Div(f) - D \geq 0$.  If $D$ is effective, this will
produce the ideal corresponding to $O(-D)$.  Otherwise, it will produce some
ideal isomorphic to a module corresponding to $O(-D)$.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y, u, v] / ideal(x * y - u * v);                              |
+-----------------------------------------------------------------------------+
|i2 : D1 = divisor({1, -2, 3, -4}, {ideal(x, u), ideal(x, v), ideal(y, u),    |
|                                                                             |
|o2 = -4*Div(y, v) + Div(x, u) + -2*Div(x, v) + 3*Div(y, u)                   |
|                                                                             |
|o2 : WeilDivisor on R                                                        |
|-----------------------------------------------------------------------------|
|ideal(y, v)})                                                                |
+-----------------------------------------------------------------------------+
|i3 : ideal( D1 )                                                             |
|                                                                             |
|             4 2     3 2   2 2 2     4    2 4                                |
|o3 = ideal (u v , y*u v , y u v , x*u v, x u )                               |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : D2 = divisor(ideal(x,u))                                                |
|                                                                             |
|o4 = Div(x, u)                                                               |
|                                                                             |
|o4 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i5 : ideal(D2)                                                               |
|                                                                             |
|o5 = ideal (u, x)                                                            |
|                                                                             |
|o5 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

Note, if the divisor has non-integer coefficients, their ceilings will be
taken, since $O(-D) = O(floor(-D)) = O(-ceiling(D))$.

+--------------------------------------------+
|i6 : R = QQ[x,y,z]/(ideal(x^3 + y^3 - z^3));|
+--------------------------------------------+
|i7 : D1 = 1.3*divisor(ideal(x, y-z))        |
|                                            |
|o7 = 1.3*Div(x, y-z)                        |
|                                            |
|o7 : RWeilDivisor on R                      |
+--------------------------------------------+
|i8 : ideal D1                               |
|                                            |
|                    2                       |
|o8 = ideal (y - z, x )                      |
|                                            |
|o8 : Ideal of R                             |
+--------------------------------------------+
|i9 : I1 = ideal (ceiling(D1))               |
|                                            |
|                    2                       |
|o9 = ideal (y - z, x )                      |
|                                            |
|o9 : Ideal of R                             |
+--------------------------------------------+
|i10 : I2 = ideal (-ceiling(D1))             |
|                                            |
|              2          2   2              |
|o10 = ideal (y  + y*z + z , x )             |
|                                            |
|o10 : Ideal of R                            |
+--------------------------------------------+
|i11 : reflexify(I1*I2)                      |
|                                            |
|             2                              |
|o11 = ideal x                               |
|                                            |
|o11 : Ideal of R                            |
+--------------------------------------------+

The output value of this function is stored in the divisor's cache.

See also
========

  * OO RWeilDivisor -- calculate module corresponding
    to divisor

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

  * "ideal(QWeilDivisor)"
  * ideal(RWeilDivisor) -- calculate the
    corresponding module of a divisor and represent it as an ideal
  * "ideal(WeilDivisor)"

idealPower -- compute the ideal generated by the generators of the ideal raised to a power
******************************************************************************************

Synopsis
========

  * Usage:
        idealPower(n, I)
  * Inputs:
      * n, an integer (Macaulay2Doc),
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * an ideal (Macaulay2Doc),

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

If I is generated by $(f1, ..., fk)$ then idealPower(n, I) is the ideal
generated by $(f1^n, ..., fk^n)$.  This is relevant because idealPower(n, I)
and I^n have the same reflexification, but idealPower(n, I) can be much faster
to compute with since it has fewer generators typically.

+-----------------------------------------------+
|i1 : R = QQ[x, y, u, v] / ideal(x * y - u * v);|
+-----------------------------------------------+
|i2 : I = ideal(x, u);                          |
|                                               |
|o2 : Ideal of R                                |
+-----------------------------------------------+
|i3 : idealPower(5, I)                          |
|                                               |
|             5   5                             |
|o3 = ideal (x , u )                            |
|                                               |
|o3 : Ideal of R                                |
+-----------------------------------------------+
|i4 : I^5                                       |
|                                               |
|             5   4    3 2   2 3     4   5      |
|o4 = ideal (x , x u, x u , x u , x*u , u )     |
|                                               |
|o4 : Ideal of R                                |
+-----------------------------------------------+

See also
========

  * reflexify -- calculate the double dual of an ideal or
    module Hom(Hom(M, R), R)

Ways to use idealPower :
========================

  * "idealPower(ZZ,Ideal)"

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

The object idealPower, is a method function (Macaulay2Doc).

ideals -- a symbol used as a key within the divisor cache
*********************************************************

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

Each divisor has a cache (a CacheTable).  One of the keys of this cache is
always (symbol ideals).  This points to a MutableHashTable whose keys are lists
of elements in a Groebner basis and which themselves point to how the ideal
should be displayed.  Note the trim command trims these ideals.

See also
========

  * trim(BasicDivisor) -- trims the ideals
    displayed to the user and removes primes with coefficient zero

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

The object ideals, is a symbol (Macaulay2Doc).

IdealStrategy -- a valid value for the Strategy option in dualize or reflexify
******************************************************************************

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

This is a valid input for the Strategy option of dualize or reflexify.

See also
========

  * dualize -- finds an ideal or module isomorphic to Hom(M, R)
  * reflexify -- calculate the double dual of an ideal or
    module Hom(Hom(M, R), R)

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

The object IdealStrategy, is a symbol (Macaulay2Doc).

isCartier -- whether a Weil divisor is Cartier
**********************************************

Synopsis
========

  * Usage:
        isCartier( D )
  * Inputs:
      * D, an instance of the type WeilDivisor,
  * Optional inputs (Macaulay2Doc),:
      * IsGraded => a Boolean value (Macaulay2Doc), default
        value false, set to true to assume that we are doing this check on a
        projective variety
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

Check if a Weil divisor is Cartier.  For example, the following divisor is not
Cartier

+-----------------------------------------------------+
|i1 : R = QQ[x, y, u, v] / ideal(x * y - u * v);      |
+-----------------------------------------------------+
|i2 : D = divisor({2, -3}, {ideal(x, u), ideal(y, v)})|
|                                                     |
|o2 = 2*Div(x, u) + -3*Div(y, v)                      |
|                                                     |
|o2 : WeilDivisor on R                                |
+-----------------------------------------------------+
|i3 : isCartier( D )                                  |
|                                                     |
|o3 = false                                           |
+-----------------------------------------------------+

Neither is this divisor.

+----------------------------------------------------+
|i4 : R = QQ[x, y, z] / ideal(x * y - z^2 );         |
+----------------------------------------------------+
|i5 : D = divisor({1, 2}, {ideal(x, z), ideal(y, z)})|
|                                                    |
|o5 = Div(x, z) + 2*Div(y, z)                        |
|                                                    |
|o5 : WeilDivisor on R                               |
+----------------------------------------------------+
|i6 : isCartier( D )                                 |
|                                                    |
|o6 = false                                          |
+----------------------------------------------------+

Of course the next divisor is Cartier.

+----------------------------------------------+
|i7 : R = QQ[x, y, z];                         |
+----------------------------------------------+
|i8 : D = divisor({1, 2}, {ideal(x), ideal(y)})|
|                                              |
|o8 = 2*Div(y) + Div(x)                        |
|                                              |
|o8 : WeilDivisor on R                         |
+----------------------------------------------+
|i9 : isCartier( D )                           |
|                                              |
|o9 = true                                     |
+----------------------------------------------+

If the option IsGraded is set to true (it is false by default), this will check
as if D is a divisor on the $Proj$ of the ambient graded ring.

+------------------------------------------------------+
|i10 : R = QQ[x, y, u, v] / ideal(x * y - u * v);      |
+------------------------------------------------------+
|i11 : D = divisor({2, -3}, {ideal(x, u), ideal(y, v)})|
|                                                      |
|o11 = 2*Div(x, u) + -3*Div(y, v)                      |
|                                                      |
|o11 : WeilDivisor on R                                |
+------------------------------------------------------+
|i12 : isCartier(D, IsGraded => true)                  |
|                                                      |
|o12 = true                                            |
+------------------------------------------------------+
+-----------------------------------------------------+
|i13 : R = QQ[x, y, z] / ideal(x * y - z^2);          |
+-----------------------------------------------------+
|i14 : D = divisor({1, 2}, {ideal(x, z), ideal(y, z)})|
|                                                     |
|o14 = Div(x, z) + 2*Div(y, z)                        |
|                                                     |
|o14 : WeilDivisor on R                               |
+-----------------------------------------------------+
|i15 : isCartier(D, IsGraded => true)                 |
|                                                     |
|o15 = true                                           |
+-----------------------------------------------------+

The output value of this function is stored in the divisor's cache with the
value of the last IsGraded option.  If you change the IsGraded option, the
value will be recomputed.

See also
========

  * OO RWeilDivisor -- calculate module corresponding
    to divisor
  * isQCartier -- whether m times a divisor is Cartier for
    any m from 1 to a fixed positive integer n1.

Ways to use isCartier :
=======================

  * "isCartier(WeilDivisor)"

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

The object isCartier, is a method function with options (Macaulay2Doc).

isDomain -- whether a ring is a domain
**************************************

Synopsis
========

  * Usage:
        isDomain(R)
  * Inputs:
      * R, a ring (Macaulay2Doc),
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function returns true if R is an integral domain, otherwise it returns
false.  It simply checks whether the zero ideal is prime.

+---------------------------------+
|i1 : R = QQ[x,y,z]/ideal(x^2-y*z)|
|                                 |
|o1 = R                           |
|                                 |
|o1 : QuotientRing                |
+---------------------------------+
|i2 : isDomain(R)                 |
|                                 |
|o2 = true                        |
+---------------------------------+
|i3 : S = ZZ/5[x,y]/ideal(x^2*y^3)|
|                                 |
|o3 = S                           |
|                                 |
|o3 : QuotientRing                |
+---------------------------------+
|i4 : isDomain(S)                 |
|                                 |
|o4 = false                       |
+---------------------------------+

Ways to use isDomain :
======================

  * "isDomain(Ring)"

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

The object isDomain, is a method function (Macaulay2Doc).

isEffective -- whether a divisor is effective
*********************************************

Synopsis
========

  * Usage:
        isEffective( D1 )
  * Inputs:
      * D1, an instance of the type WeilDivisor,
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function returns true if the divisor is effective (all coefficients
nonnegative), otherwise it returns false.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/31[x, y, u, v] / ideal(x * y - u * v);                           |
+-----------------------------------------------------------------------------+
|i2 : D1 = divisor({1, -2, 3, -4}, {ideal(x, u), ideal(x, v), ideal(y, u),    |
|                                                                             |
|o2 = -4*Div(y, v) + Div(x, u) + -2*Div(x, v) + 3*Div(y, u)                   |
|                                                                             |
|o2 : WeilDivisor on R                                                        |
|-----------------------------------------------------------------------------|
|ideal(y, v)})                                                                |
+-----------------------------------------------------------------------------+
|i3 : D2 = divisor({1, 39, 5, 27}, {ideal(x, v), ideal(y, v), ideal(x, u),    |
|                                                                             |
|o3 = Div(x, v) + 39*Div(y, v) + 32*Div(x, u)                                 |
|                                                                             |
|o3 : WeilDivisor on R                                                        |
|-----------------------------------------------------------------------------|
|ideal(x, u)})                                                                |
+-----------------------------------------------------------------------------+
|i4 : isEffective( D1 )                                                       |
|                                                                             |
|o4 = false                                                                   |
+-----------------------------------------------------------------------------+
|i5 : isEffective( D2 )                                                       |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+

Ways to use isEffective :
=========================

  * "isEffective(BasicDivisor)"

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

The object isEffective, is a method function (Macaulay2Doc).

IsGraded -- an option used by numerous functions which tells it to treat the divisors as if we were working on the Proj of the ambient ring.
********************************************************************************************************************************************

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

An option used by numerous functions which tells it to treat the divisors as if
we were working on the Proj of the ambient ring.  In other words, setting it to
true tells the function to ignore behavior at the irrelevant ideal (the ideal
generated by vars Ring).  Default value is false.

Functions with optional argument named IsGraded :
=================================================

  * "canonicalDivisor(...,IsGraded=>...)" -- see canonicalDivisor,
    -- compute a canonical divisor of a ring
  * "divisor(...,IsGraded=>...)" -- see divisor, -- constructor
    for (Weil/Q/R)-divisors
  * "embedAsIdeal(...,IsGraded=>...)" -- see embedAsIdeal,
    -- embed a module as an ideal of a ring
  * "isCartier(...,IsGraded=>...)" -- see isCartier, --
    whether a Weil divisor is Cartier
  * "isLinearEquivalent(...,IsGraded=>...)" -- see isLinearEquivalent,
    -- whether two Weil divisors are linearly equivalent
  * "isPrincipal(...,IsGraded=>...)" -- see isPrincipal, --
    whether a Weil divisor is globally principal
  * "isQCartier(...,IsGraded=>...)" -- see isQCartier, --
    whether m times a divisor is Cartier for any m from 1 to a fixed positive
    integer n1.
  * "isQLinearEquivalent(...,IsGraded=>...)" -- see isQLinearEquivalent,
    -- whether two Q-divisors are linearly equivalent
  * "isSmooth(...,IsGraded=>...)" -- see isSmooth, -- whether R
    mod the ideal is smooth
  * "isSNC(...,IsGraded=>...)" -- see isSNC, -- whether the
    divisor is simple normal crossings
  * "nonCartierLocus(...,IsGraded=>...)" -- see nonCartierLocus,
    -- the non-Cartier locus of a Weil divisor
  * "ramificationDivisor(...,IsGraded=>...)" -- see ramificationDivisor,
    -- compute the ramification divisor of a finite
    inclusion of normal domains or a blowup over a smooth base

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

The object IsGraded, is a symbol (Macaulay2Doc).

isHomogeneous(BasicDivisor) -- whether the divisor is graded (homogeneous)
**************************************************************************

Synopsis
========

  * Function: isHomogeneous (Macaulay2Doc),
  * Usage:
        isHomogeneous(D)
  * Inputs:
      * D, an instance of the type BasicDivisor,
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function returns true if the divisor is graded (homogeneous), otherwise it
returns false.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y, z];                                                        |
+-----------------------------------------------------------------------------+
|i2 : D = divisor({1, 2, 3}, {ideal(x * y - z^2), ideal(y * z - x^2), ideal(x |
|                                                                             |
|o2 = Div(x*y-z^2) + 2*Div(-x^2+y*z) + 3*Div(-y^2+x*z)                        |
|                                                                             |
|o2 : WeilDivisor on R                                                        |
|-----------------------------------------------------------------------------|
|* z - y^2)})                                                                 |
+-----------------------------------------------------------------------------+
|i3 : isHomogeneous( D )                                                      |
|                                                                             |
|o3 = true                                                                    |
+-----------------------------------------------------------------------------+
+----------------------------------------------------------------+
|i4 : R = QQ[x, y, z];                                           |
+----------------------------------------------------------------+
|i5 : D = divisor({1, 2}, {ideal(x * y - z^2), ideal(y^2 - z^3)})|
|                                                                |
|o5 = Div(x*y-z^2) + 2*Div(-z^3+y^2)                             |
|                                                                |
|o5 : WeilDivisor on R                                           |
+----------------------------------------------------------------+
|i6 : isHomogeneous( D )                                         |
|                                                                |
|o6 = false                                                      |
+----------------------------------------------------------------+

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

  * isHomogeneous(BasicDivisor), --
    whether the divisor is graded (homogeneous)

isLinearEquivalent -- whether two Weil divisors are linearly equivalent
***********************************************************************

Synopsis
========

  * Usage:
        flag = isLinearEquivalent(D1, D2)
  * Inputs:
      * D1, an instance of the type WeilDivisor,
      * D2, an instance of the type WeilDivisor,
  * Optional inputs (Macaulay2Doc),:
      * IsGraded => a Boolean value (Macaulay2Doc), default
        value false, specify that we are doing this computation on a projective
        algebraic variety
  * Outputs:
      * flag, a Boolean value (Macaulay2Doc),

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

Given two Weil divisors, this method checks whether they are linearly
equivalent.

+-----------------------------------------------------+
|i1 : R = QQ[x, y, z]/ ideal(x * y - z^2);            |
+-----------------------------------------------------+
|i2 : D1 = divisor({3, 8}, {ideal(x, z), ideal(y, z)})|
|                                                     |
|o2 = 3*Div(x, z) + 8*Div(y, z)                       |
|                                                     |
|o2 : WeilDivisor on R                                |
+-----------------------------------------------------+
|i3 : D2 = divisor({8, 1}, {ideal(y, z), ideal(x, z)})|
|                                                     |
|o3 = Div(x, z) + 8*Div(y, z)                         |
|                                                     |
|o3 : WeilDivisor on R                                |
+-----------------------------------------------------+
|i4 : isLinearEquivalent(D1, D2)                      |
|                                                     |
|o4 = true                                            |
+-----------------------------------------------------+

If IsGraded is set to true (by default it is false), then it treats the
divisors as divisors on the $Proj$ of their ambient ring.

+-----------------------------------------------------+
|i5 : R = QQ[x, y, z]/ ideal(x * y - z^2);            |
+-----------------------------------------------------+
|i6 : D1 = divisor({3, 8}, {ideal(x, z), ideal(y, z)})|
|                                                     |
|o6 = 8*Div(y, z) + 3*Div(x, z)                       |
|                                                     |
|o6 : WeilDivisor on R                                |
+-----------------------------------------------------+
|i7 : D2 = divisor({8, 1}, {ideal(y, z), ideal(x, z)})|
|                                                     |
|o7 = 8*Div(y, z) + Div(x, z)                         |
|                                                     |
|o7 : WeilDivisor on R                                |
+-----------------------------------------------------+
|i8 : isLinearEquivalent(D1, D2, IsGraded => true)    |
|                                                     |
|o8 = false                                           |
+-----------------------------------------------------+

See also
========

  * OO RWeilDivisor -- calculate module corresponding
    to divisor
  * isQLinearEquivalent -- whether two Q-divisors
    are linearly equivalent

Ways to use isLinearEquivalent :
================================

  * "isLinearEquivalent(WeilDivisor,WeilDivisor)"

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

The object isLinearEquivalent, is a method function with options (Macaulay2Doc).

isPrime(BasicDivisor) -- whether a divisor is prime
***************************************************

Synopsis
========

  * Function: isPrime (Macaulay2Doc),
  * Usage:
        isPrime( D1 )
  * Inputs:
      * D1, an instance of the type BasicDivisor,
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function returns true if the divisor is prime (with coefficient 1),
otherwise it returns false.

+--------------------------+
|i1 : R = QQ[x, y];        |
+--------------------------+
|i2 : D1 = divisor(x^2 * y)|
|                          |
|o2 = 2*Div(x) + Div(y)    |
|                          |
|o2 : WeilDivisor on R     |
+--------------------------+
|i3 : D2 = divisor(x^2)    |
|                          |
|o3 = 2*Div(x)             |
|                          |
|o3 : WeilDivisor on R     |
+--------------------------+
|i4 : D3 = divisor(y)      |
|                          |
|o4 = Div(y)               |
|                          |
|o4 : WeilDivisor on R     |
+--------------------------+
|i5 : isPrime( D1 )        |
|                          |
|o5 = false                |
+--------------------------+
|i6 : isPrime( D2 )        |
|                          |
|o6 = false                |
+--------------------------+
|i7 : isPrime( D3 )        |
|                          |
|o7 = true                 |
+--------------------------+

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

  * isPrime(BasicDivisor) -- whether a
    divisor is prime

isPrincipal -- whether a Weil divisor is globally principal
***********************************************************

Synopsis
========

  * Usage:
        isPrincipal( D, IsGraded => b )
  * Inputs:
      * D, an instance of the type WeilDivisor,
      * b, a Boolean value (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * IsGraded => ..., default value false
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function returns true if the Weil divisor D is principal, otherwise false.
If IsGraded is set to true, then this checks whether the divisor corresponds to
a principal divisor on the Proj of the ambient ring.  Note that this function
may return a false negative if the defining equations of the divisor are not
homogeneous (it warns the user if this occurs).

+-------------------------------------+
|i1 : R = QQ[x, y, z];                |
+-------------------------------------+
|i2 : D = divisor(x);                 |
|                                     |
|o2 : WeilDivisor on R                |
+-------------------------------------+
|i3 : isPrincipal(D, IsGraded => true)|
|                                     |
|o3 = false                           |
+-------------------------------------+

By default, IsGraded is set to false.  Regardless of the format, the check is
done by determining whether or not $O(D)$ is free.

+--------------------------------------+
|i4 : R = QQ[x, y, z]/ideal(x^2 - y*z);|
+--------------------------------------+
|i5 : D = divisor(x);                  |
|                                      |
|o5 : WeilDivisor on R                 |
+--------------------------------------+
|i6 : E = divisor(ideal(x,z));         |
|                                      |
|o6 : WeilDivisor on R                 |
+--------------------------------------+
|i7 : isPrincipal( D )                 |
|                                      |
|o7 = true                             |
+--------------------------------------+
|i8 : isPrincipal( E )                 |
|                                      |
|o8 = false                            |
+--------------------------------------+

The output value of this function is stored in the divisor's cache with the
value of the last IsGraded option.  If you change the IsGraded option, the
value will be recomputed.

See also
========

  * OO RWeilDivisor -- calculate module corresponding
    to divisor

Ways to use isPrincipal :
=========================

  * "isPrincipal(WeilDivisor)"

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

The object isPrincipal, is a method function with options (Macaulay2Doc).

isQCartier -- whether m times a divisor is Cartier for any m from 1 to a fixed positive integer n1.
***************************************************************************************************

Synopsis
========

  * Usage:
        isQCartier(n1, D1 )
        isQCartier(n1, D2 )
  * Inputs:
      * D1, an instance of the type WeilDivisor,
      * D2, an instance of the type QWeilDivisor,
      * n1, an integer (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * IsGraded => a Boolean value (Macaulay2Doc), default
        value false, specify that we should do this computation on a projective
        algebraic variety
  * Outputs:
      * b, a Boolean value (Macaulay2Doc),

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

Check whether $m$ times a Weil or Q-divisor $D$ is Cartier for each $m$ from 1
to a fixed positive integer n1 (if the divisor is a QWeilDivisor, it can search
slightly higher than n1).  If m * D1 is Cartier, it returns m.  If it fails to
find an m, it returns 0.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y, z] / ideal(x * y - z^2 );                                  |
+-----------------------------------------------------------------------------+
|i2 : D1 = divisor({1, 2}, {ideal(x, z), ideal(y, z)})                        |
|                                                                             |
|o2 = Div(x, z) + 2*Div(y, z)                                                 |
|                                                                             |
|o2 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i3 : D2 = divisor({1/2, 3/4}, {ideal(y, z), ideal(x, z)}, CoefficientType => |
|                                                                             |
|o3 = 3/4*Div(x, z) + 1/2*Div(y, z)                                           |
|                                                                             |
|o3 : QWeilDivisor on R                                                       |
|-----------------------------------------------------------------------------|
|QQ)                                                                          |
+-----------------------------------------------------------------------------+
|i4 : isQCartier(10, D1)                                                      |
|                                                                             |
|o4 = 2                                                                       |
+-----------------------------------------------------------------------------+
|i5 : isQCartier(10, D2)                                                      |
|                                                                             |
|o5 = 8                                                                       |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i6 : R = QQ[x, y, u, v] / ideal(x * y - u * v);                              |
+-----------------------------------------------------------------------------+
|i7 : D1 = divisor({1, 2}, {ideal(x, u), ideal(y, v)})                        |
|                                                                             |
|o7 = Div(x, u) + 2*Div(y, v)                                                 |
|                                                                             |
|o7 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i8 : D2 = divisor({1/2, -3/4}, {ideal(y, u), ideal(x, v)}, CoefficientType =>|
|                                                                             |
|o8 = 1/2*Div(y, u) + -3/4*Div(x, v)                                          |
|                                                                             |
|o8 : QWeilDivisor on R                                                       |
|-----------------------------------------------------------------------------|
|QQ)                                                                          |
+-----------------------------------------------------------------------------+
|i9 : isQCartier(10, D1)                                                      |
|                                                                             |
|o9 = 0                                                                       |
+-----------------------------------------------------------------------------+
|i10 : isQCartier(10, D2)                                                     |
|                                                                             |
|o10 = 0                                                                      |
+-----------------------------------------------------------------------------+

If the option IsGraded is set to true (by default it is false), then it treats
the divisor as a divisor on the $Proj$ of their ambient ring.

+-----------------------------------------------------------------------------+
|i11 : R = QQ[x, y, z] / ideal(x * y - z^2 );                                 |
+-----------------------------------------------------------------------------+
|i12 : D1 = divisor({1, 2}, {ideal(x, z), ideal(y, z)})                       |
|                                                                             |
|o12 = 2*Div(y, z) + Div(x, z)                                                |
|                                                                             |
|o12 : WeilDivisor on R                                                       |
+-----------------------------------------------------------------------------+
|i13 : D2 = divisor({1/2, 3/4}, {ideal(y, z), ideal(x, z)}, CoefficientType =>|
|                                                                             |
|o13 = 1/2*Div(y, z) + 3/4*Div(x, z)                                          |
|                                                                             |
|o13 : QWeilDivisor on R                                                      |
|-----------------------------------------------------------------------------|
|QQ)                                                                          |
+-----------------------------------------------------------------------------+
|i14 : isQCartier(10, D1, IsGraded => true)                                   |
|                                                                             |
|o14 = 1                                                                      |
+-----------------------------------------------------------------------------+
|i15 : isQCartier(10, D2, IsGraded => true)                                   |
|                                                                             |
|o15 = 4                                                                      |
+-----------------------------------------------------------------------------+

The output value of this function is stored in the divisor's cache with the
value of the last IsGraded option.  If you change the IsGraded option, the
value will be recomputed.

See also
========

  * isCartier -- whether a Weil divisor is Cartier

Ways to use isQCartier :
========================

  * "isQCartier(ZZ,QWeilDivisor)"
  * "isQCartier(ZZ,WeilDivisor)"

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

The object isQCartier, is a method function with options (Macaulay2Doc).

isQLinearEquivalent -- whether two Q-divisors are linearly equivalent
*********************************************************************

Synopsis
========

  * Usage:
        isQLinearEquivalent(n, D1, D2)
  * Inputs:
      * n, an integer (Macaulay2Doc),
      * D1, an instance of the type QWeilDivisor,
      * D2, an instance of the type QWeilDivisor,
  * Optional inputs (Macaulay2Doc),:
      * IsGraded => a Boolean value (Macaulay2Doc), default
        value false, specify that we should do this computation on a projective
        algebraic variety
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

Given two rational divisors, this method returns true if they linearly
equivalent after clearing denominators or if some further multiple up to n
makes them linearly equivalent.  Otherwise it returns false.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y, z] / ideal(x * y - z^2);                                   |
+-----------------------------------------------------------------------------+
|i2 : D = divisor({1/2, 3/4}, {ideal(x, z), ideal(y, z)}, CoefficientType =>  |
|                                                                             |
|o2 = 1/2*Div(x, z) + 3/4*Div(y, z)                                           |
|                                                                             |
|o2 : QWeilDivisor on R                                                       |
|-----------------------------------------------------------------------------|
|QQ)                                                                          |
+-----------------------------------------------------------------------------+
|i3 : E = divisor({3/4, 5/2}, {ideal(y, z), ideal(x, z)}, CoefficientType =>  |
|                                                                             |
|o3 = 5/2*Div(x, z) + 3/4*Div(y, z)                                           |
|                                                                             |
|o3 : QWeilDivisor on R                                                       |
|-----------------------------------------------------------------------------|
|QQ)                                                                          |
+-----------------------------------------------------------------------------+
|i4 : isQLinearEquivalent(10, D, E)                                           |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+

In the above ring, every pair of divisors is Q-linearly equivalent because the
Weil divisor class group is isomorphic to Z/2.  However, if we don't set n high
enough, the function will return false.

+----------------------------------------+
|i5 : R = QQ[x,y,z] / ideal(x * y - z^2);|
+----------------------------------------+
|i6 : D = divisor(x);                    |
|                                        |
|o6 : WeilDivisor on R                   |
+----------------------------------------+
|i7 : E = divisor(ideal(x,z));           |
|                                        |
|o7 : WeilDivisor on R                   |
+----------------------------------------+
|i8 : isQLinearEquivalent(1, D, E)       |
|                                        |
|o8 = false                              |
+----------------------------------------+
|i9 : isQLinearEquivalent(3, D, E)       |
|                                        |
|o9 = true                               |
+----------------------------------------+

If IsGraded=>true (the default is false), then it treats the divisors as if
they are divisors on the $Proj$ of their ambient ring.

+-----------------------------------------------------------------------------+
|i10 : R = QQ[x, y, z] / ideal(x * y - z^2);                                  |
+-----------------------------------------------------------------------------+
|i11 : D = divisor({1/2, 3/4}, {ideal(x, z), ideal(y, z)}, CoefficientType => |
|                                                                             |
|o11 = 3/4*Div(y, z) + 1/2*Div(x, z)                                          |
|                                                                             |
|o11 : QWeilDivisor on R                                                      |
|-----------------------------------------------------------------------------|
|QQ)                                                                          |
+-----------------------------------------------------------------------------+
|i12 : E = divisor({3/2, -1/4}, {ideal(y, z), ideal(x, z)}, CoefficientType =>|
|                                                                             |
|o12 = 3/2*Div(y, z) + -1/4*Div(x, z)                                         |
|                                                                             |
|o12 : QWeilDivisor on R                                                      |
|-----------------------------------------------------------------------------|
|QQ)                                                                          |
+-----------------------------------------------------------------------------+
|i13 : isQLinearEquivalent(10, D, E, IsGraded => true)                        |
|                                                                             |
|o13 = true                                                                   |
+-----------------------------------------------------------------------------+
|i14 : isQLinearEquivalent(10, 3*D, E, IsGraded => true)                      |
|                                                                             |
|o14 = false                                                                  |
+-----------------------------------------------------------------------------+

See also
========

  * OO RWeilDivisor -- calculate module corresponding
    to divisor
  * isLinearEquivalent -- whether two Weil divisors
    are linearly equivalent

Ways to use isQLinearEquivalent :
=================================

  * "isQLinearEquivalent(ZZ,QWeilDivisor,QWeilDivisor)"

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

The object isQLinearEquivalent, is a method function with options (Macaulay2Doc).

isReduced -- whether a divisor is reduced
*****************************************

Synopsis
========

  * Usage:
        isReduced( D1 )
  * Inputs:
      * D1, an instance of the type WeilDivisor,
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function returns true if the divisor is reduced (all coefficients equal to
1), otherwise it returns false.

+---------------------------------+
|i1 : R = QQ[x, y, z];            |
+---------------------------------+
|i2 : D1 = divisor(x^2 * y^3 * z) |
|                                 |
|o2 = 3*Div(y) + Div(z) + 2*Div(x)|
|                                 |
|o2 : WeilDivisor on R            |
+---------------------------------+
|i3 : D2 = divisor(x * y * z)     |
|                                 |
|o3 = Div(y) + Div(z) + Div(x)    |
|                                 |
|o3 : WeilDivisor on R            |
+---------------------------------+
|i4 : isReduced( D1 )             |
|                                 |
|o4 = false                       |
+---------------------------------+
|i5 : isReduced( D2 )             |
|                                 |
|o5 = true                        |
+---------------------------------+

Ways to use isReduced :
=======================

  * "isReduced(BasicDivisor)"

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

The object isReduced, is a method function (Macaulay2Doc).

isReflexive -- whether an ideal or module is reflexive
******************************************************

Synopsis
========

  * Usage:
        isReflexive( I1 )
        isReflexive( M1 )
  * Inputs:
      * I1, an ideal (Macaulay2Doc),
      * M1, a module (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Strategy => a symbol (Macaulay2Doc), default value
        NoStrategy, specify a strategy for the internal call to reflexify
      * KnownDomain => a Boolean value (Macaulay2Doc), default
        value true, assume the ambient ring is a domain for the internal call
        to reflexify
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function returns true if the module or ideal is reflexive, otherwise it
returns false.  In other words this checks if $M \cong Hom(Hom(M, R))$.  This
function calls reflexify and passes the options Strategy and KnownDomain
specified in its call.

+----------------------------------+
|i1 : R = QQ[x,y,z]/ideal(x^2-y*z);|
+----------------------------------+
|i2 : m = ideal(x,y,z);            |
|                                  |
|o2 : Ideal of R                   |
+----------------------------------+
|i3 : isReflexive(m)               |
|                                  |
|o3 = false                        |
+----------------------------------+
|i4 : isReflexive(m*R^1)           |
|                                  |
|o4 = false                        |
+----------------------------------+
|i5 : I = ideal(x,y);              |
|                                  |
|o5 : Ideal of R                   |
+----------------------------------+
|i6 : isReflexive(I)               |
|                                  |
|o6 = true                         |
+----------------------------------+
|i7 : isReflexive(I*R^1)           |
|                                  |
|o7 = true                         |
+----------------------------------+

See also
========

  * reflexify -- calculate the double dual of an ideal or
    module Hom(Hom(M, R), R)
  * Strategy (Macaulay2Doc) -- an optional argument
  * KnownDomain -- an option used to specify to certain
    functions that we know that the ring is a domain

Ways to use isReflexive :
=========================

  * "isReflexive(Ideal)"
  * "isReflexive(Module)"

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

The object isReflexive, is a method function with options (Macaulay2Doc).

isSmooth -- whether R mod the ideal is smooth
*********************************************

Synopsis
========

  * Usage:
        isSmooth( I )
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * IsGraded => a Boolean value (Macaulay2Doc), default
        value false, specify that we should do this computation on a projective
        algebraic variety
  * Outputs:
      * flag, a Boolean value (Macaulay2Doc),

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

This function returns true if $R/I$ is regular where $R$ is the ambient ring of
$I$, otherwise it sets to false.

+----------------------------+
|i1 : R = QQ[x, y, z];       |
+----------------------------+
|i2 : I = ideal(x * y - z^2 )|
|                            |
|                  2         |
|o2 = ideal(x*y - z )        |
|                            |
|o2 : Ideal of R             |
+----------------------------+
|i3 : isSmooth( I )          |
|                            |
|o3 = false                  |
+----------------------------+
+-----------------------------+
|i4 : R = QQ[x, y, u, v];     |
+-----------------------------+
|i5 : I = ideal(x * y - u * v)|
|                             |
|o5 = ideal(x*y - u*v)        |
|                             |
|o5 : Ideal of R              |
+-----------------------------+
|i6 : isSmooth( I )           |
|                             |
|o6 = false                   |
+-----------------------------+
+---------------------+
|i7 : R = QQ[x, y, z];|
+---------------------+
|i8 : J = ideal( x )  |
|                     |
|o8 = ideal x         |
|                     |
|o8 : Ideal of R      |
+---------------------+
|i9 : isSmooth( J )   |
|                     |
|o9 = true            |
+---------------------+

If IsGraded is set to true (default false) then it treats $I$ as an ideal on
$Proj R$ (and it assumes $R$ is standard graded over a field).  In particular,
singularities at the origin (corresponding to the irrelevant ideal) are
ignored.

+-----------------------------------+
|i10 : R = QQ[x, y, z];             |
+-----------------------------------+
|i11 : I = ideal(x * y - z^2 )      |
|                                   |
|                   2               |
|o11 = ideal(x*y - z )              |
|                                   |
|o11 : Ideal of R                   |
+-----------------------------------+
|i12 : isSmooth(I)                  |
|                                   |
|o12 = false                        |
+-----------------------------------+
|i13 : isSmooth(I, IsGraded => true)|
|                                   |
|o13 = true                         |
+-----------------------------------+
+-----------------------------------+
|i14 : R = QQ[x, y, u, v];          |
+-----------------------------------+
|i15 : I = ideal(x * y - u * v)     |
|                                   |
|o15 = ideal(x*y - u*v)             |
|                                   |
|o15 : Ideal of R                   |
+-----------------------------------+
|i16 : isSmooth(I)                  |
|                                   |
|o16 = false                        |
+-----------------------------------+
|i17 : isSmooth(I, IsGraded => true)|
|                                   |
|o17 = true                         |
+-----------------------------------+

Ways to use isSmooth :
======================

  * "isSmooth(Ideal)"

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

The object isSmooth, is a method function with options (Macaulay2Doc).

isSNC -- whether the divisor is simple normal crossings
*******************************************************

Synopsis
========

  * Usage:
        isSNC( D )
  * Inputs:
      * D, an instance of the type BasicDivisor,
  * Optional inputs (Macaulay2Doc),:
      * IsGraded => a Boolean value (Macaulay2Doc), default
        value false, specify that we should do this computation on a projective
        algebraic variety
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function returns true if the divisor is simple normal crossings, this
includes checking that the ambient ring is regular.

+-----------------------------------------------------+
|i1 : R = QQ[x, y, z] / ideal(x * y - z^2 );          |
+-----------------------------------------------------+
|i2 : D = divisor({1, -2}, {ideal(x, z), ideal(y, z)})|
|                                                     |
|o2 = Div(x, z) + -2*Div(y, z)                        |
|                                                     |
|o2 : WeilDivisor on R                                |
+-----------------------------------------------------+
|i3 : isSNC( D )                                      |
|                                                     |
|o3 = false                                           |
+-----------------------------------------------------+
+-------------------------------+
|i4 : R = QQ[x, y];             |
+-------------------------------+
|i5 : D = divisor(x*y*(x+y))    |
|                               |
|o5 = Div(x+y) + Div(y) + Div(x)|
|                               |
|o5 : WeilDivisor on R          |
+-------------------------------+
|i6 : isSNC( D )                |
|                               |
|o6 = false                     |
+-------------------------------+
+-------------------------------+
|i7 : R = QQ[x, y];             |
+-------------------------------+
|i8 : D = divisor(x*y*(x+1))    |
|                               |
|o8 = Div(y) + Div(x) + Div(x+1)|
|                               |
|o8 : WeilDivisor on R          |
+-------------------------------+
|i9 : isSNC( D )                |
|                               |
|o9 = true                      |
+-------------------------------+

If IsGraded is set to true (default false), then the divisor is treated as if
it is on the $Proj$ of the ambient ring.  In particular, non-SNC behavior at
the origin is ignored.

+------------------------------------------------------+
|i10 : R = QQ[x, y, z] / ideal(x * y - z^2 );          |
+------------------------------------------------------+
|i11 : D = divisor({1, -2}, {ideal(x, z), ideal(y, z)})|
|                                                      |
|o11 = Div(x, z) + -2*Div(y, z)                        |
|                                                      |
|o11 : WeilDivisor on R                                |
+------------------------------------------------------+
|i12 : isSNC( D, IsGraded => true )                    |
|                                                      |
|o12 = true                                            |
+------------------------------------------------------+
+----------------------------------+
|i13 : R = QQ[x, y];               |
+----------------------------------+
|i14 : D = divisor(x*y*(x+y))      |
|                                  |
|o14 = Div(x+y) + Div(y) + Div(x)  |
|                                  |
|o14 : WeilDivisor on R            |
+----------------------------------+
|i15 : isSNC( D, IsGraded => true )|
|                                  |
|o15 = true                        |
+----------------------------------+
+---------------------------------+
|i16 : R = QQ[x,y,z];             |
+---------------------------------+
|i17 : D = divisor(x*y*(x+y))     |
|                                 |
|o17 = Div(x) + Div(x+y) + Div(y) |
|                                 |
|o17 : WeilDivisor on R           |
+---------------------------------+
|i18 : isSNC( D, IsGraded => true)|
|                                 |
|o18 = false                      |
+---------------------------------+

The output value of this function is stored in the divisor's cache with the
value of the last IsGraded option.  If you change the IsGraded option, the
value will be recomputed.

Ways to use isSNC :
===================

  * "isSNC(BasicDivisor)"

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

The object isSNC, is a method function with options (Macaulay2Doc).

isVeryAmple -- whether a divisor is very ample.
***********************************************

Synopsis
========

  * Usage:
        isVeryAmple( D1 )
  * Inputs:
      * D1, an instance of the type WeilDivisor,
  * Optional inputs (Macaulay2Doc),:
      * Verbose => a Boolean value (Macaulay2Doc), default value
        false, pass the verbose option to the called isEmbedding method
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function returns true if the divisor is very ample, otherwise it returns
false.  It works by calling isEmbedding from the RationalMaps package.  If
Verbose is set to true, it will print Verbose output from isEmbedding.

+--------------------------------------------+
|i1 : R = QQ[x, y, z]/ideal(x^3 + y^3 - z^3);|
+--------------------------------------------+
|i2 : D = divisor(ideal(x, y-z));            |
|                                            |
|o2 : WeilDivisor on R                       |
+--------------------------------------------+
|i3 : isVeryAmple(D)                         |
|                                            |
|o3 = false                                  |
+--------------------------------------------+
|i4 : isVeryAmple(2*D)                       |
|                                            |
|o4 = false                                  |
+--------------------------------------------+
|i5 : isVeryAmple(3*D)                       |
|                                            |
|o5 = true                                   |
+--------------------------------------------+

The output value of this function is stored in the divisor's cache.

Ways to use isVeryAmple :
=========================

  * "isVeryAmple(WeilDivisor)"

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

The object isVeryAmple, is a method function with options (Macaulay2Doc).

isWeilDivisor -- whether a rational/real divisor is in actuality a Weil divisor
*******************************************************************************

Synopsis
========

  * Usage:
        isWeilDivisor( D2 )
  * Inputs:
      * D2, an instance of the type RWeilDivisor,
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

Check if a rational/real divisor is a Weil divisor

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y, z];                                                        |
+-----------------------------------------------------------------------------+
|i2 : D1 = divisor({1/1, 2/2, -6/3}, {ideal(x), ideal(y), ideal(z)},          |
|                                                                             |
|o2 = Div(y) + -2*Div(z) + Div(x)                                             |
|                                                                             |
|o2 : QWeilDivisor on R                                                       |
|-----------------------------------------------------------------------------|
|CoefficientType=>QQ)                                                         |
+-----------------------------------------------------------------------------+
|i3 : D2 = divisor({1/2, 3/4, 5/6}, {ideal(y), ideal(z), ideal(x)},           |
|                                                                             |
|o3 = 1/2*Div(y) + 3/4*Div(z) + 5/6*Div(x)                                    |
|                                                                             |
|o3 : QWeilDivisor on R                                                       |
|-----------------------------------------------------------------------------|
|CoefficientType=>QQ)                                                         |
+-----------------------------------------------------------------------------+
|i4 : isWeilDivisor( D1 )                                                     |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+
|i5 : isWeilDivisor( D2 )                                                     |
|                                                                             |
|o5 = false                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * toWeilDivisor -- create a Weil divisor from a Q or
    R-divisor

Ways to use isWeilDivisor :
===========================

  * "isWeilDivisor(RWeilDivisor)"

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

The object isWeilDivisor, is a method function (Macaulay2Doc).

isWellDefined(BasicDivisor) -- whether a divisor is valid
*********************************************************

Synopsis
========

  * Function: isWellDefined (Macaulay2Doc),
  * Usage:
        isWellDefined( D1 )
  * Inputs:
      * D1, an instance of the type BasicDivisor,
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function tries to verify that this is a valid divisor.  It checks that the
coefficients are from the right ring (in the
WeilDivisor/QWeilDivisor/RWeilDivisor cases at least).  It also checks to make
sure all the ideals are from the same ring, are prime, and have height one.  If
debugLevel > 0, the function will print an message explaining why the divisor
was not valid.

+-----------------------------------------------------------------------------+
|i1 : debugLevel = 1;                                                         |
+-----------------------------------------------------------------------------+
|i2 : R = QQ[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i3 : isWellDefined(divisor({1}, {ideal(x)} ))                                |
| -- 1 : (ContainmentHooks) with Strategy => Inhomogeneous from -*Function[/us|
| -- (minimalPrimes,Ideal) with Strategy => Monomial from -*Function[/usr/shar|
| -- (trim,Module) with Strategy => Complement from -*Function[/usr/share/Maca|
| -- (codim,Module) with Strategy => Default from -*Function[/usr/share/Macaul|
| -- (codim,Module) with Strategy => Default from -*Function[/usr/share/Macaul|
|                                                                             |
|o3 = true                                                                    |
|-----------------------------------------------------------------------------|
|r/share/Macaulay2/Core/modules2.m2:115:60-115:98]*-                          |
|e/Macaulay2/MinimalPrimes.m2:304:26-313:60]*-                                |
|ulay2/Core/matrix2.m2:248:61-248:112]*-                                      |
|ay2/Core/monideal.m2:37:56-49:51]*-                                          |
|ay2/Core/monideal.m2:37:56-49:51]*-                                          |
+-----------------------------------------------------------------------------+
|i4 : isWellDefined(divisor({1/2}, {ideal(x)} ))                              |
|(isWellDefined, BasicDivisor): Not all coefficients are integers             |
|                                                                             |
|o4 = false                                                                   |
+-----------------------------------------------------------------------------+
|i5 : isWellDefined(divisor({1/2}, {ideal(x)}, CoefficientType=>QQ))          |
| -- 1 : (ContainmentHooks) with Strategy => Inhomogeneous from -*Function[/us|
| -- (minimalPrimes,Ideal) with Strategy => Monomial from -*Function[/usr/shar|
| -- (trim,Module) with Strategy => Complement from -*Function[/usr/share/Maca|
| -- (codim,Module) with Strategy => Default from -*Function[/usr/share/Macaul|
| -- (codim,Module) with Strategy => Default from -*Function[/usr/share/Macaul|
|                                                                             |
|o5 = true                                                                    |
|-----------------------------------------------------------------------------|
|r/share/Macaulay2/Core/modules2.m2:115:60-115:98]*-                          |
|e/Macaulay2/MinimalPrimes.m2:304:26-313:60]*-                                |
|ulay2/Core/matrix2.m2:248:61-248:112]*-                                      |
|ay2/Core/monideal.m2:37:56-49:51]*-                                          |
|ay2/Core/monideal.m2:37:56-49:51]*-                                          |
+-----------------------------------------------------------------------------+
|i6 : isWellDefined(divisor({1}, {ideal(x,y)}))                               |
| -- 1 : (ContainmentHooks) with Strategy => Inhomogeneous from -*Function[/us|
| -- (minimalPrimes,Ideal) with Strategy => Monomial from -*Function[/usr/shar|
| -- (trim,Module) with Strategy => Complement from -*Function[/usr/share/Maca|
| -- (codim,Module) with Strategy => Default from -*Function[/usr/share/Macaul|
| -- 1 : (ContainmentHooks) with Strategy => Inhomogeneous from -*Function[/us|
| -- 1 : (ContainmentHooks) with Strategy => Inhomogeneous from -*Function[/us|
| -- (codim,Module) with Strategy => Default from -*Function[/usr/share/Macaul|
|(isWellDefined, BasicDivisor): Not all ideals are height one                 |
|                                                                             |
|o6 = false                                                                   |
|-----------------------------------------------------------------------------|
|r/share/Macaulay2/Core/modules2.m2:115:60-115:98]*-                          |
|e/Macaulay2/MinimalPrimes.m2:304:26-313:60]*-                                |
|ulay2/Core/matrix2.m2:248:61-248:112]*-                                      |
|ay2/Core/monideal.m2:37:56-49:51]*-                                          |
|r/share/Macaulay2/Core/modules2.m2:115:60-115:98]*-                          |
|r/share/Macaulay2/Core/modules2.m2:115:60-115:98]*-                          |
|ay2/Core/monideal.m2:37:56-49:51]*-                                          |
+-----------------------------------------------------------------------------+
|i7 : isWellDefined(divisor({1}, {ideal(x^2)}))                               |
| -- 1 : (ContainmentHooks) with Strategy => Inhomogeneous from -*Function[/us|
| -- (minimalPrimes,Ideal) with Strategy => Monomial from -*Function[/usr/shar|
| -- (trim,Module) with Strategy => Complement from -*Function[/usr/share/Maca|
| -- (codim,Module) with Strategy => Default from -*Function[/usr/share/Macaul|
| -- 1 : (ContainmentHooks) with Strategy => Inhomogeneous from -*Function[/us|
|(isWellDefined, BasicDivisor): Not all ideals are prime                      |
|                                                                             |
|o7 = false                                                                   |
|-----------------------------------------------------------------------------|
|r/share/Macaulay2/Core/modules2.m2:115:60-115:98]*-                          |
|e/Macaulay2/MinimalPrimes.m2:304:26-313:60]*-                                |
|ulay2/Core/matrix2.m2:248:61-248:112]*-                                      |
|ay2/Core/monideal.m2:37:56-49:51]*-                                          |
|r/share/Macaulay2/Core/modules2.m2:115:60-115:98]*-                          |
+-----------------------------------------------------------------------------+
|i8 : S = QQ[a,b];                                                            |
+-----------------------------------------------------------------------------+
|i9 : isWellDefined(divisor({1,2}, {ideal(x), ideal(a)}))                     |
|(isWellDefined, BasicDivisor): Not all ideals have the same ambient ring     |
|                                                                             |
|o9 = false                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * divisor -- constructor for (Weil/Q/R)-divisors

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

  * isWellDefined(BasicDivisor), --
    whether a divisor is valid

isZeroDivisor -- whether the divisor is the zero divisor
********************************************************

Synopsis
========

  * Usage:
        isZeroDivisor(D)
  * Inputs:
      * D, an instance of the type BasicDivisor,
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function returns true if the divisor is zero, otherwise it returns false.

+--------------------------------------------------------------------------+
|i1 : R = QQ[x, y, z];                                                     |
+--------------------------------------------------------------------------+
|i2 : D = divisor({1, 2, -3, 4}, {ideal(x), ideal(y), ideal(z), ideal(y)});|
|                                                                          |
|o2 : WeilDivisor on R                                                     |
+--------------------------------------------------------------------------+
|i3 : isZeroDivisor( D )                                                   |
|                                                                          |
|o3 = false                                                                |
+--------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i4 : R = QQ[x, y, z];                                                        |
+-----------------------------------------------------------------------------+
|i5 : E = divisor({1, 2, -3, 4, 5, -9, 13, 2, -15}, {ideal(x), ideal(x),      |
|                                                                             |
|o5 : WeilDivisor on R                                                        |
|-----------------------------------------------------------------------------|
|ideal(x), ideal(y), ideal(y), ideal(y), ideal(z), ideal(z), ideal(z)});      |
+-----------------------------------------------------------------------------+
|i6 : isZeroDivisor( E )                                                      |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

Ways to use isZeroDivisor :
===========================

  * "isZeroDivisor(BasicDivisor)"

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

The object isZeroDivisor, is a method function (Macaulay2Doc).

KnownCartier -- an option used to specify to certain functions that we know that the divisor is Cartier
*******************************************************************************************************

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

If true, then some functions will not check whether or not the divisor is
Cartier, they will assume it is and proceed.

Functions with optional argument named KnownCartier :
=====================================================

  * "mapToProjectiveSpace(...,KnownCartier=>...)" -- see
    mapToProjectiveSpace, -- compute the map to
    projective space associated with the global sections of a Cartier divisor

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

The object KnownCartier, is a symbol (Macaulay2Doc).

KnownDomain -- an option used to specify to certain functions that we know that the ring is a domain
****************************************************************************************************

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

If true, then some functions will not check whether or not the ring is domain,
they will assume it and proceed.

Functions with optional argument named KnownDomain :
====================================================

  * "dualize(...,KnownDomain=>...)" -- see dualize, -- finds an
    ideal or module isomorphic to Hom(M, R)
  * "isReflexive(...,KnownDomain=>...)" -- see isReflexive,
    -- whether an ideal or module is reflexive
  * "reflexify(...,KnownDomain=>...)" -- see reflexify, --
    calculate the double dual of an ideal or module Hom(Hom(M, R), R)
  * "torsionSubmodule(...,KnownDomain=>...)" -- see torsionSubmodule,
    -- create the torsion submodule of a module

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

The object KnownDomain, is a symbol (Macaulay2Doc).

mapToProjectiveSpace -- compute the map to projective space associated with the global sections of a Cartier divisor
********************************************************************************************************************

Synopsis
========

  * Usage:
        mapToProjectiveSpace( D )
  * Inputs:
      * D, an instance of the type WeilDivisor,
  * Optional inputs (Macaulay2Doc),:
      * KnownCartier => a Boolean value (Macaulay2Doc), default
        value true, specify whether the divisor is known to be Cartier
      * Variable => a symbol (Macaulay2Doc), default value "YY"
      * Variable => a string (Macaulay2Doc), default value "YY",
        specify the variable to use in the construction of the target
        projective space
  * Outputs:
      * a ring map (Macaulay2Doc),

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

Given a Cartier divisor $D$ on a projective variety (represented by a divisor
on a normal standard graded ring), this function returns the map to projective
space induced by the global sections of $O(D)$.  If KnownCartier is set to
false (default is true), the function will also check to make sure the divisor
is Cartier away from the irrelevant ideal.

+------------------------------------+
|i1 : R = QQ[x,y,u,v]/ideal(x*y-u*v);|
+------------------------------------+
|i2 : D = divisor( ideal(x, u) )     |
|                                    |
|o2 = Div(x, u)                      |
|                                    |
|o2 : WeilDivisor on R               |
+------------------------------------+
|i3 : mapToProjectiveSpace(D)        |
|                                    |
|o3 = map (R, QQ[YY ..YY ], {v, x})  |
|                  1    2            |
|                                    |
|o3 : RingMap R <--- QQ[YY ..YY ]    |
|                         1    2     |
+------------------------------------+

The user may also specify the variable name of the new projective space.

+-----------------------------------------------------+
|i4 : R = ZZ/7[x,y,z];                                |
+-----------------------------------------------------+
|i5 : D = divisor(x*y)                                |
|                                                     |
|o5 = Div(x) + Div(y)                                 |
|                                                     |
|o5 : WeilDivisor on R                                |
+-----------------------------------------------------+
|i6 : mapToProjectiveSpace(D, Variable=>"Z")          |
|                                                     |
|             ZZ            2             2        2  |
|o6 = map (R, --[Z ..Z ], {x , x*y, x*z, y , y*z, z })|
|              7  1   6                               |
|                                                     |
|                    ZZ                               |
|o6 : RingMap R <--- --[Z ..Z ]                       |
|                     7  1   6                        |
+-----------------------------------------------------+

See also
========

  * isCartier -- whether a Weil divisor is Cartier

Ways to use mapToProjectiveSpace :
==================================

  * "mapToProjectiveSpace(WeilDivisor)"

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

The object mapToProjectiveSpace, is a method function with options (Macaulay2Doc).

MTries -- an option used by embedAsIdeal how many times to try embedding the module as an ideal in a random way.
****************************************************************************************************************

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

After making some canonical attempts, embedAsIdeal tries to embed the module
into a ring as an ideal in a random way.  The value of this option is how many
times that random embedding is attempted.  The default value is 10.

Functions with optional argument named MTries :
===============================================

  * "embedAsIdeal(...,MTries=>...)" -- see embedAsIdeal, --
    embed a module as an ideal of a ring

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

The object MTries, is a symbol (Macaulay2Doc).

nonCartierLocus -- the non-Cartier locus of a Weil divisor
**********************************************************

Synopsis
========

  * Usage:
        nonCartierLocus( D, IsGraded=>b)
  * Inputs:
      * D, an instance of the type WeilDivisor,
  * Optional inputs (Macaulay2Doc),:
      * IsGraded => a Boolean value (Macaulay2Doc), default
        value false, specify that we are computing this locus on a projective
        variety
  * Outputs:
      * an ideal (Macaulay2Doc),

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

This function returns an ideal which vanishes on the locus where D is not
Cartier.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y, u, v]/ideal(x * y  - u * v);                               |
+-----------------------------------------------------------------------------+
|i2 : D = divisor({1, -3, -5, 8}, {ideal(x, u), ideal(y, v), ideal(x, v),     |
|                                                                             |
|o2 = 8*Div(y, u) + Div(x, u) + -3*Div(y, v) + -5*Div(x, v)                   |
|                                                                             |
|o2 : WeilDivisor on R                                                        |
|-----------------------------------------------------------------------------|
|ideal(y, u)})                                                                |
+-----------------------------------------------------------------------------+
|i3 : nonCartierLocus( D )                                                    |
|                                                                             |
|             5     4     4     4   2 3       3       3   2 3   2 3   3 2     |
|o3 = ideal (v , u*v , y*v , x*v , u v , y*u*v , x*u*v , y v , x v , u v ,    |
|     ------------------------------------------------------------------------|
|        2 2     2 2   2   2   2   2   3 2   3 2   4      3      3    2 2     |
|     y*u v , x*u v , y u*v , x u*v , y v , x v , u v, y*u v, x*u v, y u v,   |
|     ------------------------------------------------------------------------|
|      2 2    3      3      4    4    5     4     4   2 3   2 3   3 2   3 2   |
|     x u v, y u*v, x u*v, y v, x v, u , y*u , x*u , y u , x u , y u , x u ,  |
|     ------------------------------------------------------------------------|
|      4    4    5   5                                                        |
|     y u, x u, y , x )                                                       |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

If the option IsGraded is set to true (by default it is false), it saturates
with respect to the homogeneous maximal ideal.

+-----------------------------------------------------------------------------+
|i4 : R = QQ[x, y, u, v]/ideal(x * y  - u * v);                               |
+-----------------------------------------------------------------------------+
|i5 : D = divisor({1, -3, -5, 8}, {ideal(x, u), ideal(y, v), ideal(x, v),     |
|                                                                             |
|o5 = 8*Div(y, u) + Div(x, u) + -3*Div(y, v) + -5*Div(x, v)                   |
|                                                                             |
|o5 : WeilDivisor on R                                                        |
|-----------------------------------------------------------------------------|
|ideal(y, u)})                                                                |
+-----------------------------------------------------------------------------+
|i6 : nonCartierLocus( D, IsGraded => true )                                  |
|                                                                             |
|o6 = ideal 1                                                                 |
|                                                                             |
|o6 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

The output value of this function is stored in the divisor's cache with the
value of the last IsGraded option.  If you change the IsGraded option, the
value will be recomputed.

See also
========

  * isCartier -- whether a Weil divisor is Cartier
  * isQCartier -- whether m times a divisor is Cartier for
    any m from 1 to a fixed positive integer n1.

Ways to use nonCartierLocus :
=============================

  * "nonCartierLocus(WeilDivisor)"

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

The object nonCartierLocus, is a method function with options (Macaulay2Doc).

Number * BasicDivisor -- multiply a divisor by a number
*******************************************************

Synopsis
========

  * Operator: * (Macaulay2Doc),
  * Usage:
        n * D
  * Inputs:
      * n, a number (Macaulay2Doc),
      * D, an instance of the type BasicDivisor,
  * Outputs:
      * an instance of the type BasicDivisor,

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

Multiply a divisor by an integer or a real or rational number.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : D = divisor(x^2*y/(x+y));                                               |
|                                                                             |
|o2 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i3 : E = divisor({1/2, -5/3}, {ideal(x), ideal(y)}, CoefficientType=>QQ)     |
|                                                                             |
|o3 = 1/2*Div(x) + -5/3*Div(y)                                                |
|                                                                             |
|o3 : QWeilDivisor on R                                                       |
+-----------------------------------------------------------------------------+
|i4 : F = divisor({1.5, 0, -3.2}, {ideal(x), ideal(y), ideal(x^2-y^3)},       |
|                                                                             |
|o4 = -3.2*Div(-y^3+x^2) + 1.5*Div(x) + 0*Div(y)                              |
|                                                                             |
|o4 : RWeilDivisor on R                                                       |
|-----------------------------------------------------------------------------|
|CoefficientType=>RR)                                                         |
+-----------------------------------------------------------------------------+
|i5 : 8*D                                                                     |
|                                                                             |
|o5 = -8*Div(x+y) + 8*Div(y) + 16*Div(x)                                      |
|                                                                             |
|o5 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i6 : (-2/3)*D                                                                |
|                                                                             |
|o6 = 2/3*Div(x+y) + -2/3*Div(y) + -4/3*Div(x)                                |
|                                                                             |
|o6 : QWeilDivisor on R                                                       |
+-----------------------------------------------------------------------------+
|i7 : 0.0*D                                                                   |
|                                                                             |
|o7 = 0, the zero divisor                                                     |
|                                                                             |
|o7 : RWeilDivisor on R                                                       |
+-----------------------------------------------------------------------------+
|i8 : (3/2)*E                                                                 |
|                                                                             |
|o8 = 3/4*Div(x) + -5/2*Div(y)                                                |
|                                                                             |
|o8 : QWeilDivisor on R                                                       |
+-----------------------------------------------------------------------------+
|i9 : (-1.414)*E                                                              |
|                                                                             |
|o9 = 2.35667*Div(y) + -.707*Div(x)                                           |
|                                                                             |
|o9 : RWeilDivisor on R                                                       |
+-----------------------------------------------------------------------------+
|i10 : 6*F                                                                    |
|                                                                             |
|o10 = -19.2*Div(-y^3+x^2) + 9*Div(x)                                         |
|                                                                             |
|o10 : RWeilDivisor on R                                                      |
+-----------------------------------------------------------------------------+
|i11 : (-3/2)*F                                                               |
|                                                                             |
|o11 = 4.8*Div(-y^3+x^2) + -2.25*Div(x)                                       |
|                                                                             |
|o11 : RWeilDivisor on R                                                      |
+-----------------------------------------------------------------------------+

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

  * Number * BasicDivisor -- multiply a divisor
    by a number
  * "QQ * RWeilDivisor"
  * "QQ * WeilDivisor"
  * "RR * QWeilDivisor"
  * "RR * RWeilDivisor"

OO RWeilDivisor -- calculate module corresponding to divisor
************************************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        OO( D1 )
  * Inputs:
      * D1, an instance of the type RWeilDivisor,
  * Outputs:
      * a module (Macaulay2Doc),

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

Get the associated module $O(D)$ of a Weil Divisor $D$.  In the affine case,
$O(D)$ is by definition the set of elements $f$ of the fraction field such that
$D + Div(f) \geq 0$.  We represent this as a module.  In the projective case,
$O(D)$ is the coherent sheaf of such elements, and hence we represent it as a
graded module.  For example, consider the following modules on $P^2$.

+---------------------------------+
|i1 : R = ZZ/7[x,y,z];            |
+---------------------------------+
|i2 : D = divisor(x);             |
|                                 |
|o2 : WeilDivisor on R            |
+---------------------------------+
|i3 : OO(D)                       |
|                                 |
|      1                          |
|o3 = R                           |
|                                 |
|o3 : R-module, free, degrees {-1}|
+---------------------------------+
|i4 : OO(2*D)                     |
|                                 |
|      1                          |
|o4 = R                           |
|                                 |
|o4 : R-module, free, degrees {-2}|
+---------------------------------+
|i5 : OO(0*D)                     |
|                                 |
|      1                          |
|o5 = R                           |
|                                 |
|o5 : R-module, free              |
+---------------------------------+
|i6 : OO(-3*D)                    |
|                                 |
|      1                          |
|o6 = R                           |
|                                 |
|o6 : R-module, free, degrees {3} |
+---------------------------------+

Next, consider an example on $P^1 \times P^1$.

+-----------------------------------------------+
|i7 : R = QQ[x, y, u, v] / ideal(x * y - u * v);|
+-----------------------------------------------+
|i8 : D1 = divisor(ideal(x, u))                 |
|                                               |
|o8 = Div(x, u)                                 |
|                                               |
|o8 : WeilDivisor on R                          |
+-----------------------------------------------+
|i9 : D2 = divisor(ideal(x, v))                 |
|                                               |
|o9 = Div(x, v)                                 |
|                                               |
|o9 : WeilDivisor on R                          |
+-----------------------------------------------+
|i10 : OO( D1 )                                 |
|                                               |
|o10 = image {-1} | x v |                       |
|            {-1} | u y |                       |
|                                               |
|                              2                |
|o10 : R-module, submodule of R                 |
+-----------------------------------------------+
|i11 : OO(D1 + D2)                              |
|                                               |
|o11 = image {-2} | x |                         |
|            {-2} | v |                         |
|            {-2} | u |                         |
|            {-2} | y |                         |
|                                               |
|                              4                |
|o11 : R-module, submodule of R                 |
+-----------------------------------------------+

To get the associated module $O(D)$ for a rational/real divisor $D$, we first
obtain a new divisor $D'$ whose coefficients are the floor of the coefficients
of $D$, and take $O(D')$ as $O(D)$.

+-----------------------------------------------------------------------------+
|i12 : R = QQ[x, y, u, v] / ideal(x * y - u * v);                             |
+-----------------------------------------------------------------------------+
|i13 : D2 = divisor({3/5, -4/7, 9/4, -7/8}, {ideal(x, u), ideal(x, v),        |
|                                                                             |
|o13 = -7/8*Div(y, v) + 3/5*Div(x, u) + -4/7*Div(x, v) + 9/4*Div(y, u)        |
|                                                                             |
|o13 : QWeilDivisor on R                                                      |
|-----------------------------------------------------------------------------|
|ideal(y, u), ideal(y, v)}, CoefficientType=>QQ)                              |
+-----------------------------------------------------------------------------+
|i14 : OO( D2 )                                                               |
|                                                                             |
|o14 = image {-1} | y2 yv v2 |                                                |
|            {-1} | u2 xu x2 |                                                |
|                                                                             |
|                              2                                              |
|o14 : R-module, submodule of R                                               |
+-----------------------------------------------------------------------------+
|i15 : OO( floor(D2) )                                                        |
|                                                                             |
|o15 = image {-1} | y2 yv v2 |                                                |
|            {-1} | u2 xu x2 |                                                |
|                                                                             |
|                              2                                              |
|o15 : R-module, submodule of R                                               |
+-----------------------------------------------------------------------------+

Note that you can call the divisor constructor on the module you construct, but
it will only produce a divisor up to linear equivalence (which can mean
different things depending on whether or not you are keeping track of the
grading).

+------------------------------------+
|i16 : R = ZZ/11[x,y];               |
+------------------------------------+
|i17 : D = divisor(x*y/(x+y))        |
|                                    |
|o17 = -Div(x+y) + Div(x) + Div(y)   |
|                                    |
|o17 : WeilDivisor on R              |
+------------------------------------+
|i18 : divisor(OO(D))                |
|                                    |
|o18 = 0, the zero divisor           |
|                                    |
|o18 : WeilDivisor on R              |
+------------------------------------+
|i19 : divisor(OO(D), IsGraded=>true)|
|                                    |
|o19 = Div(x)                        |
|                                    |
|o19 : WeilDivisor on R              |
+------------------------------------+

The output value of this function is stored in the divisor's cache.

See also
========

  * ideal(RWeilDivisor) -- calculate the
    corresponding module of a divisor and represent it as an ideal

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

  * OO RWeilDivisor -- calculate module corresponding
    to divisor

positivePart -- get the effective part or anti-effective part of a divisor
**************************************************************************

Synopsis
========

  * Usage:
        positivePart( F1 )
        negativePart( F1 )
  * Inputs:
      * F1, an instance of the type RWeilDivisor,
  * Outputs:
      * an instance of the type RWeilDivisor, an effective
        divisor

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

This function returns the positive part of a divisor

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x, y, u, v] / ideal(x * y - u * v);                              |
+-----------------------------------------------------------------------------+
|i2 : D = divisor({1, -2, 3, -4}, {ideal(x, u), ideal(y, u), ideal(x, v),     |
|                                                                             |
|o2 = -4*Div(y, v) + Div(x, u) + -2*Div(y, u) + 3*Div(x, v)                   |
|                                                                             |
|o2 : WeilDivisor on R                                                        |
|-----------------------------------------------------------------------------|
|ideal(y, v)})                                                                |
+-----------------------------------------------------------------------------+
|i3 : positivePart( D )                                                       |
|                                                                             |
|o3 = Div(x, u) + 3*Div(x, v)                                                 |
|                                                                             |
|o3 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i4 : negativePart( D )                                                       |
|                                                                             |
|o4 = 2*Div(y, u) + 4*Div(y, v)                                               |
|                                                                             |
|o4 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i5 : D == positivePart(D) - negativePart(D)                                  |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+
|i6 : E = divisor({0, 1}, {ideal(x,u), ideal(y,u)})                           |
|                                                                             |
|o6 = 0*Div(x, u) + Div(y, u)                                                 |
|                                                                             |
|o6 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i7 : positivePart(E)                                                         |
|                                                                             |
|o7 = Div(y, u)                                                               |
|                                                                             |
|o7 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i8 : negativePart(E)                                                         |
|                                                                             |
|o8 = 0, the zero divisor                                                     |
|                                                                             |
|o8 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i9 : E == positivePart(E) - negativePart(E)                                  |
|                                                                             |
|o9 = true                                                                    |
+-----------------------------------------------------------------------------+

Ways to use positivePart :
==========================

  * "positivePart(RWeilDivisor)"

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

The object positivePart, is a method function (Macaulay2Doc).

Primes -- a value for the option Strategy for the pullback method
*****************************************************************

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

If Strategy=>Primes then the pullback method will pull back each prime
individually.

See also
========

  * pullback -- pullback a divisor under a ring map
  * Sheaves -- a value for the option Strategy for the pullback
    method

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

The object Primes, is a symbol (Macaulay2Doc).

primes -- get the list of height-one primes in the support of a divisor
***********************************************************************

Synopsis
========

  * Usage:
        primes( D1 )
  * Inputs:
      * D1, an instance of the type BasicDivisor,
  * Outputs:
      * a list (Macaulay2Doc),

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

This function returns the list of height-one prime ideals corresponding to the
components of a BasicDivisor.  Note that if you don't call cleanSupport, this
can return primes with coefficient equal to zero.

+-----------------------------------------------+
|i1 : R = QQ[x,y,u,v]/ideal(x*y-u*v);           |
+-----------------------------------------------+
|i2 : D = divisor(x)                            |
|                                               |
|o2 = Div(v, x) + Div(u, x)                     |
|                                               |
|o2 : WeilDivisor on R                          |
+-----------------------------------------------+
|i3 : primes(D)                                 |
|                                               |
|o3 = {ideal (v, x), ideal (u, x)}              |
|                                               |
|o3 : List                                      |
+-----------------------------------------------+
|i4 : E = divisor(x*u)                          |
|                                               |
|o4 = Div(v, x) + Div(u, y) + 2*Div(u, x)       |
|                                               |
|o4 : WeilDivisor on R                          |
+-----------------------------------------------+
|i5 : primes(E)                                 |
|                                               |
|o5 = {ideal (v, x), ideal (u, y), ideal (u, x)}|
|                                               |
|o5 : List                                      |
+-----------------------------------------------+
|i6 : F = divisor({0}, {ideal(x,u)})            |
|                                               |
|o6 = 0*Div(x, u)                               |
|                                               |
|o6 : WeilDivisor on R                          |
+-----------------------------------------------+
|i7 : primes(F)                                 |
|                                               |
|o7 = {ideal (x, u)}                            |
|                                               |
|o7 : List                                      |
+-----------------------------------------------+
|i8 : primes(cleanSupport F)                    |
|                                               |
|o8 = {}                                        |
|                                               |
|o8 : List                                      |
+-----------------------------------------------+
|i9 : primes(1*F)                               |
|                                               |
|o9 = {}                                        |
|                                               |
|o9 : List                                      |
+-----------------------------------------------+

See also
========

  * coefficients(BasicDivisor) -- get
    the list of coefficients of a divisor
  * gbs -- get the list of Groebner bases corresponding to the
    height-one primes in the support of a divisor

Ways to use primes :
====================

  * "primes(BasicDivisor)"

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

The object primes, is a method function (Macaulay2Doc).

pullback -- pullback a divisor under a ring map
***********************************************

Synopsis
========

  * Usage:
        pullback(f, D1)
  * Inputs:
      * f, a ring map (Macaulay2Doc),
      * D1, an instance of the type RWeilDivisor,
  * Optional inputs (Macaulay2Doc),:
      * Strategy => a symbol (Macaulay2Doc), default value
        Primes, specify the strategy used by pullback
  * Outputs:
      * an instance of the type RWeilDivisor,

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

This function computes the pullback of a divisor under a ring map.  There are
two potential strategies, Primes and Sheaves (Primes is the default strategy).
The Primes strategy pulls back each prime individually.  It can be faster, but
it only works for ring maps that are either finite or flat (unless each prime
is also Cartier).  For more general maps, it can give incorrect results.  The
other option for Strategy is Sheaves.  This can be slower, especially for
divisors with large coefficients, but it will successfully pull back any
Cartier divisor.  The option Sheaves also requires the divisor passed to be a
WeilDivisor.

+----------------------------------------------------+
|i1 : R = QQ[x,y,z,w]/ideal(z^2-y*w,y*z-x*w,y^2-x*z);|
+----------------------------------------------------+
|i2 : T = QQ[a,b];                                   |
+----------------------------------------------------+
|i3 : f = map(T, R, {a^3, a^2*b, a*b^2, b^3});       |
|                                                    |
|o3 : RingMap T <--- R                               |
+----------------------------------------------------+
|i4 : D = divisor(y*z)                               |
|                                                    |
|o4 = 3*Div(w, z, y) + 3*Div(z, y, x)                |
|                                                    |
|o4 : WeilDivisor on R                               |
+----------------------------------------------------+
|i5 : pullback(f, D, Strategy=>Primes)               |
|                                                    |
|o5 = 3*Div(b) + 3*Div(a)                            |
|                                                    |
|o5 : WeilDivisor on T                               |
+----------------------------------------------------+
|i6 : pullback(f, D, Strategy=>Sheaves)              |
|                                                    |
|o6 = 3*Div(b) + 3*Div(a)                            |
|                                                    |
|o6 : WeilDivisor on T                               |
+----------------------------------------------------+

Let us also consider pulling back a divisor under a blowup map.

+----------------------------------+
|i7 : R = QQ[x,y];                 |
+----------------------------------+
|i8 : S = QQ[a,b];                 |
+----------------------------------+
|i9 : f = map(S, R, {a*b, b});     |
|                                  |
|o9 : RingMap S <--- R             |
+----------------------------------+
|i10 : D = divisor(x*y*(x+y));     |
|                                  |
|o10 : WeilDivisor on R            |
+----------------------------------+
|i11 : D1 = pullback(f, D)         |
|                                  |
|o11 = Div(a) + 3*Div(b) + Div(a+1)|
|                                  |
|o11 : WeilDivisor on S            |
+----------------------------------+
|i12 : f^* D                       |
|                                  |
|o12 = Div(a) + 3*Div(b) + Div(a+1)|
|                                  |
|o12 : WeilDivisor on S            |
+----------------------------------+

As illustrated by the previous example, the same functionality can also be
accomplished by f^* (which creates a function which sends a divisor $D$ to $f^*
D$).

See also
========

  * Primes -- a value for the option Strategy for the pullback
    method
  * Sheaves -- a value for the option Strategy for the pullback
    method

Ways to use pullback :
======================

  * "pullback(RingMap,RWeilDivisor)"

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

The object pullback, is a method function with options (Macaulay2Doc).

ramificationDivisor -- compute the ramification divisor of a finite inclusion of normal domains or a blowup over a smooth base
******************************************************************************************************************************

Synopsis
========

  * Usage:
        ramficationDivisor( f )
  * Inputs:
      * f, a ring map (Macaulay2Doc),
      * b, a Boolean value (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * IsGraded => a Boolean value (Macaulay2Doc), default
        value false, specify true to compute the relative canonical divisor of
        blowup over a smooth base
  * Outputs:
      * an instance of the type WeilDivisor,

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

Compute the ramification (relative canonical) divisor corresponding the finite
inclusion of normal domains.  If you pass it a non-finite map, it will compute
the divisorial part of the locus where the map is not smooth.  If IsGraded is
set to false (the default value), then the coefficient ring of both the source
and target of $f$ must be equal.

+---------------------------+
|i1 : R = QQ[x];            |
+---------------------------+
|i2 : S = QQ[y];            |
+---------------------------+
|i3 : f = map(S, R, {y^3}); |
|                           |
|o3 : RingMap S <--- R      |
+---------------------------+
|i4 : ramificationDivisor(f)|
|                           |
|o4 = 2*Div(y)              |
|                           |
|o4 : WeilDivisor on S      |
+---------------------------+

The next example is a Veronese which is etale in codimension 1.

+---------------------------------------------+
|i5 : R = QQ[x,y];                            |
+---------------------------------------------+
|i6 : T = QQ[a,b,c,d];                        |
+---------------------------------------------+
|i7 : h = map(R, T, {x^3, x^2*y, x*y^2, y^3});|
|                                             |
|o7 : RingMap R <--- T                        |
+---------------------------------------------+
|i8 : S = T/ker h;                            |
+---------------------------------------------+
|i9 : f = map(R, S, {x^3, x^2*y, x*y^2, y^3});|
|                                             |
|o9 : RingMap R <--- S                        |
+---------------------------------------------+
|i10 : ramificationDivisor(f)                 |
|                                             |
|o10 = 0, the zero divisor                    |
|                                             |
|o10 : WeilDivisor on R                       |
+---------------------------------------------+

Here is an example with wild ramification.

+---------------------------------+
|i11 : R = ZZ/2[t];               |
+---------------------------------+
|i12 : S = ZZ/2[x];               |
+---------------------------------+
|i13 : f = map(S, R, {x^2*(1+x)});|
|                                 |
|o13 : RingMap S <--- R           |
+---------------------------------+
|i14 : ramificationDivisor(f)     |
|                                 |
|o14 = 2*Div(x)                   |
|                                 |
|o14 : WeilDivisor on S           |
+---------------------------------+

If the option IsGraded is set to true, then the function will assume that the
source of f is affine, and the target is projective over the source.  In this
case, the coefficient ring of the target must be equal to the source ring.
This can be useful when computing things like relative canonical divisors over
regular bases (it may not give the expected answer over non-regular bases).
For example, this is useful if you want to compute the relative canonical
divisor of a blowup.

+-------------------------------------------+
|i15 : R = QQ[x,y];                         |
+-------------------------------------------+
|i16 : S = reesAlgebra(ideal(x,y^2));       |
+-------------------------------------------+
|i17 : f = map(S, R);                       |
|                                           |
|o17 : RingMap S <--- R                     |
+-------------------------------------------+
|i18 : ramificationDivisor(f,IsGraded=>true)|
|                                           |
|o18 = 2*Div(y, x)                          |
|                                           |
|o18 : WeilDivisor on S                     |
+-------------------------------------------+

See also
========

  * canonicalDivisor -- compute a canonical divisor of
    a ring

Ways to use ramificationDivisor :
=================================

  * "ramificationDivisor(RingMap)"

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

The object ramificationDivisor, is a method function with options (Macaulay2Doc).

reflexify -- calculate the double dual of an ideal or module Hom(Hom(M, R), R)
******************************************************************************

Synopsis
========

  * Usage:
        reflexify( I1 )
        reflexify( M1 )
  * Inputs:
      * I1, an ideal (Macaulay2Doc),
      * M1, a module (Macaulay2Doc),
      * b, a Boolean value (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Strategy => a symbol (Macaulay2Doc), default value
        NoStrategy, specify a strategy for reflexify
      * ReturnMap => a Boolean value (Macaulay2Doc), default
        value false, tell reflexify to return a map from the original module to
        the reflexification
      * KnownDomain => a Boolean value (Macaulay2Doc), default
        value true, make reflexify more efficient if the ambient ring is a
        domain
  * Outputs:
      * an ideal (Macaulay2Doc),
      * a module (Macaulay2Doc),

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

Get the reflexification or double dual (in the case of a normal ring,
S2-ification) of an ideal $I$ or module $M$. Recall the double dual is defined
to be $Hom(Hom(M, R), R)$.

+----------------------------------+
|i1 : R = QQ[x,y,z]/ideal(x^2-y*z);|
+----------------------------------+
|i2 : m = ideal(x,y,z);            |
|                                  |
|o2 : Ideal of R                   |
+----------------------------------+
|i3 : reflexify(m)                 |
|                                  |
|o3 = ideal 1                      |
|                                  |
|o3 : Ideal of R                   |
+----------------------------------+
|i4 : I = ideal(x,y);              |
|                                  |
|o4 : Ideal of R                   |
+----------------------------------+
|i5 : reflexify(I)                 |
|                                  |
|o5 = ideal (y, x)                 |
|                                  |
|o5 : Ideal of R                   |
+----------------------------------+
|i6 : reflexify(I^2)               |
|                                  |
|o6 = ideal y                      |
|                                  |
|o6 : Ideal of R                   |
+----------------------------------+
|i7 : reflexify(I^3)               |
|                                  |
|             2                    |
|o7 = ideal (y , x*y)              |
|                                  |
|o7 : Ideal of R                   |
+----------------------------------+

We also have an example of reflexifying a module.

+----------------------------------+
|i8 : R = QQ[x,y,z]/ideal(x^2-y*z);|
+----------------------------------+
|i9 : m = ideal(x,y,z);            |
|                                  |
|o9 : Ideal of R                   |
+----------------------------------+
|i10 : prune reflexify(m*R^2)      |
|                                  |
|       2                          |
|o10 = R                           |
|                                  |
|o10 : R-module, free              |
+----------------------------------+
|i11 : I = ideal(x,y);             |
|                                  |
|o11 : Ideal of R                  |
+----------------------------------+
|i12 : prune reflexify(I*R^1)      |
|                                  |
|o12 = cokernel {1} | x  -y |      |
|               {1} | -z x  |      |
|                                  |
|                             2    |
|o12 : R-module, quotient of R     |
+----------------------------------+
|i13 : prune reflexify(I^2*R^1)    |
|                                  |
|       1                          |
|o13 = R                           |
|                                  |
|o13 : R-module, free, degrees {1} |
+----------------------------------+

There is a canonical map from a module $M$ to its reflexification, $Hom(Hom(M,
R), R)$.  If reflexify is passed the option ReturnMap => true, then instead of
returning a module, reflexify returns that map.  This is not necessary for
ideals since an ideal is canonically a subsetset of its reflexification.

+-------------------------------------------+
|i14 : R = QQ[x,y];                         |
+-------------------------------------------+
|i15 : m = ideal(x,y);                      |
|                                           |
|o15 : Ideal of R                           |
+-------------------------------------------+
|i16 : M = m*R^1;                           |
+-------------------------------------------+
|i17 : f = reflexify( M, ReturnMap => true )|
|                                           |
|o17 = | x y |                              |
|                                           |
|o17 : Matrix                               |
+-------------------------------------------+
|i18 : source f                             |
|                                           |
|o18 = image | x y |                        |
|                                           |
|                              1            |
|o18 : R-module, submodule of R             |
+-------------------------------------------+
|i19 : target f                             |
|                                           |
|       1                                   |
|o19 = R                                    |
|                                           |
|o19 : R-module, free                       |
+-------------------------------------------+

Generally speaking, it is faster to reflexify ideals as opposed to modules.
Consider the following example of a point on an elliptic curve.

+-----------------------------------------------------------+
|i20 : R = QQ[x,y,z]/ideal(-y^2*z +x^3 + x^2*z + x*z^2+z^3);|
+-----------------------------------------------------------+
|i21 : I = ideal(x-z,y-2*z);                                |
|                                                           |
|o21 : Ideal of R                                           |
+-----------------------------------------------------------+
|i22 : J = I^21;                                            |
|                                                           |
|o22 : Ideal of R                                           |
+-----------------------------------------------------------+
|i23 : time reflexify(J);                                   |
|     -- used 0.215135 seconds                              |
|                                                           |
|o23 : Ideal of R                                           |
+-----------------------------------------------------------+
|i24 : time reflexify(J*R^1);                               |
|     -- used 0.491292 seconds                              |
+-----------------------------------------------------------+

Because of this, there are two strategies for computing a reflexification (at
least if the module embeds as an ideal).

IdealStrategy.  In the case that $R$ is a domain, and our module is isomorphic
to an ideal $I$, then one can compute the reflexification by computing colons.

ModuleStrategy.  This computes the reflexification simply by computing $Hom$
twice.

ModuleStrategy is the default strategy for modules, IdealStrategy is the
default strategy for ideals.  In our experience, IdealStrategy is faster on
average.  Note that calling ModuleStrategy for ideals or IdealStrategy for
modules creates overhead which can slow things down substantially (since we
must embed various modules as ideals).

+---------------------------------------------------------+
|i25 : R = ZZ/13[x,y,z]/ideal(x^3 + y^3-z^11*x*y);        |
+---------------------------------------------------------+
|i26 : I = ideal(x-4*y, z);                               |
|                                                         |
|o26 : Ideal of R                                         |
+---------------------------------------------------------+
|i27 : J = I^20;                                          |
|                                                         |
|o27 : Ideal of R                                         |
+---------------------------------------------------------+
|i28 : M = J*R^1;                                         |
+---------------------------------------------------------+
|i29 : J1 = time reflexify( J, Strategy=>IdealStrategy )  |
|     -- used 0.0655063 seconds                           |
|                                                         |
|              2            2     9       9   11          |
|o29 = ideal (x  + 5x*y + 3y , x*z  - 4y*z , z   + x - 4y)|
|                                                         |
|o29 : Ideal of R                                         |
+---------------------------------------------------------+
|i30 : J2 = time reflexify( J, Strategy=>ModuleStrategy ) |
|     -- used 5.46202 seconds                             |
|                                                         |
|              2            2     9       9   11          |
|o30 = ideal (x  + 5x*y + 3y , x*z  - 4y*z , z   + x - 4y)|
|                                                         |
|o30 : Ideal of R                                         |
+---------------------------------------------------------+
|i31 : J1 == J2                                           |
|                                                         |
|o31 = true                                               |
+---------------------------------------------------------+
|i32 : time reflexify( M, Strategy=>IdealStrategy );      |
|     -- used 5.78042 seconds                             |
+---------------------------------------------------------+
|i33 : time reflexify( M, Strategy=>ModuleStrategy );     |
|     -- used 0.397599 seconds                            |
+---------------------------------------------------------+

However, sometimes ModuleStrategy is faster, especially for Monomial ideals.

+-----------------------------------------------------------------------------+
|i34 : R = QQ[x,y,u,v]/ideal(x*y-u*v);                                        |
+-----------------------------------------------------------------------------+
|i35 : I = ideal(x,u);                                                        |
|                                                                             |
|o35 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i36 : J = I^20;                                                              |
|                                                                             |
|o36 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i37 : M = I^20*R^1;                                                          |
+-----------------------------------------------------------------------------+
|i38 : time reflexify( J, Strategy=>IdealStrategy )                           |
|     -- used 0.174993 seconds                                                |
|                                                                             |
|              20     19   2 18   3 17   4 16   5 15   6 14   7 13   8 12     |
|o38 = ideal (u  , x*u  , x u  , x u  , x u  , x u  , x u  , x u  , x u  ,    |
|      -----------------------------------------------------------------------|
|       9 11   10 10   11 9   12 8   13 7   14 6   15 5   16 4   17 3   18 2  |
|      x u  , x  u  , x  u , x  u , x  u , x  u , x  u , x  u , x  u , x  u , |
|      -----------------------------------------------------------------------|
|       19    20                                                              |
|      x  u, x  )                                                             |
|                                                                             |
|o38 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i39 : time reflexify( J, Strategy=>ModuleStrategy )                          |
|     -- used 0.0412416 seconds                                               |
|                                                                             |
|              20     19   2 18   3 17   4 16   5 15   6 14   7 13   8 12     |
|o39 = ideal (u  , x*u  , x u  , x u  , x u  , x u  , x u  , x u  , x u  ,    |
|      -----------------------------------------------------------------------|
|       9 11   10 10   11 9   12 8   13 7   14 6   15 5   16 4   17 3   18 2  |
|      x u  , x  u  , x  u , x  u , x  u , x  u , x  u , x  u , x  u , x  u , |
|      -----------------------------------------------------------------------|
|       19    20                                                              |
|      x  u, x  )                                                             |
|                                                                             |
|o39 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i40 : time reflexify( M, Strategy=>IdealStrategy );                          |
|     -- used 0.0408997 seconds                                               |
+-----------------------------------------------------------------------------+
|i41 : time reflexify( M, Strategy=>ModuleStrategy );                         |
|     -- used 0.00674874 seconds                                              |
+-----------------------------------------------------------------------------+

For ideals, if KnownDomain is false (default value is true), then the function
will check whether it is a domain.  If it is a domain (or assumed to be a
domain), it will reflexify using a strategy which can speed up computation, if
not it will compute using a sometimes slower method which is essentially
reflexifying it as a module.

Consider the following example showing the importance of making the correct
assumption about the ring being a domain.

+--------------------------------------+
|i42 : R = QQ[x,y]/ideal(x*y);         |
+--------------------------------------+
|i43 : I = ideal(x,y);                 |
|                                      |
|o43 : Ideal of R                      |
+--------------------------------------+
|i44 : reflexify(I, KnownDomain=>false)|
|                                      |
|o44 = ideal (y, x)                    |
|                                      |
|o44 : Ideal of R                      |
+--------------------------------------+
|i45 : reflexify(I, KnownDomain=>true) |
|                                      |
|o45 = ideal 1                         |
|                                      |
|o45 : Ideal of R                      |
+--------------------------------------+
|i46 : J = ideal(x-y, x+y);            |
|                                      |
|o46 : Ideal of R                      |
+--------------------------------------+
|i47 : reflexify(J, KnownDomain=>false)|
|                                      |
|o47 = ideal (y, x)                    |
|                                      |
|o47 : Ideal of R                      |
+--------------------------------------+
|i48 : reflexify(I, KnownDomain=>true) |
|                                      |
|o48 = ideal 1                         |
|                                      |
|o48 : Ideal of R                      |
+--------------------------------------+

In the above, when KnownDomain=>true (an incorrect assumption), this function
returns the incorrect answer for $I$.

See also
========

  * isReflexive -- whether an ideal or module is reflexive
  * dualize -- finds an ideal or module isomorphic to Hom(M, R)

Ways to use reflexify :
=======================

  * "reflexify(Ideal)"
  * "reflexify(Module)"

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

The object reflexify, is a method function with options (Macaulay2Doc).

reflexivePower -- computes a reflexive power of an ideal in a normal domain
***************************************************************************

Synopsis
========

  * Usage:
        reflexivePower( n, I )
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Strategy => a symbol (Macaulay2Doc), default value
        IdealStrategy, specify the strategy passed to reflexify
  * Outputs:
      * an ideal (Macaulay2Doc),

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

This function returns the $n$-th reflexive power of $I$.  By definition this is
the reflexification of $I^n$, or in other words, $Hom(Hom(I^n, R), R)$.

+----------------------------------+
|i1 : R = QQ[x,y,z]/ideal(x^2-y*z);|
+----------------------------------+
|i2 : J = ideal(x,y);              |
|                                  |
|o2 : Ideal of R                   |
+----------------------------------+
|i3 : reflexivePower(5, J)         |
|                                  |
|             3     2              |
|o3 = ideal (y , x*y )             |
|                                  |
|o3 : Ideal of R                   |
+----------------------------------+
|i4 : reflexivePower(6, J)         |
|                                  |
|            3                     |
|o4 = ideal y                      |
|                                  |
|o4 : Ideal of R                   |
+----------------------------------+

This function is typically much faster than reflexifying $I^n$ however.  We can
obtain this speedup, because in a normal domain, the reflexification of $I^n$
is the same as the reflexification of the ideal generated by the $n$-th powers
of the generators of $I$.  Consider the example of a cone over a point on an
elliptic curve.

+----------------------------------------------------------+
|i5 : R = QQ[x,y,z]/ideal(-y^2*z +x^3 + x^2*z + x*z^2+z^3);|
+----------------------------------------------------------+
|i6 : I = ideal(x-z,y-2*z);                                |
|                                                          |
|o6 : Ideal of R                                           |
+----------------------------------------------------------+
|i7 : time J20a = reflexivePower(20, I);                   |
|     -- used 0.0383985 seconds                            |
|                                                          |
|o7 : Ideal of R                                           |
+----------------------------------------------------------+
|i8 : I20 = I^20;                                          |
|                                                          |
|o8 : Ideal of R                                           |
+----------------------------------------------------------+
|i9 : time J20b = reflexify(I20);                          |
|     -- used 0.166702 seconds                             |
|                                                          |
|o9 : Ideal of R                                           |
+----------------------------------------------------------+
|i10 : J20a == J20b                                        |
|                                                          |
|o10 = true                                                |
+----------------------------------------------------------+

This passes the Strategy option to a reflexify call.  Valid options are
IdealStrategy and ModuleStrategy.

+----------------------------------------------------------------+
|i11 : R = QQ[x,y,z]/ideal(-y^2*z +x^3 + x^2*z + x*z^2+z^3);     |
+----------------------------------------------------------------+
|i12 : I = ideal(x-z,y-2*z);                                     |
|                                                                |
|o12 : Ideal of R                                                |
+----------------------------------------------------------------+
|i13 : time J1 = reflexivePower(20, I, Strategy=>IdealStrategy); |
|     -- used 0.039811 seconds                                   |
|                                                                |
|o13 : Ideal of R                                                |
+----------------------------------------------------------------+
|i14 : time J2 = reflexivePower(20, I, Strategy=>ModuleStrategy);|
|     -- used 0.109467 seconds                                   |
|                                                                |
|o14 : Ideal of R                                                |
+----------------------------------------------------------------+
|i15 : J1 == J2                                                  |
|                                                                |
|o15 = true                                                      |
+----------------------------------------------------------------+

See also
========

  * reflexify -- calculate the double dual of an ideal or
    module Hom(Hom(M, R), R)
  * isReflexive -- whether an ideal or module is reflexive

Ways to use reflexivePower :
============================

  * "reflexivePower(ZZ,Ideal)"

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

The object reflexivePower, is a method function with options (Macaulay2Doc).

ReturnMap -- an option for embedAsIdeal
***************************************

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

If ReturnMap is set to true, then instead of embedAsIdeal converting a module
into an isomorphic ideal, this also returns the map from the module to the
ring.

See also
========

  * embedAsIdeal -- embed a module as an ideal of a ring

Functions with optional argument named ReturnMap :
==================================================

  * "embedAsIdeal(...,ReturnMap=>...)" -- see embedAsIdeal,
    -- embed a module as an ideal of a ring
  * "reflexify(...,ReturnMap=>...)" -- see reflexify, --
    calculate the double dual of an ideal or module Hom(Hom(M, R), R)

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

The object ReturnMap, is a symbol (Macaulay2Doc).

ring(BasicDivisor) -- get the ambient ring of a divisor
*******************************************************

Synopsis
========

  * Function: ring (Macaulay2Doc),
  * Usage:
        ring( D1 )
  * Inputs:
      * D1, an instance of the type BasicDivisor,
  * Outputs:
      * a ring (Macaulay2Doc),

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

This function returns the ambient ring of a divisor.

+----------------------------------------------------+
|i1 : R = QQ[x, y, z] / ideal(x * y - z^2 );         |
+----------------------------------------------------+
|i2 : D = divisor({1, 2}, {ideal(x, z), ideal(y, z)})|
|                                                    |
|o2 = Div(x, z) + 2*Div(y, z)                        |
|                                                    |
|o2 : WeilDivisor on R                               |
+----------------------------------------------------+
|i3 : ring( D )                                      |
|                                                    |
|o3 = R                                              |
|                                                    |
|o3 : QuotientRing                                   |
+----------------------------------------------------+

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

  * ring(BasicDivisor) -- get the ambient ring
    of a divisor

RWeilDivisor == RWeilDivisor -- whether two divisors are equal
**************************************************************

Synopsis
========

  * Operator: == (Macaulay2Doc),
  * Usage:
        (D == E)
  * Inputs:
      * D, an instance of the type RWeilDivisor,
      * E, an instance of the type RWeilDivisor,
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function returns true if the two divisors are equal

+----------------------+
|i1 : R = QQ[x,y];     |
+----------------------+
|i2 : D = divisor(x*y);|
|                      |
|o2 : WeilDivisor on R |
+----------------------+
|i3 : E = divisor(x);  |
|                      |
|o3 : WeilDivisor on R |
+----------------------+
|i4 : F = divisor(y);  |
|                      |
|o4 : WeilDivisor on R |
+----------------------+
|i5 : D == E           |
|                      |
|o5 = false            |
+----------------------+
|i6 : D == E+F         |
|                      |
|o6 = true             |
+----------------------+

Here is an example with rational coefficients compared with integer
coefficients.

+-------------------------+
|i7 : R = QQ[x,y];        |
+-------------------------+
|i8 : D = (1/2)*divisor(x)|
|                         |
|o8 = 1/2*Div(x)          |
|                         |
|o8 : QWeilDivisor on R   |
+-------------------------+
|i9 : D == 2*D            |
|                         |
|o9 = false               |
+-------------------------+
|i10 : D + D == 2*D       |
|                         |
|o10 = true               |
+-------------------------+
|i11 : E = divisor(x)     |
|                         |
|o11 = Div(x)             |
|                         |
|o11 : WeilDivisor on R   |
+-------------------------+
|i12 : D == E             |
|                         |
|o12 = false              |
+-------------------------+
|i13 : 2*D == E           |
|                         |
|o13 = true               |
+-------------------------+

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

  * RWeilDivisor == RWeilDivisor, --
    whether two divisors are equal

Safe -- an option used to tell functions whether not to do checks.
******************************************************************

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

If set to true, then certain functions will perform checks to make sure the
user didn't pass something unreasonable.  You can use isWellDefined to ensure
that a constructed divisor is constructed correctly.

See also
========

  * isWellDefined (Macaulay2Doc) -- whether a map is well
    defined

Functions with optional argument named Safe :
=============================================

  * "applyToCoefficients(...,Safe=>...)" -- see applyToCoefficients,
    -- apply a function to the coefficients of a divisor
  * "getLinearDiophantineSolution(...,Safe=>...)" -- see
    getLinearDiophantineSolution, -- find a
    solution of the linear Diophantine equation Ax = b

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

The object Safe, is a symbol (Macaulay2Doc).

Section -- an option used in a number of functions
**************************************************

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

Used to specify a (global) section of an ideal or module, in order to construct
an effective divisor.

Functions with optional argument named Section :
================================================

  * "divisor(...,Section=>...)" -- see divisor, -- constructor
    for (Weil/Q/R)-divisors
  * "embedAsIdeal(...,Section=>...)" -- see embedAsIdeal,
    -- embed a module as an ideal of a ring

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

The object Section, is a symbol (Macaulay2Doc).

Sheaves -- a value for the option Strategy for the pullback method
******************************************************************

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

If Strategy => Sheaves then the pullback method will pull back the sheaf
$O(D)$.

See also
========

  * pullback -- pullback a divisor under a ring map
  * Primes -- a value for the option Strategy for the pullback
    method

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

The object Sheaves, is a symbol (Macaulay2Doc).

toQWeilDivisor -- create a Q-Weil divisor from a Weil divisor
*************************************************************

Synopsis
========

  * Usage:
        toQWeilDivisor( D )
  * Inputs:
      * D, an instance of the type QWeilDivisor,
  * Outputs:
      * an instance of the type QWeilDivisor,

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

Turn a Weil divisor into a Q-divisor (or do nothing to a Q-divisor).

+--------------------------------------------------------------+
|i1 : R = ZZ/5[x, y];                                          |
+--------------------------------------------------------------+
|i2 : D = divisor(x);                                          |
|                                                              |
|o2 : WeilDivisor on R                                         |
+--------------------------------------------------------------+
|i3 : E = toQWeilDivisor(D)                                    |
|                                                              |
|o3 = Div(x)                                                   |
|                                                              |
|o3 : QWeilDivisor on R                                        |
+--------------------------------------------------------------+
|i4 : toQWeilDivisor(E)                                        |
|                                                              |
|o4 = Div(x)                                                   |
|                                                              |
|o4 : QWeilDivisor on R                                        |
+--------------------------------------------------------------+
|i5 : F = divisor({3, 0, -2}, {ideal(x), ideal(y), ideal(x+y)})|
|                                                              |
|o5 = 3*Div(x) + 0*Div(y) + -2*Div(x+y)                        |
|                                                              |
|o5 : WeilDivisor on R                                         |
+--------------------------------------------------------------+

See also
========

  * toWeilDivisor -- create a Weil divisor from a Q or
    R-divisor
  * toRWeilDivisor -- create a R-divisor from a Q or
    Weil divisor

Ways to use toQWeilDivisor :
============================

  * "toQWeilDivisor(QWeilDivisor)"
  * "toQWeilDivisor(WeilDivisor)"

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

The object toQWeilDivisor, is a method function (Macaulay2Doc).

torsionSubmodule -- create the torsion submodule of a module
************************************************************

Synopsis
========

  * Usage:
        torsionSubmodule( M1 )
  * Inputs:
      * M1, a module (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Strategy => a symbol (Macaulay2Doc), default value
        NoStrategy, specify a strategy for the internal call to reflexify
      * KnownDomain => a Boolean value (Macaulay2Doc), default
        value false, assume the ambient ring is a domain for the internal call
        to reflexify
  * Outputs:
      * a module (Macaulay2Doc),

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

Finds the torsion submodule of a module.  It does this by computing the kernel
of the map from M1 to its reflexification.  The options Strategy and
KnownDomain are passed along when the function reflexify is called.

+-----------------------------+
|i1 : R = QQ[x,y];            |
+-----------------------------+
|i2 : m = ideal(x,y);         |
|                             |
|o2 : Ideal of R              |
+-----------------------------+
|i3 : M = (R^1/m) ++ R^1      |
|                             |
|o3 = cokernel | x y |        |
|              | 0 0 |        |
|                             |
|                            2|
|o3 : R-module, quotient of R |
+-----------------------------+
|i4 : prune torsionSubmodule M|
|                             |
|o4 = cokernel | y x |        |
|                             |
|                            1|
|o4 : R-module, quotient of R |
+-----------------------------+

See also
========

  * reflexify -- calculate the double dual of an ideal or
    module Hom(Hom(M, R), R)

Ways to use torsionSubmodule :
==============================

  * "torsionSubmodule(Module)"

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

The object torsionSubmodule, is a method function with options (Macaulay2Doc).

toRWeilDivisor -- create a R-divisor from a Q or Weil divisor
*************************************************************

Synopsis
========

  * Usage:
        toRWeilDivisor( D1 )
        toRWeilDivisor( E1 )
  * Inputs:
      * D1, an instance of the type WeilDivisor,
      * E1, an instance of the type QWeilDivisor,
      * E1, an instance of the type RWeilDivisor,
  * Outputs:
      * an instance of the type RWeilDivisor,

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

Turn a Weil divisor or a Q-divisor into a R-divisor (or do nothing to a
R-divisor).

+--------------------------------------------------------------+
|i1 : R = ZZ/5[x,y];                                           |
+--------------------------------------------------------------+
|i2 : D = divisor({2, 0, -4}, {ideal(x), ideal(y), ideal(x-y)})|
|                                                              |
|o2 = 2*Div(x) + 0*Div(y) + -4*Div(x-y)                        |
|                                                              |
|o2 : WeilDivisor on R                                         |
+--------------------------------------------------------------+
|i3 : E = (1/2)*D                                              |
|                                                              |
|o3 = Div(x) + -2*Div(x-y)                                     |
|                                                              |
|o3 : QWeilDivisor on R                                        |
+--------------------------------------------------------------+
|i4 : F = toRWeilDivisor(D)                                    |
|                                                              |
|o4 = 2*Div(x) + -4*Div(x-y)                                   |
|                                                              |
|o4 : RWeilDivisor on R                                        |
+--------------------------------------------------------------+
|i5 : G = toRWeilDivisor(E)                                    |
|                                                              |
|o5 = Div(x) + -2*Div(x-y)                                     |
|                                                              |
|o5 : RWeilDivisor on R                                        |
+--------------------------------------------------------------+
|i6 : F == 2*G                                                 |
|                                                              |
|o6 = true                                                     |
+--------------------------------------------------------------+

See also
========

  * toWeilDivisor -- create a Weil divisor from a Q or
    R-divisor
  * toQWeilDivisor -- create a Q-Weil divisor from a
    Weil divisor

Ways to use toRWeilDivisor :
============================

  * "toRWeilDivisor(QWeilDivisor)"
  * "toRWeilDivisor(RWeilDivisor)"
  * "toRWeilDivisor(WeilDivisor)"

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

The object toRWeilDivisor, is a method function (Macaulay2Doc).

toWeilDivisor -- create a Weil divisor from a Q or R-divisor
************************************************************

Synopsis
========

  * Usage:
        toWeilDivisor( E1 )
  * Inputs:
      * E1, an instance of the type RWeilDivisor,
  * Outputs:
      * an instance of the type WeilDivisor,

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

Given a divisor with rational or real coefficients, but whose coefficients are
actually integers, we first check if all coefficients are integers. If so we
make this Weil divisor.  Otherwise, an error is thrown.

+-----------------------------------------------------------------------------+
|i1 : R=QQ[x];                                                                |
+-----------------------------------------------------------------------------+
|i2 : D=divisor({3/2}, {ideal(x)}, CoefficientType=>QQ)                       |
|                                                                             |
|o2 = 3/2*Div(x)                                                              |
|                                                                             |
|o2 : QWeilDivisor on R                                                       |
+-----------------------------------------------------------------------------+
|i3 : E=divisor({1.5}, {ideal(x)}, CoefficientType=>RR)                       |
|                                                                             |
|o3 = 1.5*Div(x)                                                              |
|                                                                             |
|o3 : RWeilDivisor on R                                                       |
+-----------------------------------------------------------------------------+
|i4 : toWeilDivisor(2*D)                                                      |
|                                                                             |
|o4 = 3*Div(x)                                                                |
|                                                                             |
|o4 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i5 : toWeilDivisor(2*E)                                                      |
|                                                                             |
|o5 = 3*Div(x)                                                                |
|                                                                             |
|o5 : WeilDivisor on R                                                        |
+-----------------------------------------------------------------------------+
|i6 : isWeilDivisor(D)                                                        |
|                                                                             |
|o6 = false                                                                   |
+-----------------------------------------------------------------------------+
|i7 : try toWeilDivisor(D) then print "converted to a WeilDivisor" else print |
|can't be converted to a WeilDivisor                                          |
|-----------------------------------------------------------------------------|
|"can't be converted to a WeilDivisor"                                        |
+-----------------------------------------------------------------------------+

Notice in the final computation, D cannot be converted into a Weil divisor
since $D$ has non-integer coefficients, but 2*D can be converted into a Weil
divisor.

See also
========

  * toQWeilDivisor -- create a Q-Weil divisor from a
    Weil divisor
  * toRWeilDivisor -- create a R-divisor from a Q or
    Weil divisor
  * isWeilDivisor -- whether a rational/real divisor is
    in actuality a Weil divisor

Ways to use toWeilDivisor :
===========================

  * "toWeilDivisor(RWeilDivisor)"

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

The object toWeilDivisor, is a method function (Macaulay2Doc).

trim(BasicDivisor) -- trims the ideals displayed to the user and removes primes with coefficient zero
*****************************************************************************************************

Synopsis
========

  * Function: trim (Macaulay2Doc),
  * Usage:
        trim( D1 )
  * Inputs:
      * D1, an instance of the type BasicDivisor,
  * Optional inputs (Macaulay2Doc),:
      * Strategy (Macaulay2Doc), => ..., default value null,
        null
  * Outputs:
      * an instance of the type BasicDivisor,

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

This function returns a divisor where all entries with coefficient zero are
removed and where the ideals displayed to the user are trimmed.

+-------------------------------------------------------------------------+
|i1 : R = QQ[x,y,z]/ideal(x*y-z^2);                                       |
+-------------------------------------------------------------------------+
|i2 : D = divisor({1,0,-2}, {ideal(x, z), ideal(x-z,y-z), ideal(y+z, z)});|
|                                                                         |
|o2 : WeilDivisor on R                                                    |
+-------------------------------------------------------------------------+
|i3 : cleanSupport(D)                                                     |
|                                                                         |
|o3 = Div(x, z) + -2*Div(y+z, z)                                          |
|                                                                         |
|o3 : WeilDivisor on R                                                    |
+-------------------------------------------------------------------------+
|i4 : trim(D)                                                             |
|                                                                         |
|o4 = Div(z, x) + -2*Div(z, y)                                            |
|                                                                         |
|o4 : WeilDivisor on R                                                    |
+-------------------------------------------------------------------------+
|i5 : D == trim(D)                                                        |
|                                                                         |
|o5 = true                                                                |
+-------------------------------------------------------------------------+

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

  * trim(BasicDivisor) -- trims the ideals
    displayed to the user and removes primes with coefficient zero

zeroDivisor -- constructs the zero Weil divisor for the ring
************************************************************

Synopsis
========

  * Usage:
        zeroDivisor(R)
  * Inputs:
      * R, a ring (Macaulay2Doc),
  * Outputs:
      * an instance of the type WeilDivisor,

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

Constructs the zero Weil divisor for the input ring

+------------------------------------------+
|i1 : R = QQ[x, y, z] / ideal(x * y - z^2);|
+------------------------------------------+
|i2 : D = zeroDivisor( R )                 |
|                                          |
|o2 = 0, the zero divisor                  |
|                                          |
|o2 : WeilDivisor on R                     |
+------------------------------------------+

Ways to use zeroDivisor :
=========================

  * "zeroDivisor(Ring)"

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

The object zeroDivisor, is a method function (Macaulay2Doc).