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

Valuations -- A package for constructing and using valuations.
**************************************************************

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

A valuation is a function $v:R\rightarrow G\cup\{\infty\}$ where $R$ is a ring
and $G$ is a linearly ordered group with the following properties:

  * $v(ab)=v(a)+v(b)$,
  * $v(a+b)\geq\min\{v(a),v(b)\}$, and
  * $v(a)=\infty$ iff $a=0$.

The Valuations package provides uniform constructions of common valuations and
also offers user-defined valuations. A valuation acts like a function (Macaulay2Doc),
but may contain extra information.

+---------------------------------------+
|i1 : pval = padicValuation 3;          |
+---------------------------------------+
|i2 : pval(54)                          |
|                                       |
|o2 = 3                                 |
+---------------------------------------+
|i3 : pval(2)                           |
|                                       |
|o3 = 0                                 |
+---------------------------------------+
|i4 : R = QQ[x,y];                      |
+---------------------------------------+
|i5 : leadval = leadTermValuation R;    |
+---------------------------------------+
|i6 : leadval(x^3+3*x^3*y^2+2*y^4)      |
|                                       |
|o6 = | -3 |                            |
|     | -2 |                            |
|                                       |
|o6 : Ordered QQ^2 module               |
+---------------------------------------+
|i7 : lowestval = lowestTermValuation R;|
+---------------------------------------+
|i8 : lowestval(x^3+3*x^3*y^2+2*y^4)    |
|                                       |
|o8 = | 3 |                             |
|     | 0 |                             |
|                                       |
|o8 : Ordered QQ^2 module               |
+---------------------------------------+
|i9 : lowestval(0)                      |
|                                       |
|o9 = infinity                          |
|                                       |
|o9 : InfiniteNumber                    |
+---------------------------------------+

Authors
=======

  * Michael Burr (see https://cecas.clemson.edu/~burr2/ ) <burr2@clemson.edu>
  * Colin Alstad (see https://colinalstad.com/ ) <calstad@clemson.edu>
  * Michael Byrd (see https://michael-byrd.github.io ) <mbyrd6@clemson.edu>
  * Ethan Partida (see https://ethanpartida.github.io/ )
    <ethan_partida@brown.edu>
  * Shelby Cox <spcox@umich.edu>
  * Courtney George <courtney.george@uky.edu>
  * Oliver Clarke (see https://www.oliverclarkemath.com/ )
    <oliver.clarke@ed.ac.uk>

Version
=======

This documentation describes version 1.0 of Valuations.

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

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

Exports
=======

  * Types
      * OrderedQQn -- The class of all ordered modules
        $\QQ^n$
      * OrderedQQVector -- The class of all vectors of
        an ordered module $\QQ^n$
      * Valuation -- The type of all valuations
  * Functions and commands
      * coneToValuation -- Convert a prime cone of a
        tropical ideal to a (quasi-)valuation
      * leadTermValuation -- The valuation defined by
        leading terms
      * localRingValuation -- The valuation defined
        by a local ring.
      * lowestTermValuation -- The valuation
        defined by lowest terms
      * orderedQQn -- Construct an ordered module $\QQ^n$
      * padicValuation -- The p-adic valuation
      * "primeConesOfIdeal" -- see primeConesOfSubalgebra,
        -- Finds the prime cones of the tropicalization
        of a given subalgebra or ideal.
      * primeConesOfSubalgebra -- Finds the
        prime cones of the tropicalization of a given subalgebra or ideal.
      * valM -- Construct a valuation from a (quasi-)valuation
      * valuation -- User-defined valuation object
  * Methods
      * "coneToValuation(Matrix,Subring)" -- see coneToValuation,
        -- Convert a prime cone of a tropical ideal to a
        (quasi-)valuation
      * "coneToValuation(Matrix,Subring,Ring)" -- see coneToValuation,
        -- Convert a prime cone of a tropical ideal to a
        (quasi-)valuation
      * "leadTermValuation(PolynomialRing)" -- see leadTermValuation,
        -- The valuation defined by leading terms
      * "localRingValuation(LocalRing)" -- see localRingValuation,
        -- The valuation defined by a local ring.
      * "lowestTermValuation(PolynomialRing)" -- see lowestTermValuation,
        -- The valuation defined by lowest terms
      * net(Valuation) (missing documentation)
      * "OrderedQQn == OrderedQQn" -- see Ordered modules,
        -- Overview of the ordered module $\QQ^n$
      * "orderedQQn(PolynomialRing)" -- see orderedQQn, --
        Construct an ordered module $\QQ^n$
      * "orderedQQn(ZZ,List)" -- see orderedQQn, -- Construct
        an ordered module $\QQ^n$
      * "InfiniteNumber == OrderedQQVector" -- see OrderedQQVector,
        -- The class of all vectors of an ordered module
        $\QQ^n$
      * "OrderedQQVector == InfiniteNumber" -- see OrderedQQVector,
        -- The class of all vectors of an ordered module
        $\QQ^n$
      * "OrderedQQVector ? OrderedQQVector" -- see OrderedQQVector,
        -- The class of all vectors of an ordered module
        $\QQ^n$
      * "padicValuation(ZZ)" -- see padicValuation, --
        The p-adic valuation
      * "primeConesOfIdeal(Ideal)" -- see primeConesOfSubalgebra,
        -- Finds the prime cones of the tropicalization
        of a given subalgebra or ideal.
      * "primeConesOfSubalgebra(Subring)" -- see primeConesOfSubalgebra,
        -- Finds the prime cones of the tropicalization
        of a given subalgebra or ideal.
      * "valM(Ring,Valuation)" -- see valM, -- Construct a
        valuation from a (quasi-)valuation
      * "valuation(Function)" -- see valuation, --
        User-defined valuation object
      * "valuation(Function,LocalRing,LocalRing)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,LocalRing,OrderedQQn)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,LocalRing,Ring)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,LocalRing,RingOfInvariants)" -- see
        valuation, -- User-defined valuation object
      * "valuation(Function,LocalRing,Subring)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,Ring,LocalRing)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,Ring,OrderedQQn)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,Ring,Ring)" -- see valuation, --
        User-defined valuation object
      * "valuation(Function,Ring,RingOfInvariants)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,Ring,Subring)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,RingOfInvariants,LocalRing)" -- see
        valuation, -- User-defined valuation object
      * "valuation(Function,RingOfInvariants,OrderedQQn)" -- see
        valuation, -- User-defined valuation object
      * "valuation(Function,RingOfInvariants,Ring)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,RingOfInvariants,RingOfInvariants)" -- see
        valuation, -- User-defined valuation object
      * "valuation(Function,RingOfInvariants,Subring)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,Subring,LocalRing)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,Subring,OrderedQQn)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,Subring,Ring)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,Subring,RingOfInvariants)" -- see valuation,
        -- User-defined valuation object
      * "valuation(Function,Subring,Subring)" -- see valuation,
        -- User-defined valuation object
      * Valuation Constant (missing documentation)
      * Valuation Number (missing documentation)
      * Valuation RingElement (missing documentation)
  * Other things
      * trivialValuation -- The trivial valuation

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

The object Valuations, is a package (Macaulay2Doc).

coneToValuation -- Convert a prime cone of a tropical ideal to a (quasi-)valuation
**********************************************************************************

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

This function constructs a valuation from the prime cone of a tropical variety.
From a Subring (SubalgebraBases), and the rays of a prime cone of
the kernel of its presentationRing (SubalgebraBases), a
(quasi-)valuation is constructed.  A quasivaluation satisfies
$\nu(fg)\geq\min\{\nu(f),\nu(g)\},$ where the inequality replaces the equality.

+--------------------------------------------+
|i1 : R = QQ[x_1, x_2, x_3];                 |
+--------------------------------------------+
|i2 : A = subring {                          |
|         x_1 + x_2 + x_3,                   |
|         x_1*x_2 + x_1*x_3 + x_2*x_3,       |
|         x_1*x_2*x_3,                       |
|         (x_1 - x_2)*(x_1 - x_3)*(x_2 - x_3)|
|         };                                 |
+--------------------------------------------+
|i3 : C = primeConesOfSubalgebra A           |
|                                            |
|o3 = {| -3 22 |, | 22 -3 |, | -11 -2 |}     |
|      | -6 -2 |  | -2 -6 |  | 1   19 |      |
|      | 14 -3 |  | -3 -9 |  | 13  -6 |      |
|      | -9 -3 |  | -3 14 |  | -10 -6 |      |
|                                            |
|o3 : List                                   |
+--------------------------------------------+
|i4 : val = coneToValuation(C#0, A)          |
|                                            |
|o4 = valuation from QQ[p_0..p_3] to QQ^2    |
|                                            |
|o4 : Valuation                              |
+--------------------------------------------+
|i5 : use A#"presentationRing";              |
+--------------------------------------------+
|i6 : val(p_0^2 + p_1*p_2 - p_3^3)           |
|                                            |
|o6 = |  -9 |                                |
|     | -18 |                                |
|                                            |
|o6 : Ordered QQ^2 module                    |
+--------------------------------------------+

See also
========

  * valM -- Construct a valuation from a (quasi-)valuation
  * Subring (SubalgebraBases) -- The type of all subrings
  * presentationRing (SubalgebraBases) -- returns the
    presentation ring of a subring

Ways to use coneToValuation:
============================

  * "coneToValuation(Matrix,Subring)"
  * "coneToValuation(Matrix,Subring,Ring)"

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

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

leadTermValuation -- The valuation defined by leading terms
***********************************************************

Synopsis
========

  * Usage:
        v = leadTermValuation R
  * Inputs:
      * R, a polynomial ring (Macaulay2Doc), the ring
        whose term order is used to define the valuation
  * Outputs:
      * v, an instance of the type Valuation, the lead term
        valuation

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

This function constructs a valuation which returns the negative exponent vector
of the lead term of a polynomial with respect to the ring's term order. The
valuation returns vectors in an ordered $\QQ$-module, which respects the
monomial order of the PolynomialRing (Macaulay2Doc). For
more details see Ordered modules.

+-----------------------------------------+
|i1 : R = QQ[a,b,c, MonomialOrder => Lex];|
+-----------------------------------------+
|i2 : v = leadTermValuation R;            |
+-----------------------------------------+
|i3 : f = 13*a^2*b + a*c^3;               |
+-----------------------------------------+
|i4 : g = 5*a^2*c + b^3;                  |
+-----------------------------------------+
|i5 : v f                                 |
|                                         |
|o5 = | -2 |                              |
|     | -1 |                              |
|     |  0 |                              |
|                                         |
|o5 : Ordered QQ^3 module                 |
+-----------------------------------------+
|i6 : v g                                 |
|                                         |
|o6 = | -2 |                              |
|     |  0 |                              |
|     | -1 |                              |
|                                         |
|o6 : Ordered QQ^3 module                 |
+-----------------------------------------+
|i7 : v f < v g                           |
|                                         |
|o7 = true                                |
+-----------------------------------------+

See also
========

  * valuation -- User-defined valuation object
  * Valuation -- The type of all valuations
  * localRingValuation -- The valuation defined by a
    local ring.
  * lowestTermValuation -- The valuation defined by
    lowest terms
  * padicValuation -- The p-adic valuation
  * trivialValuation -- The trivial valuation

Ways to use leadTermValuation:
==============================

  * "leadTermValuation(PolynomialRing)"

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

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

localRingValuation -- The valuation defined by a local ring.
************************************************************

Synopsis
========

  * Usage:
        v = localRingValuation(R)
  * Inputs:
      * R, a local ring (LocalRings), the ring whose maximal
        ideal determines the order
  * Outputs:
      * v, an instance of the type Valuation, local ring
        valuation using a local ring R

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

This function constructs a valuation which returns the largest power of the
maximal ideal of R that contains the input to the valuation.

+----------------------------------------+
|i1 : R = QQ[x,y];                       |
+----------------------------------------+
|i2 : I = ideal(x,y);                    |
|                                        |
|o2 : Ideal of R                         |
+----------------------------------------+
|i3 : S = R_I                            |
|                                        |
|o3 = S                                  |
|                                        |
|o3 : LocalRing, maximal ideal (x, y)    |
+----------------------------------------+
|i4 : localVal = localRingValuation(S)   |
|                                        |
|o4 = valuation from S to ZZ             |
|                                        |
|o4 : Valuation                          |
+----------------------------------------+
|i5 : localVal(1 + x + y)                |
|                                        |
|o5 = 0                                  |
+----------------------------------------+
|i6 : localVal(x^4 + x^2*y^2 + x^7 + y^3)|
|                                        |
|o6 = 3                                  |
+----------------------------------------+
|i7 : localVal(x^2 + x*y + y^2)          |
|                                        |
|o7 = 2                                  |
+----------------------------------------+

This valuation may be applied to elements of the fraction field of R, where the
value of the valuation is the difference between the valuations of the
numerator and denominator.

+------------------------------+
|i8 : localVal(1/(x^2+x*y+y^3))|
|                              |
|o8 = -2                       |
+------------------------------+

See also
========

  * valuation -- User-defined valuation object
  * Valuation -- The type of all valuations
  * leadTermValuation -- The valuation defined by
    leading terms
  * lowestTermValuation -- The valuation defined by
    lowest terms
  * padicValuation -- The p-adic valuation
  * trivialValuation -- The trivial valuation

Ways to use localRingValuation:
===============================

  * "localRingValuation(LocalRing)"

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

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

lowestTermValuation -- The valuation defined by lowest terms
************************************************************

Synopsis
========

  * Usage:
        v = lowestTermValuation
  * Inputs:
      * R, a polynomial ring (Macaulay2Doc), the ring
        whose term order is used to define the valuation
  * Outputs:
      * v, an instance of the type Valuation, the lowest term
        valuation

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

This function builds a valuation which returns the exponent vector of the lead
term of a polynomial with respect to the ring's term order. The valuation
returns vectors in an ordered $\QQ$-module, which respects the monomial order
of the PolynomialRing (Macaulay2Doc). For more details
see Ordered modules.

+-------------------------------------------------------------+
|i1 : R = QQ[a,b,c, MonomialOrder => Lex];                    |
+-------------------------------------------------------------+
|i2 : vR = lowestTermValuation R;                             |
+-------------------------------------------------------------+
|i3 : f = 13*a^2*b + a*c^3;                                   |
+-------------------------------------------------------------+
|i4 : g = 5*a^2*c + b^3;                                      |
+-------------------------------------------------------------+
|i5 : vR f                                                    |
|                                                             |
|o5 = | 1 |                                                   |
|     | 0 |                                                   |
|     | 3 |                                                   |
|                                                             |
|o5 : Ordered QQ^3 module                                     |
+-------------------------------------------------------------+
|i6 : vR f < vR g                                             |
|                                                             |
|o6 = false                                                   |
+-------------------------------------------------------------+
|i7 : S = QQ[a,b,c, MonomialOrder => RevLex, Global => false];|
+-------------------------------------------------------------+
|i8 : vS = lowestTermValuation S;                             |
+-------------------------------------------------------------+
|i9 : f = 13*a^2*b + a*c^3;                                   |
+-------------------------------------------------------------+
|i10 : g = 5*a^2*c + b^3;                                     |
+-------------------------------------------------------------+
|i11 : vS f                                                   |
|                                                             |
|o11 = | 2 |                                                  |
|      | 1 |                                                  |
|      | 0 |                                                  |
|                                                             |
|o11 : Ordered QQ^3 module                                    |
+-------------------------------------------------------------+
|i12 : vS f < vS g                                            |
|                                                             |
|o12 = true                                                   |
+-------------------------------------------------------------+

See also
========

  * valuation -- User-defined valuation object
  * Valuation -- The type of all valuations
  * leadTermValuation -- The valuation defined by
    leading terms
  * localRingValuation -- The valuation defined by a
    local ring.
  * padicValuation -- The p-adic valuation
  * trivialValuation -- The trivial valuation

Ways to use lowestTermValuation:
================================

  * "lowestTermValuation(PolynomialRing)"

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

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

Ordered modules -- Overview of the ordered module $\QQ^n$
*********************************************************

Many standard valuations take values in a totally ordered subgroup $\Gamma
\subseteq \QQ^n$. These standard valuations implement an instance of the type
OrderedQQn, whose order is based on the monomial order of a
given ring $R$. The values in $\QQ^n$ are compared using the monomial order of
$R$. By default, our valuations use the min convention, that is $v(a + b) \ge
\min(v(a), v(b))$.

+-----------------------------+
|i1 : R = QQ[x,y];            |
+-----------------------------+
|i2 : I = ideal(x,y);         |
|                             |
|o2 : Ideal of R              |
+-----------------------------+
|i3 : v = leadTermValuation R;|
+-----------------------------+
|i4 : a = v(x)                |
|                             |
|o4 = | -1 |                  |
|     |  0 |                  |
|                             |
|o4 : Ordered QQ^2 module     |
+-----------------------------+
|i5 : b = v(y)                |
|                             |
|o5 = |  0 |                  |
|     | -1 |                  |
|                             |
|o5 : Ordered QQ^2 module     |
+-----------------------------+
|i6 : c = v(x+y)              |
|                             |
|o6 = | -1 |                  |
|     |  0 |                  |
|                             |
|o6 : Ordered QQ^2 module     |
+-----------------------------+
|i7 : a > b                   |
|                             |
|o7 = false                   |
+-----------------------------+
|i8 : a == c                  |
|                             |
|o8 = true                    |
+-----------------------------+

Two ordered $\QQ^n$ modules are equal if they are built from the same ring.
Note that isomorphic rings with the same term order may not be equal.

+-----------------------------------------------------------------------------+
|i9 : M1 = orderedQQn(3, {Lex})                                               |
|                                                                             |
|       3                                                                     |
|o9 = QQ                                                                      |
|                                                                             |
|o9 : Ordered QQ^3 module                                                     |
+-----------------------------------------------------------------------------+
|i10 : R = M1.cache.Ring                                                      |
|                                                                             |
|o10 = R                                                                      |
|                                                                             |
|o10 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i11 : M2 = orderedQQn R                                                      |
|                                                                             |
|        3                                                                    |
|o11 = QQ                                                                     |
|                                                                             |
|o11 : Ordered QQ^3 module                                                    |
+-----------------------------------------------------------------------------+
|i12 : M1 == M2                                                               |
|                                                                             |
|o12 = true                                                                   |
+-----------------------------------------------------------------------------+
|i13 : S = QQ[x_1 .. x_3, MonomialOrder => {Lex}]                             |
|warning: clearing value of symbol x to allow access to subscripted           |
|       : debug with expression   debug 9868   or with command line           |
|                                                                             |
|o13 = S                                                                      |
|                                                                             |
|o13 : PolynomialRing                                                         |
|-----------------------------------------------------------------------------|
|variables based on it                                                        |
|option   --debug 9868                                                        |
+-----------------------------------------------------------------------------+
|i14 : M3 = orderedQQn S                                                      |
|                                                                             |
|        3                                                                    |
|o14 = QQ                                                                     |
|                                                                             |
|o14 : Ordered QQ^3 module                                                    |
+-----------------------------------------------------------------------------+
|i15 : M1 == M3                                                               |
|                                                                             |
|o15 = false                                                                  |
+-----------------------------------------------------------------------------+

See also
========

  * leadTermValuation -- The valuation defined by
    leading terms
  * lowestTermValuation -- The valuation defined by
    lowest terms
  * OrderedQQn -- The class of all ordered modules $\QQ^n$
  * orderedQQn -- Construct an ordered module $\QQ^n$

OrderedQQn -- The class of all ordered modules $\QQ^n$
******************************************************

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

For an introduction see Ordered modules. Every element
of an ordered $\QQ^n$ module is an instance of the type OrderedQQVector.
A new ordered $\QQ^n$ module is created with the function
orderedQQn.

+---------------------------------------------+
|i1 : R = QQ[x_1 .. x_4, MonomialOrder => Lex]|
|                                             |
|o1 = R                                       |
|                                             |
|o1 : PolynomialRing                          |
+---------------------------------------------+
|i2 : M = orderedQQn R                        |
|                                             |
|       4                                     |
|o2 = QQ                                      |
|                                             |
|o2 : Ordered QQ^4 module                     |
+---------------------------------------------+
|i3 : M_0, M_1, M_2, M_3                      |
|                                             |
|o3 = (| 1 |, | 0 |, | 0 |, | 0 |)            |
|      | 0 |  | 1 |  | 0 |  | 0 |             |
|      | 0 |  | 0 |  | 1 |  | 0 |             |
|      | 0 |  | 0 |  | 0 |  | 1 |             |
|                                             |
|o3 : Sequence                                |
+---------------------------------------------+
|i4 : M_0 < M_1                               |
|                                             |
|o4 = false                                   |
+---------------------------------------------+
|i5 : M_0 + M_3 < M_1 + M_2                   |
|                                             |
|o5 = false                                   |
+---------------------------------------------+

See also
========

  * Ordered modules -- Overview of the ordered module
    $\QQ^n$
  * orderedQQn -- Construct an ordered module $\QQ^n$
  * OrderedQQVector -- The class of all vectors of an
    ordered module $\QQ^n$

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

  * "OrderedQQn == OrderedQQn" -- see Ordered modules,
    -- Overview of the ordered module $\QQ^n$
  * "valuation(Function,LocalRing,OrderedQQn)" -- see valuation,
    -- User-defined valuation object
  * "valuation(Function,Ring,OrderedQQn)" -- see valuation, --
    User-defined valuation object
  * "valuation(Function,RingOfInvariants,OrderedQQn)" -- see valuation,
    -- User-defined valuation object
  * "valuation(Function,Subring,OrderedQQn)" -- see valuation,
    -- User-defined valuation object

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

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

orderedQQn -- Construct an ordered module $\QQ^n$
*************************************************

Synopsis
========

  * Usage:
        M = orderedQQn R
        M = orderedQQn(n, monomialOrders)
  * Inputs:
      * R, a polynomial ring (Macaulay2Doc), polynomial
        ring for the construction
      * n, an integer (Macaulay2Doc), rank of the module
      * monomialOrder, a list (Macaulay2Doc), monomial order for
        comparison
  * Outputs:
      * M, an instance of the type OrderedQQn,

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

For an overview see Ordered modules. Let $R$ be a
polynomial ring (Macaulay2Doc), with $n$ variables $x_1 \dots
x_n$. Then the corresponding ordered $\QQ^n$ module has the following ordering.
Suppose that $v, w \in \QQ^n$. Let $d \in \ZZ$ be a positive integer and $c \in
\ZZ^n_{\ge 0}$ be a vector such that $dv + c$ and $dw + c$ have non-negative
entries. Then $v < w$ if and only if $x^{dv + c} > x^{dw + c}$ in $R$. Note
that this property does not depend on the choices of $c$ and $d$, so we obtain
a well-defined order on $\QQ^n$.

+---------------------------------------------+
|i1 : R = QQ[x_1 .. x_3, MonomialOrder => Lex]|
|                                             |
|o1 = R                                       |
|                                             |
|o1 : PolynomialRing                          |
+---------------------------------------------+
|i2 : M = orderedQQn R                        |
|                                             |
|       3                                     |
|o2 = QQ                                      |
|                                             |
|o2 : Ordered QQ^3 module                     |
+---------------------------------------------+
|i3 : v = 1/2 * M_0 - 1/3 * M_1               |
|                                             |
|o3 = |  1/2 |                                |
|     | -1/3 |                                |
|     |   0  |                                |
|                                             |
|o3 : Ordered QQ^3 module                     |
+---------------------------------------------+
|i4 : w = 1/2 * M_0 + 1/4 * M_2               |
|                                             |
|o4 = | 1/2 |                                 |
|     |  0  |                                 |
|     | 1/4 |                                 |
|                                             |
|o4 : Ordered QQ^3 module                     |
+---------------------------------------------+
|i5 : v < w                                   |
|                                             |
|o5 = true                                    |
+---------------------------------------------+

Instead of supplying a polynomial ring (Macaulay2Doc), we
may supply the rank $n$ of the module along with a monomial order. The
constructor creates the ring $R$ with $n$ variables and the given monomial
order to construct the OrderedQQn, module

+-----------------------------+
|i6 : N = orderedQQn(3, {Lex})|
|                             |
|       3                     |
|o6 = QQ                      |
|                             |
|o6 : Ordered QQ^3 module     |
+-----------------------------+
|i7 : R = N.cache.Ring        |
|                             |
|o7 = R                       |
|                             |
|o7 : PolynomialRing          |
+-----------------------------+
|i8 : N' = orderedQQn R       |
|                             |
|       3                     |
|o8 = QQ                      |
|                             |
|o8 : Ordered QQ^3 module     |
+-----------------------------+
|i9 : N == N'                 |
|                             |
|o9 = true                    |
+-----------------------------+

$N$ and $N'$ are the same module because they are built from the same ring. See
OrderedQQn == OrderedQQn.

See also
========

  * Ordered modules -- Overview of the ordered module
    $\QQ^n$
  * OrderedQQn -- The class of all ordered modules $\QQ^n$

Ways to use orderedQQn:
=======================

  * "orderedQQn(PolynomialRing)"
  * "orderedQQn(ZZ,List)"

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

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

OrderedQQVector -- The class of all vectors of an ordered module $\QQ^n$
************************************************************************

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

For an introduction see Ordered modules. Every ordered
$\QQ^n$ vector belongs to an instance of the type OrderedQQn.
The ordered $\QQ^n$ vectors are most easily accessed though the
original module.

+-----------------------------+
|i1 : M = orderedQQn(3, {Lex})|
|                             |
|       3                     |
|o1 = QQ                      |
|                             |
|o1 : Ordered QQ^3 module     |
+-----------------------------+
|i2 : M_0 + 2 * M_1 + 3 * M_2 |
|                             |
|o2 = | 1 |                   |
|     | 2 |                   |
|     | 3 |                   |
|                             |
|o2 : Ordered QQ^3 module     |
+-----------------------------+

Any pair of vectors of a module of type OrderedQQn, may be
compared with <, >, and ==.

+------------------------------+
|i3 : M = orderedQQn(3, {GLex})|
|                              |
|       3                      |
|o3 = QQ                       |
|                              |
|o3 : Ordered QQ^3 module      |
+------------------------------+
|i4 : 2*M_1 < M_0 + M_2        |
|                              |
|o4 = true                     |
+------------------------------+
|i5 : 3*M_1 < M_0 + M_2        |
|                              |
|o5 = false                    |
+------------------------------+

The image of $0$ under a valuation is $\infty$, so it may be necessary to test
whether an element of an ordered module $\QQ^n$ is equal to the valuation of
$0$.

+-----------------------------+
|i6 : M = orderedQQn(3, {Lex})|
|                             |
|       3                     |
|o6 = QQ                      |
|                             |
|o6 : Ordered QQ^3 module     |
+-----------------------------+
|i7 : M_0 < infinity          |
|                             |
|o7 = true                    |
+-----------------------------+
|i8 : M_0 == infinity         |
|                             |
|o8 = false                   |
+-----------------------------+

See also
========

  * Ordered modules -- Overview of the ordered module
    $\QQ^n$
  * OrderedQQn -- The class of all ordered modules $\QQ^n$
  * orderedQQn -- Construct an ordered module $\QQ^n$

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

  * "InfiniteNumber == OrderedQQVector"
  * "OrderedQQVector == InfiniteNumber"
  * "OrderedQQVector ? OrderedQQVector"

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

The object OrderedQQVector, is a type (Macaulay2Doc),
with ancestor classes Vector (Macaulay2Doc),
< BasicList (Macaulay2Doc) < Thing (Macaulay2Doc).

padicValuation -- The p-adic valuation
**************************************

Synopsis
========

  * Usage:
        v = padicValuation(p)
  * Inputs:
      * p, an integer (Macaulay2Doc), a prime
  * Outputs:
      * v, an instance of the type Valuation, p-adic
        valuation using prime p

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

This function constructs a valuation which returns the number of times that $p$
divides the numerator minus the number of times that $p$ divides the
denominator.

+--------------------------+
|i1 : v = padicValuation 7;|
+--------------------------+
|i2 : v 98                 |
|                          |
|o2 = 2                    |
+--------------------------+
|i3 : v (2/7)              |
|                          |
|o3 = -1                   |
+--------------------------+
|i4 : v 0                  |
|                          |
|o4 = infinity             |
|                          |
|o4 : InfiniteNumber       |
+--------------------------+
|i5 : v (-42)              |
|                          |
|o5 = 1                    |
+--------------------------+

See also
========

  * valuation -- User-defined valuation object
  * Valuation -- The type of all valuations
  * leadTermValuation -- The valuation defined by
    leading terms
  * lowestTermValuation -- The valuation defined by
    lowest terms
  * localRingValuation -- The valuation defined by a
    local ring.
  * trivialValuation -- The trivial valuation

Ways to use padicValuation:
===========================

  * "padicValuation(ZZ)"

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

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

primeConesOfSubalgebra -- Finds the prime cones of the tropicalization of a given subalgebra or ideal.
******************************************************************************************************

Synopsis
========

  * Usage:
        C = primeConesOfSubalgebra(S)
        C = primeConesOfIdeal(I)
  * Inputs:
      * S, an instance of the type Subring (SubalgebraBases),
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * C, a list (Macaulay2Doc), containing the ray-generators of
        the prime cones.

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

Let $I \subset k[x]$ be a prime ideal and let $C \subset \mathcal{T}(I)$ be an
open cone in the tropicalization of $I$.  This function returns all such $C$
where the initial ideal $\operatorname{in_{C}}(I)$ is a prime ideal.  When the
input is a Subring (SubalgebraBases), which is a domain, then $I$
is the kernel of the presentation map of $S$.

+--------------------------------------------+
|i1 : R = QQ[x_1, x_2, x_3];                 |
+--------------------------------------------+
|i2 : A = subring {                          |
|         x_1 + x_2 + x_3,                   |
|         x_1*x_2 + x_1*x_3 + x_2*x_3,       |
|         x_1*x_2*x_3,                       |
|         (x_1 - x_2)*(x_1 - x_3)*(x_2 - x_3)|
|         };                                 |
+--------------------------------------------+
|i3 : primeConesOfSubalgebra A               |
|                                            |
|o3 = {| -3 22 |, | 22 -3 |, | -11 -2 |}     |
|      | -6 -2 |  | -2 -6 |  | 1   19 |      |
|      | 14 -3 |  | -3 -9 |  | 13  -6 |      |
|      | -9 -3 |  | -3 14 |  | -10 -6 |      |
|                                            |
|o3 : List                                   |
+--------------------------------------------+
|i4 : I = ideal(x_1*x_2+x_2^2+x_3^2);        |
|                                            |
|o4 : Ideal of R                             |
+--------------------------------------------+
|i5 : primeConesOfIdeal I                    |
|                                            |
|o5 = {| -1 |}                               |
|      | 1  |                                |
|      | 0  |                                |
|                                            |
|o5 : List                                   |
+--------------------------------------------+

See also
========

  * coneToValuation -- Convert a prime cone of a
    tropical ideal to a (quasi-)valuation
  * valM -- Construct a valuation from a (quasi-)valuation

Ways to use primeConesOfSubalgebra:
===================================

  * "primeConesOfSubalgebra(Subring)"

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

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

trivialValuation -- The trivial valuation
*****************************************

Synopsis
========

  * Usage:
        v = trivialValuation
  * Outputs:
      * v, an instance of the type Valuation, the trivial
        valuation

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

This valuation returns zero for all nonzero inputs.

+--------------------------+
|i1 : v = trivialValuation;|
+--------------------------+
|i2 : v (-13)              |
|                          |
|o2 = 0                    |
+--------------------------+
|i3 : v 100000000          |
|                          |
|o3 = 0                    |
+--------------------------+
|i4 : v (14/23)            |
|                          |
|o4 = 0                    |
+--------------------------+
|i5 : v 0                  |
|                          |
|o5 = infinity             |
|                          |
|o5 : InfiniteNumber       |
+--------------------------+

See also
========

  * valuation -- User-defined valuation object
  * Valuation -- The type of all valuations
  * leadTermValuation -- The valuation defined by
    leading terms
  * lowestTermValuation -- The valuation defined by
    lowest terms
  * localRingValuation -- The valuation defined by a
    local ring.
  * padicValuation -- The p-adic valuation

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

The object trivialValuation, is an instance of the type
Valuation.

valM -- Construct a valuation from a (quasi-)valuation
******************************************************

Synopsis
========

  * Usage:
        val = valuation(R, v)
  * Inputs:
      * R, a ring (Macaulay2Doc),
      * v, an instance of the type Valuation,
  * Outputs:
      * val, an instance of the type Valuation,

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

Constructs a valuation from a (quasi-)valuation following the approach in Kaveh
and Manon, 2019. In particular, the maximum quasi-valuation of all preimages of
the input is taken as the valuation.

+--------------------------------------------------------+
|i1 : R = QQ[x_1, x_2, x_3];                             |
+--------------------------------------------------------+
|i2 : A = subring {                                      |
|         x_1 + x_2 + x_3,                               |
|         x_1*x_2 + x_1*x_3 + x_2*x_3,                   |
|         x_1*x_2*x_3,                                   |
|         (x_1 - x_2)*(x_1 - x_3)*(x_2 - x_3)            |
|         };                                             |
+--------------------------------------------------------+
|i3 : C = primeConesOfSubalgebra A;                      |
+--------------------------------------------------------+
|i4 : v = coneToValuation(C#0, A);                       |
+--------------------------------------------------------+
|i5 : vA = valM(R, v)                                    |
|                                                        |
|o5 = valuation from R to QQ^2                           |
|                                                        |
|o5 : Valuation                                          |
+--------------------------------------------------------+
|i6 : use R;                                             |
+--------------------------------------------------------+
|i7 : vA(x_1^2 + x_2^2 + x_3^2)                          |
|                                                        |
|o7 = | -2 |                                             |
|     | -4 |                                             |
|                                                        |
|o7 : Ordered QQ^2 module                                |
+--------------------------------------------------------+
|i8 : vA((x_1^2 - x_2^2)*(x_1^2 - x_3^2)*(x_2^2 - x_3^2))|
|                                                        |
|o8 = |  -5 |                                            |
|     | -10 |                                            |
|                                                        |
|o8 : Ordered QQ^2 module                                |
+--------------------------------------------------------+
|i9 : vA(0_R)                                            |
|                                                        |
|o9 = infinity                                           |
|                                                        |
|o9 : InfiniteNumber                                     |
+--------------------------------------------------------+

For elements not in A, the valuation returns unreliable results because the
valuation does not come from a weight valuation on R

+-------------------------+
|i10 : vA(x_2)            |
|                         |
|o10 = infinity           |
|                         |
|o10 : InfiniteNumber     |
+-------------------------+
|i11 : vA(x_2^2)          |
|                         |
|o11 = | -2 |             |
|      | -4 |             |
|                         |
|o11 : Ordered QQ^2 module|
+-------------------------+
|i12 : vA(x_2^3)          |
|                         |
|o12 = | -2 |             |
|      | -4 |             |
|                         |
|o12 : Ordered QQ^2 module|
+-------------------------+

References
==========

K. Khovanskii and C. Manon.  Khovanskii Bases, Higher Rank Valuations, and
Tropical Geometry.SIAM Journal on Applied Algebra and Geometry, 3(2), 2019.
(see https://epubs.siam.org/doi/10.1137/17M1160148 )

See also
========

  * coneToValuation -- Convert a prime cone of a
    tropical ideal to a (quasi-)valuation
  * primeConesOfIdeal -- Finds the prime cones
    of the tropicalization of a given subalgebra or ideal.
  * primeConesOfSubalgebra -- Finds the prime
    cones of the tropicalization of a given subalgebra or ideal.

Ways to use valM:
=================

  * "valM(Ring,Valuation)"

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

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

Valuation -- The type of all valuations
***************************************

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

Valuation is a type that contains the data needed to evaluate a valuation. A
valuation is a function $v:R\rightarrow G\cup\{\infty\}$ where $R$ is a ring
and $G$ is a linearly ordered group with the following properties:

  * $v(ab)=v(a)+v(b)$,
  * $v(a+b)\geq\min\{v(a),v(b)\}$, and
  * $v(a)=\infty$ iff $a=0$.

This package provides common valuations and user-defined valuations.

See also
========

  * valuation -- User-defined valuation object
  * leadTermValuation -- The valuation defined by
    leading terms
  * lowestTermValuation -- The valuation defined by
    lowest terms
  * localRingValuation -- The valuation defined by a
    local ring.
  * padicValuation -- The p-adic valuation
  * trivialValuation -- The trivial valuation

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

  * net(Valuation) (missing documentation)
  * "valM(Ring,Valuation)" -- see valM, -- Construct a valuation
    from a (quasi-)valuation
  * Valuation Constant (missing documentation)
  * Valuation Number (missing documentation)
  * Valuation RingElement (missing documentation)

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

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

valuation -- User-defined valuation object
******************************************

Synopsis
========

  * Usage:
        v = valuation(f)
        v = valuation(f, S, T)
  * Inputs:
      * f, a function (Macaulay2Doc), the valuation function.
      * S, a ring (Macaulay2Doc), a local ring (LocalRings),
        or an instance of the type Subring (SubalgebraBases),
        the source
      * T, a ring (Macaulay2Doc), a local ring (LocalRings),
        or an instance of the type Subring (SubalgebraBases),
        the target
  * Outputs:
      * v, an instance of the type Valuation, user-defined
        valuation function

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

Construct a user defined valuation function. User-defined functions are not
checked for satisfying the properties of a valuation. It is not necessary to
specify a source or target, but if they are provided, then the input is checked
to be in the source (or either promotable to the source or in the fraction
field of the source). For common use cases, it is suggested to use the provided
valuations.

+---------------------------------------------------------------+
|i1 : v = valuation(x -> if x == 0 then infinity else 0)        |
|                                                               |
|o1 = valuation with unspecified source and target              |
|                                                               |
|o1 : Valuation                                                 |
+---------------------------------------------------------------+
|i2 : v = valuation(x -> if x == 0 then infinity else 0, ZZ, ZZ)|
|                                                               |
|o2 = valuation from ZZ to ZZ                                   |
|                                                               |
|o2 : Valuation                                                 |
+---------------------------------------------------------------+

See also
========

  * lowestTermValuation -- The valuation defined by
    lowest terms
  * padicValuation -- The p-adic valuation
  * trivialValuation -- The trivial valuation
  * leadTermValuation -- The valuation defined by
    leading terms
  * localRingValuation -- The valuation defined by a
    local ring.

Ways to use valuation:
======================

  * "valuation(Function)"
  * "valuation(Function,LocalRing,LocalRing)"
  * "valuation(Function,LocalRing,OrderedQQn)"
  * "valuation(Function,LocalRing,Ring)"
  * "valuation(Function,LocalRing,RingOfInvariants)"
  * "valuation(Function,LocalRing,Subring)"
  * "valuation(Function,Ring,LocalRing)"
  * "valuation(Function,Ring,OrderedQQn)"
  * "valuation(Function,Ring,Ring)"
  * "valuation(Function,Ring,RingOfInvariants)"
  * "valuation(Function,Ring,Subring)"
  * "valuation(Function,RingOfInvariants,LocalRing)"
  * "valuation(Function,RingOfInvariants,OrderedQQn)"
  * "valuation(Function,RingOfInvariants,Ring)"
  * "valuation(Function,RingOfInvariants,RingOfInvariants)"
  * "valuation(Function,RingOfInvariants,Subring)"
  * "valuation(Function,Subring,LocalRing)"
  * "valuation(Function,Subring,OrderedQQn)"
  * "valuation(Function,Subring,Ring)"
  * "valuation(Function,Subring,RingOfInvariants)"
  * "valuation(Function,Subring,Subring)"

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

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