This is RealRoots.info, produced by Macaulay2, version 1.25.11

RealRoots -- Package for exploring, counting and locating real solutions to polynomial systems
**********************************************************************************************

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

This package provides general tools for elimination and solving systems of
polynomial equations, with a particular emphasis on real solutions.

Acknowledgement
===============

This package is an updated version the realroots package by Grayson and
Sottile.

Authors
=======

  * Jordy Lopez Garcia (see https://jordylopez27.github.io/ )
    <jordy.lopez@tamu.edu>
  * Kelly Maluccio (see https://www.github.com/kmaluccio/ )
    <kmaluccio@gmail.com>
  * Frank Sottile (see https://franksottile.github.io/ ) <sottile@tamu.edu>
  * Thomas Yahl (see https://tjyahl.github.io/ ) <tyahl@wisc.edu>

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

Version 1.0 of this package was accepted for publication in volume 14 (see
https://msp.org/jsag/2024/14-1/ ) of Journal of Software for Algebra and
Geometry (see https://msp.org/jsag/ ) on 2024-03-18, in the article Real
solutions to systems of polynomial equations in Macaulay2 (see
https://msp.org/jsag/2024/14-1/p10.xhtml ) (DOI: 10.2140/jsag.2024.14.87 (see
https://doi.org/10.2140/jsag.2024.14.87 )). That version can be obtained from
the journal (see https://msp.org/jsag/2024/14-1/jsag-v14-n1-x10-RealRoots.m2 ).

Version
=======

This documentation describes version 1.1 of RealRoots, released Oct 9, 2020.

Citation
========

If you have used this package in your research, please cite it as follows:

+-----------------------------------------------------------------------------+
|@misc{RealRootsSource,                                                       |
|  title = {{RealRoots: A \emph{Macaulay2} package. Version~1.1}},            |
|  author = {Jordy Lopez Garcia and Kelly Maluccio and Frank Sottile and Thoma|
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}} |
|}                                                                            |
|                                                                             |
|@article{RealRootsArticle,                                                   |
|  title = {{Real solutions to systems of polynomial equations in \emph{Macaul|
|  author = {Jordy Lopez Garcia and Kelly Maluccio and Frank Sottile and Thoma|
|  journal = {Journal of Software for Algebra and Geometry},                  |
|  volume = {14},                                                             |
|  year = {2024},                                                             |
|}                                                                            |
|-----------------------------------------------------------------------------|
|s Yahl},                                                                     |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ay2}}},                                                                      |
|s Yahl},                                                                     |
+-----------------------------------------------------------------------------+

Exports
=======

  * Functions and commands
      * budanFourierBound -- a bound for the number
        of real roots with multiplicity of a univariate polynomial with
        rational coefficients
      * characteristicPolynomial -- the
        characteristic polynomial of a matrix or the characteristic polynomial
        of the regular representation of a polynomial
      * hurwitzMatrix -- the principal submatrix of the
        Hurwitz matrix of a univariate polynomial
      * isHurwitzStable -- determines if a univariate
        polynomial with rational coefficients is Hurwitz-stable
      * minimalPolynomial -- the minimal polynomial
        of an element of an Artinian ring
      * rationalUnivariateRepresentation
        -- the rational univariate
        representation of a zero-dimensional ideal in a polynomial ring
      * realCount -- the number of real points of the
        spectrum of an Artinian ring (of characteristic 0)
      * realRootIsolation -- a list that isolates the
        real roots of a univariate polynomial with rational coefficients
      * regularRepresentation -- the regular
        representation of an element of an Artinian ring
      * signature -- the signature of a symmetric matrix with
        rational entries
      * sturmCount -- the number of real roots of a
        univariate polynomial with rational coefficients
      * sturmSequence -- the Sturm sequence of a
        univariate polynomial with rational coefficients
      * sylvesterCount -- a signed count of the real
        roots of a univariate polynomial with rational coefficients
      * sylvesterSequence -- the Sylvester sequence
        of two univariate polynomials with rational coefficients
      * traceCount -- the degree of the reduced scheme of an
        Artinian ring
      * traceForm -- the trace symmetric form of a polynomial
        in an Artinian ring
      * univariateEliminant -- the univariate
        eliminant of an element of an Artinian ring
      * variations -- the number of sign changes of an
        ordered list of numbers
  * Methods
      * "budanFourierBound(RingElement)" -- see budanFourierBound,
        -- a bound for the number of real roots with
        multiplicity of a univariate polynomial with rational coefficients
      * "budanFourierBound(RingElement,QQ,QQ)" -- see budanFourierBound,
        -- a bound for the number of real roots with
        multiplicity of a univariate polynomial with rational coefficients
      * "characteristicPolynomial(Matrix)" -- see
        characteristicPolynomial, -- the
        characteristic polynomial of a matrix or the characteristic polynomial
        of the regular representation of a polynomial
      * "characteristicPolynomial(RingElement)" -- see
        characteristicPolynomial, -- the
        characteristic polynomial of a matrix or the characteristic polynomial
        of the regular representation of a polynomial
      * "characteristicPolynomial(RingElement,Ideal)" -- see
        characteristicPolynomial, -- the
        characteristic polynomial of a matrix or the characteristic polynomial
        of the regular representation of a polynomial
      * "hurwitzMatrix(RingElement)" -- see hurwitzMatrix,
        -- the principal submatrix of the Hurwitz matrix of a univariate
        polynomial
      * "hurwitzMatrix(RingElement,ZZ)" -- see hurwitzMatrix,
        -- the principal submatrix of the Hurwitz matrix of a
        univariate polynomial
      * "isHurwitzStable(RingElement)" -- see isHurwitzStable,
        -- determines if a univariate polynomial with rational
        coefficients is Hurwitz-stable
      * "minimalPolynomial(RingElement)" -- see minimalPolynomial,
        -- the minimal polynomial of an element of an
        Artinian ring
      * "minimalPolynomial(RingElement,Ideal)" -- see minimalPolynomial,
        -- the minimal polynomial of an element of an
        Artinian ring
      * "rationalUnivariateRepresentation(Ideal)" -- see
        rationalUnivariateRepresentation, --
        the rational univariate representation of a zero-dimensional ideal in a
        polynomial ring
      * "rationalUnivariateRepresentation(QuotientRing)" -- see
        rationalUnivariateRepresentation, --
        the rational univariate representation of a zero-dimensional ideal in a
        polynomial ring
      * "realCount(Ideal)" -- see realCount, -- the number of
        real points of the spectrum of an Artinian ring (of characteristic 0)
      * "realCount(List)" -- see realCount, -- the number of
        real points of the spectrum of an Artinian ring (of characteristic 0)
      * "realCount(QuotientRing)" -- see realCount, -- the
        number of real points of the spectrum of an Artinian ring (of
        characteristic 0)
      * "realCount(RingElement)" -- see realCount, -- the
        number of real points of the spectrum of an Artinian ring (of
        characteristic 0)
      * "realRootIsolation(RingElement,QQ)" -- see realRootIsolation,
        -- a list that isolates the real roots of a
        univariate polynomial with rational coefficients
      * "regularRepresentation(RingElement)" -- see
        regularRepresentation, -- the regular
        representation of an element of an Artinian ring
      * "regularRepresentation(RingElement,Ideal)" -- see
        regularRepresentation, -- the regular
        representation of an element of an Artinian ring
      * "signature(Matrix)" -- see signature, -- the signature
        of a symmetric matrix with rational entries
      * "sturmCount(RingElement)" -- see sturmCount, -- the
        number of real roots of a univariate polynomial with rational
        coefficients
      * "sturmCount(RingElement,QQ,QQ)" -- see sturmCount, --
        the number of real roots of a univariate polynomial with rational
        coefficients
      * "sturmSequence(RingElement)" -- see sturmSequence,
        -- the Sturm sequence of a univariate polynomial with rational
        coefficients
      * "sylvesterCount(RingElement,RingElement)" -- see sylvesterCount,
        -- a signed count of the real roots of a univariate
        polynomial with rational coefficients
      * "sylvesterCount(RingElement,RingElement,QQ,QQ)" -- see
        sylvesterCount, -- a signed count of the real roots of
        a univariate polynomial with rational coefficients
      * "sylvesterSequence(RingElement,RingElement)" -- see
        sylvesterSequence, -- the Sylvester sequence of two
        univariate polynomials with rational coefficients
      * "traceCount(Ideal)" -- see traceCount, -- the degree
        of the reduced scheme of an Artinian ring
      * "traceCount(List)" -- see traceCount, -- the degree
        of the reduced scheme of an Artinian ring
      * "traceCount(QuotientRing)" -- see traceCount, -- the
        degree of the reduced scheme of an Artinian ring
      * "traceCount(RingElement)" -- see traceCount, -- the
        degree of the reduced scheme of an Artinian ring
      * "traceForm(RingElement)" -- see traceForm, -- the
        trace symmetric form of a polynomial in an Artinian ring
      * "traceForm(RingElement,Ideal)" -- see traceForm, --
        the trace symmetric form of a polynomial in an Artinian ring
      * "univariateEliminant(RingElement,Ideal)" -- see
        univariateEliminant, -- the univariate eliminant
        of an element of an Artinian ring
      * "variations(List)" -- see variations, -- the number
        of sign changes of an ordered list of numbers
  * Symbols
      * Multiplicity

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

The object RealRoots, is a package (Macaulay2Doc),
defined in RealRoots.m2.

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:634:0.

budanFourierBound -- a bound for the number of real roots with multiplicity of a univariate polynomial with rational coefficients
*********************************************************************************************************************************

  * Usage:
        budanFourierBound(f, a, b)
        budanFourierBound(f)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a univariate
        polynomial with rational coefficients, where ring f is not necessarily
        univariate
      * a, a rational number (Macaulay2Doc), the left endpoint of the
        interval
      * b, a rational number (Macaulay2Doc), the right endpoint of
        the interval
  * Outputs:
      * an integer (Macaulay2Doc), the bound for the number of real
        roots in the interval (a,b], counted with multiplicity, of a univariate
        polynomial f with rational coefficients

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

This computes the bound from the Budan-Fourier Theorem for the number of real
roots in the interval (a,b], counted with multiplicity, of a univariate
polynomial f with rational coefficients. It assumes an unspecified interval is
$(-\infty, \infty)$. Note that ring f is allowed to be multivariate.

+----------------------------------------------------------+
|i1 : R = QQ[t]                                            |
|                                                          |
|o1 = R                                                    |
|                                                          |
|o1 : PolynomialRing                                       |
+----------------------------------------------------------+
|i2 : f = 45 - 39*t - 34*t^2 + 38*t^3 - 11*t^4 + t^5       |
|                                                          |
|      5      4      3      2                              |
|o2 = t  - 11t  + 38t  - 34t  - 39t + 45                   |
|                                                          |
|o2 : R                                                    |
+----------------------------------------------------------+
|i3 : budanFourierBound(f)                                 |
|                                                          |
|o3 = 5                                                    |
+----------------------------------------------------------+
|i4 : g = (t + 5)*(t + 3)*(t + 1)*(t - 1)^2*(t - 4)*(t - 6)|
|                                                          |
|      7     6      5      4       3       2               |
|o4 = t  - 3t  - 40t  + 86t  + 357t  - 443t  - 318t + 360  |
|                                                          |
|o4 : R                                                    |
+----------------------------------------------------------+
|i5 : budanFourierBound(g,-6,infinity)                     |
|                                                          |
|o5 = 7                                                    |
+----------------------------------------------------------+
|i6 : budanFourierBound(g,-1,5)                            |
|                                                          |
|o6 = 3                                                    |
+----------------------------------------------------------+

We also provide examples when the interval includes $-\infty$ or $\infty$.

+--------------------------------------------+
|i7 : budanFourierBound(g,-infinity,0)       |
|                                            |
|o7 = 3                                      |
+--------------------------------------------+
|i8 : budanFourierBound(g,3,infinity)        |
|                                            |
|o8 = 2                                      |
+--------------------------------------------+
|i9 : budanFourierBound(g,-infinity,infinity)|
|                                            |
|o9 = 7                                      |
+--------------------------------------------+

Ways to use budanFourierBound:
==============================

  * "budanFourierBound(RingElement)"
  * "budanFourierBound(RingElement,QQ,QQ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:930:0.

characteristicPolynomial -- the characteristic polynomial of a matrix or the characteristic polynomial of the regular representation of a polynomial
****************************************************************************************************************************************************

  * Usage:
        characteristicPolynomial(M)
        characteristicPolynomial(f)
        characteristicPolynomial(g,I)
  * Inputs:
      * M, a matrix (Macaulay2Doc), a square matrix
      * f, a ring element (Macaulay2Doc), an element of an
        Artinian ring
      * g, a ring element (Macaulay2Doc), a polynomial
      * I, an ideal (Macaulay2Doc), a zero-dimensional ideal in
        the polynomial ring containing g
  * Optional inputs (Macaulay2Doc),:
      * Variable => ..., default value "Z"
  * Outputs:
      * a ring element (Macaulay2Doc), the desired
        characteristic polynomial. See description.

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

This computes the characteristic polynomial of the matrix M, or the
characteristic polynomial of the regular representation of f on the Artinian
ring ring f, or the characteristic polynomial of the regular representation of
g on the Artinian ring (ring g)/I.

+--------------------------------+
|i1 : R = QQ[x,y]                |
|                                |
|o1 = R                          |
|                                |
|o1 : PolynomialRing             |
+--------------------------------+
|i2 : M = matrix{{2,1},{1,-1}}   |
|                                |
|o2 = | 2 1  |                   |
|     | 1 -1 |                   |
|                                |
|              2       2         |
|o2 : Matrix ZZ  <-- ZZ          |
+--------------------------------+
|i3 : characteristicPolynomial(M)|
|                                |
|      2                         |
|o3 = Z  - Z - 3                 |
|                                |
|o3 : ZZ[Z]                      |
+--------------------------------+

We can also change the variable name, as we show below.

+------------------------------------------------+
|i4 : characteristicPolynomial(M,Variable => "x")|
|                                                |
|      2                                         |
|o4 = x  - x - 3                                 |
|                                                |
|o4 : ZZ[x]                                      |
+------------------------------------------------+

We show the last two methods.

+-----------------------------------------------+
|i5 : I = ideal(y^2 - x^2 - 1,x - y^2 + 4*y - 2)|
|                                               |
|               2    2         2                |
|o5 = ideal (- x  + y  - 1, - y  + x + 4y - 2)  |
|                                               |
|o5 : Ideal of R                                |
+-----------------------------------------------+
|i6 : characteristicPolynomial(y,I)             |
|                                               |
|      4     3      2                           |
|o6 = Z  - 8Z  + 19Z  - 16Z + 5                 |
|                                               |
|o6 : QQ[Z]                                     |
+-----------------------------------------------+
|i7 : S = R/I                                   |
|                                               |
|o7 = S                                         |
|                                               |
|o7 : QuotientRing                              |
+-----------------------------------------------+
|i8 : characteristicPolynomial(y)               |
|                                               |
|      4     3      2                           |
|o8 = Z  - 8Z  + 19Z  - 16Z + 5                 |
|                                               |
|o8 : QQ[Z]                                     |
+-----------------------------------------------+

Ways to use characteristicPolynomial:
=====================================

  * "characteristicPolynomial(Matrix)"
  * "characteristicPolynomial(RingElement)"
  * "characteristicPolynomial(RingElement,Ideal)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:749:0.

hurwitzMatrix -- the principal submatrix of the Hurwitz matrix of a univariate polynomial
*****************************************************************************************

  * Usage:
        hurwitzMatrix(f,k)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a univariate
        polynomial of degree $n$ with rational coefficients
      * k, an integer (Macaulay2Doc), a nonnegative integer at most
        $n$
  * Outputs:
      * a matrix (Macaulay2Doc), the principal $k\times k$
        submatrix $H_{k}$

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

This computes the principal $k\times k$ submatrix $H_{k}$ of the Hurwitz matrix
$H$ of a univariate polynomial f of degree $n > 0$ with rational coefficients
whose leading coefficient is positive. Note that ring f is allowed to be
multivariate.

+--------------------------------+
|i1 : R = QQ[x]                  |
|                                |
|o1 = R                          |
|                                |
|o1 : PolynomialRing             |
+--------------------------------+
|i2 : f = 3*x^4 - 7*x^3 + 5*x - 7|
|                                |
|       4     3                  |
|o2 = 3x  - 7x  + 5x - 7         |
|                                |
|o2 : R                          |
+--------------------------------+
|i3 : hurwitzMatrix(f)           |
|                                |
|o3 = | -7 5  0  0  |            |
|     | 3  0  -7 0  |            |
|     | 0  -7 5  0  |            |
|     | 0  3  0  -7 |            |
|                                |
|              4       4         |
|o3 : Matrix QQ  <-- QQ          |
+--------------------------------+
|i4 : hurwitzMatrix(f,4)         |
|                                |
|o4 = | -7 5  0  0  |            |
|     | 3  0  -7 0  |            |
|     | 0  -7 5  0  |            |
|     | 0  3  0  -7 |            |
|                                |
|              4       4         |
|o4 : Matrix QQ  <-- QQ          |
+--------------------------------+
|i5 : hurwitzMatrix(f,3)         |
|                                |
|o5 = | -7 5  0  |               |
|     | 3  0  -7 |               |
|     | 0  -7 5  |               |
|                                |
|              3       3         |
|o5 : Matrix QQ  <-- QQ          |
+--------------------------------+

We can also use multiple variables to represent unknown coefficients. Note that
we create another ring S so that x and y are not considered variables in the
same ring and so confuse the monomials $x$ or $y$ with $xy$.

+--------------------------------+
|i6 : S = R[y]                   |
|                                |
|o6 = S                          |
|                                |
|o6 : PolynomialRing             |
+--------------------------------+
|i7 : g = y^3 + 2*y^2 + y - x + 1|
|                                |
|      3     2                   |
|o7 = y  + 2y  + y - x + 1       |
|                                |
|o7 : S                          |
+--------------------------------+
|i8 : hurwitzMatrix(g,3)         |
|                                |
|o8 = | 2 -x+1 0    |            |
|     | 1 1    0    |            |
|     | 0 2    -x+1 |            |
|                                |
|             3      3           |
|o8 : Matrix R  <-- R            |
+--------------------------------+
|i9 : hurwitzMatrix(g,2)         |
|                                |
|o9 = | 2 -x+1 |                 |
|     | 1 1    |                 |
|                                |
|             2      2           |
|o9 : Matrix R  <-- R            |
+--------------------------------+
|i10 : hurwitzMatrix(g,1)        |
|                                |
|o10 = | 2 |                     |
|                                |
|              1      1          |
|o10 : Matrix R  <-- R           |
+--------------------------------+

See also
========

  * isHurwitzStable -- determines if a univariate
    polynomial with rational coefficients is Hurwitz-stable

Ways to use hurwitzMatrix:
==========================

  * "hurwitzMatrix(RingElement)"
  * "hurwitzMatrix(RingElement,ZZ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:1111:0.

isHurwitzStable -- determines if a univariate polynomial with rational coefficients is Hurwitz-stable
*****************************************************************************************************

  * Usage:
        isHurwitzStable(f)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a univariate
        polynomial with rational coefficients
  * Outputs:
      * a Boolean value (Macaulay2Doc), the Hurwitz stability of
        the polynomial f

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

A real univariate polynomial is Hurwitz-stable if all its roots have negative
real parts. This method determines the Hurwitz stability of a univariate
polynomial f of degree $n>0$ with rational coefficients whose leading
coefficient is positive. Note that ring f is allowed to be multivariate.

+---------------------------------+
|i1 : R = QQ[x]                   |
|                                 |
|o1 = R                           |
|                                 |
|o1 : PolynomialRing              |
+---------------------------------+
|i2 : f = 3*x^4 - 7*x^3 + 5*x - 7 |
|                                 |
|       4     3                   |
|o2 = 3x  - 7x  + 5x - 7          |
|                                 |
|o2 : R                           |
+---------------------------------+
|i3 : g = x^2 + 10*x + 21         |
|                                 |
|      2                          |
|o3 = x  + 10x + 21               |
|                                 |
|o3 : R                           |
+---------------------------------+
|i4 : isHurwitzStable(f)          |
|                                 |
|o4 = false                       |
+---------------------------------+
|i5 : isHurwitzStable(g)          |
|                                 |
|o5 = true                        |
+---------------------------------+

See also
========

  * hurwitzMatrix -- the principal submatrix of the
    Hurwitz matrix of a univariate polynomial

Ways to use isHurwitzStable:
============================

  * "isHurwitzStable(RingElement)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:1129:0.

minimalPolynomial -- the minimal polynomial of an element of an Artinian ring
*****************************************************************************

  * Usage:
        minimalPolynomial(f)
        minimalPolynomial(g,I)
  * Inputs:
      * f, a ring element (Macaulay2Doc), an element of an
        Artinian ring
      * g, a ring element (Macaulay2Doc), a polynomial
      * I, an ideal (Macaulay2Doc), a zero-dimensional ideal in a
        polynomial ring
  * Optional inputs (Macaulay2Doc),:
      * Strategy => ..., default value 0, set method for computing the minimal
        polynomial
      * Variable => ..., default value "Z", allows user to change the variable
        of the resulting polynomial
  * Outputs:
      * a ring element (Macaulay2Doc), the desired minimal
        polynomial. See description

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

This computes the minimal polynomial of a ring element f in the Artinian ring
ring f, or the minimal polynomial of a polynomial g in the Artinian ring (ring
g)/I. When f is a variable in ring f, this is the eliminant with respect to
that variable.

+-----------------------------------------------+
|i1 : R = QQ[x,y]                               |
|                                               |
|o1 = R                                         |
|                                               |
|o1 : PolynomialRing                            |
+-----------------------------------------------+
|i2 : I = ideal(y^2 - x^2 - 1,x - y^2 + 4*y - 2)|
|                                               |
|               2    2         2                |
|o2 = ideal (- x  + y  - 1, - y  + x + 4y - 2)  |
|                                               |
|o2 : Ideal of R                                |
+-----------------------------------------------+
|i3 : minimalPolynomial(y,I)                    |
|                                               |
|      4     3      2                           |
|o3 = Z  - 8Z  + 19Z  - 16Z + 5                 |
|                                               |
|o3 : QQ[Z]                                     |
+-----------------------------------------------+
|i4 : S = R/I                                   |
|                                               |
|o4 = S                                         |
|                                               |
|o4 : QuotientRing                              |
+-----------------------------------------------+
|i5 : minimalPolynomial(y)                      |
|                                               |
|      4     3      2                           |
|o5 = Z  - 8Z  + 19Z  - 16Z + 5                 |
|                                               |
|o5 : QQ[Z]                                     |
+-----------------------------------------------+

We provide two examples to compute minimal polynomials given by Strategy => 0
(computes the kernel of $k[T]\to$ ring f by sending $T$ to f) and Strategy => 1
(a minimal linear combination of powers of the input).

+---------------------------------------+
|i6 : minimalPolynomial(x,Strategy => 0)|
|                                       |
|      4     3     2                    |
|o6 = Z  - 2Z  - 9Z  - 6Z - 7           |
|                                       |
|o6 : QQ[Z]                             |
+---------------------------------------+
|i7 : minimalPolynomial(x,Strategy => 1)|
|                                       |
|      4     3     2                    |
|o7 = Z  - 2Z  - 9Z  - 6Z - 7           |
|                                       |
|o7 : QQ[Z]                             |
+---------------------------------------+

See also
========

  * univariateEliminant -- the univariate eliminant
    of an element of an Artinian ring

Ways to use minimalPolynomial:
==============================

  * "minimalPolynomial(RingElement)"
  * "minimalPolynomial(RingElement,Ideal)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:664:0.

Multiplicity
************

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

This is a symbol for counting roots with multiplicity.

Functions with optional argument named Multiplicity:
====================================================

  * "sturmCount(...,Multiplicity=>...)" -- see Multiplicity(RealRoots),
  * "sylvesterCount(...,Multiplicity=>...)" -- see
    Multiplicity(RealRoots),

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

The object Multiplicity, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:829:0.

Multiplicity(RealRoots)
***********************

This is an optional input for counting roots with multiplicity.

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:824:0.

rationalUnivariateRepresentation -- the rational univariate representation of a zero-dimensional ideal in a polynomial ring
***************************************************************************************************************************

  * Usage:
        rationalUnivariateRepresentation(I)
        rationalUnivariateRepresentation(S)
  * Inputs:
      * I, an ideal (Macaulay2Doc), a zero-dimensional ideal in a
        polynomial ring
      * S, a quotient ring (Macaulay2Doc), an Artinian ring
        as a quotient of a polynomial ring
  * Outputs:
      * a list (Macaulay2Doc), the rational univariate
        representation of I or the rational univariate representation of S

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

This computes the rational univariate representation of a zero-dimensional
ideal in a polynomial ring.

+-----------------------------------------------+
|i1 : R = QQ[x,y]                               |
|                                               |
|o1 = R                                         |
|                                               |
|o1 : PolynomialRing                            |
+-----------------------------------------------+
|i2 : I = ideal(x*y - 1,2*x - y + 3)            |
|                                               |
|o2 = ideal (x*y - 1, 2x - y + 3)               |
|                                               |
|o2 : Ideal of R                                |
+-----------------------------------------------+
|i3 : rationalUnivariateRepresentation(I)       |
|                                               |
|              2   3        - 3Z + 15  6Z + 21  |
|o3 = (x + y, Z  - -Z - 9, {---------, -------})|
|                  2          4Z - 3    4Z - 3  |
|                                               |
|o3 : Sequence                                  |
+-----------------------------------------------+
|i4 : rationalUnivariateRepresentation(R/I)     |
|                                               |
|              2   3        - 3Z + 15  6Z + 21  |
|o4 = (x + y, Z  - -Z - 9, {---------, -------})|
|                  2          4Z - 3    4Z - 3  |
|                                               |
|o4 : Sequence                                  |
+-----------------------------------------------+

Ways to use rationalUnivariateRepresentation:
=============================================

  * "rationalUnivariateRepresentation(Ideal)"
  * "rationalUnivariateRepresentation(QuotientRing)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:1079:0.

realCount -- the number of real points of the spectrum of an Artinian ring (of characteristic 0)
************************************************************************************************

  * Usage:
        realCount(S)
  * Inputs:
      * S, a quotient ring (Macaulay2Doc), an Artinian ring
      * f, a ring element (Macaulay2Doc), a univariate
        polynomial
      * I, an ideal (Macaulay2Doc), a zero-dimensional ideal in
        the polynomial ring given by its variables
      * l, a list (Macaulay2Doc), generators of a zero-dimensional
        ideal
  * Outputs:
      * an integer (Macaulay2Doc), the number of distinct real points
        of Spec S, not counting multiplicity

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

This computes the number of distinct real points of Spec S, not counting
multiplicity. If f is a univariate polynomial (resp. if I is a zero-dimensional
ideal), this computes the number of real points of Spec R/(f) (resp. R/I),
where R is the ring generated by the variables that appear in f (resp. in I) to
allow for elimination of variables. If l is a list of generators of an ideal I,
then this computes the number of real points of Spec (R/I) as before.

If f is a univariate polynomial, then this counts its number of real roots.

+------------------------------------+
|i1 : R = QQ[x,y]                    |
|                                    |
|o1 = R                              |
|                                    |
|o1 : PolynomialRing                 |
+------------------------------------+
|i2 : f = (x^2 + 1)*(x + 1)*(x - 2)^2|
|                                    |
|      5     4    3    2             |
|o2 = x  - 3x  + x  + x  + 4         |
|                                    |
|o2 : R                              |
+------------------------------------+
|i3 : realCount(f)                   |
|                                    |
|o3 = 2                              |
+------------------------------------+

If I is a zero-dimensional ideal, this computes the number of distinct real
points of Spec R/I.

+--------------------------------------------------------------------------+
|i4 : I = ideal(5 - 3*x^2 - 3*y^2 + x^2*y^2, 1 + 2*x*y - 4*x*y^2 + 3*x^2*y)|
|                                                                          |
|             2 2     2     2        2        2                            |
|o4 = ideal (x y  - 3x  - 3y  + 5, 3x y - 4x*y  + 2x*y + 1)                |
|                                                                          |
|o4 : Ideal of R                                                           |
+--------------------------------------------------------------------------+
|i5 : realCount(I)                                                         |
|                                                                          |
|o5 = 4                                                                    |
+--------------------------------------------------------------------------+

If l is a system of rational polynomials, then this computes the number of
distinct real solutions.

+------------------------------------------+
|i6 : l = {y^2 - x^2 - 1,x - y^2 + 4*y - 2}|
|                                          |
|         2    2         2                 |
|o6 = {- x  + y  - 1, - y  + x + 4y - 2}   |
|                                          |
|o6 : List                                 |
+------------------------------------------+
|i7 : realCount(l)                         |
|                                          |
|o7 = 2                                    |
+------------------------------------------+

See also
========

  * traceForm -- the trace symmetric form of a polynomial in
    an Artinian ring
  * traceCount -- the degree of the reduced scheme of an
    Artinian ring

Ways to use realCount:
======================

  * "realCount(Ideal)"
  * "realCount(List)"
  * "realCount(QuotientRing)"
  * "realCount(RingElement)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:1059:0.

realRootIsolation -- a list that isolates the real roots of a univariate polynomial with rational coefficients
**************************************************************************************************************

  * Usage:
        realRootIsolation(f,r)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a univariate
        polynomial with rational coefficients
      * r, a rational number (Macaulay2Doc), a positive rational
        number
  * Outputs:
      * a list (Macaulay2Doc), of disjoint intervals

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

This computes disjoint intervals of length at most r, each containing exactly
one real root of f.

+---------------------------------------------------+
|i1 : R = QQ[t]                                     |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : f = 45 - 39*t - 34*t^2 + 38*t^3 - 11*t^4 + t^5|
|                                                   |
|      5      4      3      2                       |
|o2 = t  - 11t  + 38t  - 34t  - 39t + 45            |
|                                                   |
|o2 : R                                             |
+---------------------------------------------------+
|i3 : realRootIsolation(f,1/2)                      |
|                                                   |
|         3        1       5       9                |
|o3 = {{- -, -1}, {-, 1}, {-, 3}, {-, 5}}           |
|         2        2       2       2                |
|                                                   |
|o3 : List                                          |
+---------------------------------------------------+

See also
========

  * sturmSequence -- the Sturm sequence of a univariate
    polynomial with rational coefficients

Ways to use realRootIsolation:
==============================

  * "realRootIsolation(RingElement,QQ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:901:0.

regularRepresentation -- the regular representation of an element of an Artinian ring
*************************************************************************************

  * Usage:
        regularRepresentation(f)
        regularRepresentation(g,I)
  * Inputs:
      * f, a ring element (Macaulay2Doc), an element of an
        Artinian ring
      * g, a ring element (Macaulay2Doc), a rational
        polynomial
      * I, an ideal (Macaulay2Doc), a zero-dimensional ideal in
        the same ring as g
  * Outputs:
      * a matrix (Macaulay2Doc), the standard basis of ring f
        (resp. (ring g)/I)
      * a matrix (Macaulay2Doc), the matrix of the linear map
        defined by multiplication by f (resp. g) in ring f (resp. (ring g)/I)

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

This computes the matrix of the linear map defined by multiplication by f
(resp. g) in terms of the standard basis of the finite-dimensional vector space
ring f (resp. (ring g)/I).

+-----------------------------------------------+
|i1 : R = QQ[x,y]                               |
|                                               |
|o1 = R                                         |
|                                               |
|o1 : PolynomialRing                            |
+-----------------------------------------------+
|i2 : I = ideal(y^2 - x^2 - 1,x - y^2 + 4*y - 2)|
|                                               |
|               2    2         2                |
|o2 = ideal (- x  + y  - 1, - y  + x + 4y - 2)  |
|                                               |
|o2 : Ideal of R                                |
+-----------------------------------------------+
|i3 : regularRepresentation(y,I)                |
|                                               |
|o3 = (| 1 x xy y |, | 0 0 -3 -2 |)             |
|                    | 0 0 -1 1  |              |
|                    | 0 1 4  0  |              |
|                    | 1 0 4  4  |              |
|                                               |
|o3 : Sequence                                  |
+-----------------------------------------------+
|i4 : S = R/I                                   |
|                                               |
|o4 = S                                         |
|                                               |
|o4 : QuotientRing                              |
+-----------------------------------------------+
|i5 : regularRepresentation(y)                  |
|                                               |
|o5 = (| 1 x xy y |, | 0 0 -3 -2 |)             |
|                    | 0 0 -1 1  |              |
|                    | 0 1 4  0  |              |
|                    | 1 0 4  4  |              |
|                                               |
|o5 : Sequence                                  |
+-----------------------------------------------+

Ways to use regularRepresentation:
==================================

  * "regularRepresentation(RingElement)"
  * "regularRepresentation(RingElement,Ideal)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:715:0.

signature -- the signature of a symmetric matrix with rational entries
**********************************************************************

  * Usage:
        signature(M)
  * Inputs:
      * M, a matrix (Macaulay2Doc), a symmetric matrix with
        rational entries
  * Outputs:
      * an integer (Macaulay2Doc), the signature of M

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

This computes the signature of the symmetric matrix M with rational entries.

+--------------------------------------------------------+
|i1 : signature(matrix{{1,-2,3/5},{-2,-16,9},{3/5,9,13}})|
|                                                        |
|o1 = 1                                                  |
+--------------------------------------------------------+

Ways to use signature:
======================

  * "signature(Matrix)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:981:0.

sturmCount -- the number of real roots of a univariate polynomial with rational coefficients
********************************************************************************************

  * Usage:
        sturmCount(f,a,b)
        sturmCount(f)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a univariate
        polynomial with rational coefficients
      * a, a rational number (Macaulay2Doc), the left endpoint of the
        interval
      * b, a rational number (Macaulay2Doc), the right endpoint of
        the interval
  * Optional inputs (Macaulay2Doc),:
      * Multiplicity, => ..., default value
        false, option for computing roots with multiplicity
  * Outputs:
      * an integer (Macaulay2Doc), the number of real roots of f in
        the interval $(a,b]$

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

This computes the number of real roots in the interval $(a,b]$  of a univariate
polynomial f with rational coefficients. If a and b are not specified, this
computes the number of real roots of f. This is computed by taking the
difference in variation of the Sturm sequence of f.

+------------------------------------------+
|i1 : R = QQ[t]                            |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : f = (t - 5)*(t - 3)^2*(t - 1)*(t + 1)|
|                                          |
|      5      4      3      2              |
|o2 = t  - 11t  + 38t  - 34t  - 39t + 45   |
|                                          |
|o2 : R                                    |
+------------------------------------------+
|i3 : roots f                              |
|                                          |
|o3 = {-1, 1, 3, 3, 5}                     |
|                                          |
|o3 : List                                 |
+------------------------------------------+
|i4 : sturmCount(f)                        |
|                                          |
|o4 = 4                                    |
+------------------------------------------+
|i5 : sturmCount(f,0,5)                    |
|                                          |
|o5 = 3                                    |
+------------------------------------------+
|i6 : sturmCount(f,-2,2)                   |
|                                          |
|o6 = 2                                    |
+------------------------------------------+
|i7 : sturmCount(f,-1,5)                   |
|                                          |
|o7 = 3                                    |
+------------------------------------------+

In the above example, multiplicity is not counted. To include it, make the
multiplicity option true.

+--------------------------------------------+
|i8 : sturmCount(f,Multiplicity => true)     |
|                                            |
|o8 = 5                                      |
+--------------------------------------------+
|i9 : sturmCount(f,0,5,Multiplicity => true) |
|                                            |
|o9 = 4                                      |
+--------------------------------------------+
|i10 : sturmCount(f,0,3,Multiplicity => true)|
|                                            |
|o10 = 3                                     |
+--------------------------------------------+

We give examples with infinite intervals.

+--------------------------------------+
|i11 : sturmCount(f,-infinity, 0)      |
|                                      |
|o11 = 1                               |
+--------------------------------------+
|i12 : sturmCount(f,0,infinity)        |
|                                      |
|o12 = 3                               |
+--------------------------------------+
|i13 : sturmCount(f,-infinity,infinity)|
|                                      |
|o13 = 4                               |
+--------------------------------------+

See also
========

  * sturmSequence -- the Sturm sequence of a univariate
    polynomial with rational coefficients
  * sylvesterCount -- a signed count of the real roots
    of a univariate polynomial with rational coefficients

Ways to use sturmCount:
=======================

  * "sturmCount(RingElement)"
  * "sturmCount(RingElement,QQ,QQ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:868:0.

sturmSequence -- the Sturm sequence of a univariate polynomial with rational coefficients
*****************************************************************************************

  * Usage:
        sturmSequence(f)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a univariate
        polynomial with rational coefficients
  * Outputs:
      * a list (Macaulay2Doc), the Sturm sequence of f

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

This computes the Sturm sequence of the square-free part of a univariate
polynomial with rational coefficients f.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[t]                                                               |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : f = 45 - 39*t - 34*t^2 + 38*t^3 - 11*t^4 + t^5                          |
|                                                                             |
|      5      4      3      2                                                 |
|o2 = t  - 11t  + 38t  - 34t  - 39t + 45                                      |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+
|i3 : roots f                                                                 |
|                                                                             |
|o3 = {-1, 1, 3, 3, 5}                                                        |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : sturmSequence(f)                                                        |
|                                                                             |
|       4     3      2              3      2             104 2   432    232   |
|o4 = {t  - 8t  + 14t  + 8t - 15, 5t  - 29t  + 27t + 13, ---t  - ---t + ---,  |
|                                                         25      25     25   |
|     ------------------------------------------------------------------------|
|     3100    5300  194688                                                    |
|     ----t - ----, ------, 0}                                                |
|      169     169   24025                                                    |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * sturmCount -- the number of real roots of a univariate
    polynomial with rational coefficients
  * sylvesterSequence -- the Sylvester sequence of
    two univariate polynomials with rational coefficients

Ways to use sturmSequence:
==========================

  * "sturmSequence(RingElement)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:819:0.

sylvesterCount -- a signed count of the real roots of a univariate polynomial with rational coefficients
********************************************************************************************************

  * Usage:
        sylvesterCount(f,g,a,b)
        sylvesterCount(f,g)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a univariate
        polynomial with rational coefficients
      * g, a ring element (Macaulay2Doc), a univariate
        polynomial with rational coefficients in the same variable as f
      * a, a rational number (Macaulay2Doc), (optional) the left
        endpoint of the interval
      * b, a rational number (Macaulay2Doc), (optional) the right
        endpoint of the interval
  * Optional inputs (Macaulay2Doc),:
      * Multiplicity, => ..., default value
        false, option for computing roots with multiplicity
  * Outputs:
      * an integer (Macaulay2Doc), the difference between the number
        of real roots of f in the interval $(a,b]$ where g is positive, and the
        number of real roots of f in the interval $[a,b)$ where g is negative

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

This computes the difference between the number of real roots of  f in the
interval $(a,b]$ where g is positive, and the number of real roots of f in the
interval $[a,b)$ where g is negative. This is computed by taking the difference
in variations of the reduced Sylvester sequence of f and g.

+--------------------------------+
|i1 : R = QQ[t]                  |
|                                |
|o1 = R                          |
|                                |
|o1 : PolynomialRing             |
+--------------------------------+
|i2 : f = (t - 2)*(t - 1)*(t + 3)|
|                                |
|      3                         |
|o2 = t  - 7t + 6                |
|                                |
|o2 : R                          |
+--------------------------------+
|i3 : g = t + 1                  |
|                                |
|o3 = t + 1                      |
|                                |
|o3 : R                          |
+--------------------------------+
|i4 : a = -5                     |
|                                |
|o4 = -5                         |
+--------------------------------+
|i5 : b = 4                      |
|                                |
|o5 = 4                          |
+--------------------------------+
|i6 : sylvesterCount(f,g,a,b)    |
|                                |
|o6 = 1                          |
+--------------------------------+

See also
========

  * sylvesterSequence -- the Sylvester sequence of
    two univariate polynomials with rational coefficients
  * sturmCount -- the number of real roots of a univariate
    polynomial with rational coefficients

Ways to use sylvesterCount:
===========================

  * "sylvesterCount(RingElement,RingElement)"
  * "sylvesterCount(RingElement,RingElement,QQ,QQ)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:801:0.

sylvesterSequence -- the Sylvester sequence of two univariate polynomials with rational coefficients
****************************************************************************************************

  * Usage:
        sylvesterSequence(f,g)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a univariate
        polynomial with rational coefficients
      * g, a ring element (Macaulay2Doc), a univariate
        polynomial with rational coefficients in the same variable as f
  * Outputs:
      * a list (Macaulay2Doc), the reduced Sylvester sequence of f
        and g

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

This computes the reduced Sylvester sequence of two univariate polynomials with
rational coefficients f and g in the same ring. This begins with the Sylvester
sequence $(f_{0},f_{1},\dots,f_{k})$, where $f_{0} = f, f_{1} = f'\cdot g$ and
for $i\geq 1, f_{i+1} = -1\cdot$remainder $(f_{i-1},f_{i})$. The last nonzero
remainder $f_{k}$ is a greatest common divisor of $f$ and $g$. The reduced
Sylvester sequence is obtained by dividing each term of the Sylvester sequence
by $f_{k}$.

+---------------------------+
|i1 : R = QQ[t]             |
|                           |
|o1 = R                     |
|                           |
|o1 : PolynomialRing        |
+---------------------------+
|i2 : f = (t + 1)*(t + 2)   |
|                           |
|      2                    |
|o2 = t  + 3t + 2           |
|                           |
|o2 : R                     |
+---------------------------+
|i3 : g = t + 2             |
|                           |
|o3 = t + 2                 |
|                           |
|o3 : R                     |
+---------------------------+
|i4 : sylvesterSequence(f,g)|
|                           |
|                     1     |
|o4 = {t + 1, 2t + 3, -, 0} |
|                     2     |
|                           |
|o4 : List                  |
+---------------------------+

See also
========

  * sylvesterCount -- a signed count of the real roots
    of a univariate polynomial with rational coefficients
  * sturmSequence -- the Sturm sequence of a univariate
    polynomial with rational coefficients

Ways to use sylvesterSequence:
==============================

  * "sylvesterSequence(RingElement,RingElement)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:773:0.

traceCount -- the degree of the reduced scheme of an Artinian ring
******************************************************************

  * Usage:
        traceCount(S)
        traceCount(f)
        traceCount(I)
        traceCount(l)
  * Inputs:
      * S, a quotient ring (Macaulay2Doc), an Artinian ring
        over any field
      * f, a ring element (Macaulay2Doc), a univariate
        polynomial
      * I, an ideal (Macaulay2Doc), a zero-dimensional ideal in a
        polynomial ring
      * l, a list (Macaulay2Doc), a system of polynomials with a
        finite number of solutions
  * Outputs:
      * an integer (Macaulay2Doc), the degree of the reduced scheme
        of an Artinian ring

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

This computes the degree of the reduced scheme of an Artinian ring S over any
field, which is the number of distinct points of Spec S, after a base change to
an algebraically-closed field.

This counts the number of roots of a univariate polynomial f.

+------------------------------------+
|i1 : R = QQ[x,y]                    |
|                                    |
|o1 = R                              |
|                                    |
|o1 : PolynomialRing                 |
+------------------------------------+
|i2 : f = (x^2 + 1)*(x + 1)*(x - 2)^2|
|                                    |
|      5     4    3    2             |
|o2 = x  - 3x  + x  + x  + 4         |
|                                    |
|o2 : R                              |
+------------------------------------+
|i3 : traceCount(f)                  |
|                                    |
|o3 = 4                              |
+------------------------------------+

If I is a zero-dimensional ideal of a polynomial ring, this computes the number
of distinct points of Spec (ring I)/I.

+--------------------------------------------------------------------------+
|i4 : I = ideal(5 - 3*x^2 - 3*y^2 + x^2*y^2, 1 + 2*x*y - 4*x*y^2 + 3*x^2*y)|
|                                                                          |
|             2 2     2     2        2        2                            |
|o4 = ideal (x y  - 3x  - 3y  + 5, 3x y - 4x*y  + 2x*y + 1)                |
|                                                                          |
|o4 : Ideal of R                                                           |
+--------------------------------------------------------------------------+
|i5 : traceCount(I)                                                        |
|                                                                          |
|o5 = 8                                                                    |
+--------------------------------------------------------------------------+

If l is a system of rational polynomials, then this computes the number of
distinct solutions.

+------------------------------------------+
|i6 : l = {y^2 - x^2 - 1,x - y^2 + 4*y - 2}|
|                                          |
|         2    2         2                 |
|o6 = {- x  + y  - 1, - y  + x + 4y - 2}   |
|                                          |
|o6 : List                                 |
+------------------------------------------+
|i7 : traceCount(l)                        |
|                                          |
|o7 = 4                                    |
+------------------------------------------+

See also
========

  * traceForm -- the trace symmetric form of a polynomial in
    an Artinian ring
  * realCount -- the number of real points of the spectrum of
    an Artinian ring (of characteristic 0)

Ways to use traceCount:
=======================

  * "traceCount(Ideal)"
  * "traceCount(List)"
  * "traceCount(QuotientRing)"
  * "traceCount(RingElement)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:1021:0.

traceForm -- the trace symmetric form of a polynomial in an Artinian ring
*************************************************************************

  * Usage:
        traceForm(f)
        traceForm(g,I)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a polynomial in an
        Artinian ring
      * g, a ring element (Macaulay2Doc), a polynomial
      * I, an ideal (Macaulay2Doc), a zero-dimensional ideal in
        the polynomial ring containing g
  * Outputs:
      * a matrix (Macaulay2Doc), the symmetric matrix
        representing the trace symmetric form of f (resp. g) in ring f (resp.
        (ring g)/I)

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

This computes the symmetric matrix of the trace symmetric form of f (resp. g)
in terms of the standard basis of the finite-dimensional vector space ring f
(resp. (ring g)/I).

+------------------------------------------------+
|i1 : R = QQ[x,y]                                |
|                                                |
|o1 = R                                          |
|                                                |
|o1 : PolynomialRing                             |
+------------------------------------------------+
|i2 : I = ideal(y^2 - x^2 - 1, x - y^2 + 4*y - 2)|
|                                                |
|               2    2         2                 |
|o2 = ideal (- x  + y  - 1, - y  + x + 4y - 2)   |
|                                                |
|o2 : Ideal of R                                 |
+------------------------------------------------+
|i3 : S = R/I                                    |
|                                                |
|o3 = S                                          |
|                                                |
|o3 : QuotientRing                               |
+------------------------------------------------+
|i4 : f = y^2 - x^2 - x*y + 4                    |
|                                                |
|o4 = - x*y + 5                                  |
|                                                |
|o4 : S                                          |
+------------------------------------------------+
|i5 : traceForm(f)                               |
|                                                |
|o5 = | 4    -86   -340  -42   |                 |
|     | -86  -266  -1262 -340  |                 |
|     | -340 -1262 -5884 -1454 |                 |
|     | -42  -340  -1454 -262  |                 |
|                                                |
|              4       4                         |
|o5 : Matrix QQ  <-- QQ                          |
+------------------------------------------------+

We can also compute the signature of the trace form of g, which is the number
of real points in $V(J)$ where g is positive minus the number of real points in
$V(J)$ where g is negative.

+-----------------------------------------------+
|i6 : R = QQ[x,y]                               |
|                                               |
|o6 = R                                         |
|                                               |
|o6 : PolynomialRing                            |
+-----------------------------------------------+
|i7 : J = ideal(y^2 - x^2 - 1,x - y^2 + 4*y - 2)|
|                                               |
|               2    2         2                |
|o7 = ideal (- x  + y  - 1, - y  + x + 4y - 2)  |
|                                               |
|o7 : Ideal of R                                |
+-----------------------------------------------+
|i8 : g = x + y                                 |
|                                               |
|o8 = x + y                                     |
|                                               |
|o8 : R                                         |
+-----------------------------------------------+
|i9 : signature(traceForm(g,J))                 |
|                                               |
|o9 = 2                                         |
+-----------------------------------------------+

Additionally, we show an example computing the number of points in $V(I)$ using
the rank of the trace form.

+---------------------------------+
|i10 : rank traceForm(1_R,J)      |
|                                 |
|o10 = 4                          |
+---------------------------------+

See also
========

  * traceCount -- the degree of the reduced scheme of an
    Artinian ring
  * realCount -- the number of real points of the spectrum of
    an Artinian ring (of characteristic 0)
  * signature -- the signature of a symmetric matrix with
    rational entries

Ways to use traceForm:
======================

  * "traceForm(RingElement)"
  * "traceForm(RingElement,Ideal)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:967:0.

univariateEliminant -- the univariate eliminant of an element of an Artinian ring
*********************************************************************************

  * Usage:
        univariateEliminant(f)
        univariateEliminant(g,I)
  * Inputs:
      * f, a ring element (Macaulay2Doc), an element of an
        Artinian ring
      * g, a ring element (Macaulay2Doc), a polynomial
      * I, an ideal (Macaulay2Doc), a zero-dimensional ideal in
        the polynomial ring containing g
  * Optional inputs (Macaulay2Doc),:
      * Strategy => ..., default value 0, set method for computing the
        univariate eliminant
      * Variable => ..., default value "Z", allows user to change the variable
        of the resulting polynomial
  * Outputs:
      * a ring element (Macaulay2Doc), the desired
        univariate polynomial. See description

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

This computes the univariate eliminant of a ring element f in the Artinian ring
ring f, or the univariate eliminant of a polynomial g in the Artinian ring
(ring g)/I. When f is a variable in ring f, this is the eliminant with respect
to that variable. This is computed by finding the minimal polynomial of the
corresponding multiplication matrix.

+-----------------------------------------------+
|i1 : R = QQ[x,y]                               |
|                                               |
|o1 = R                                         |
|                                               |
|o1 : PolynomialRing                            |
+-----------------------------------------------+
|i2 : I = ideal(y^2 - x^2 - 1,x - y^2 + 4*y - 2)|
|                                               |
|               2    2         2                |
|o2 = ideal (- x  + y  - 1, - y  + x + 4y - 2)  |
|                                               |
|o2 : Ideal of R                                |
+-----------------------------------------------+
|i3 : univariateEliminant(y,I)                  |
|                                               |
|      4     3      2                           |
|o3 = Z  - 8Z  + 19Z  - 16Z + 5                 |
|                                               |
|o3 : QQ[Z]                                     |
+-----------------------------------------------+

We provide two examples to compute minimal polynomials given by Strategy => 0
(computes the kernel of $k[T]\to$ring f by sending $T$ to f) and Strategy => 1
(a minimal linear combination of powers of the input).

+-------------------------------------------+
|i4 : univariateEliminant(x,I,Strategy => 0)|
|                                           |
|      4     3     2                        |
|o4 = Z  - 2Z  - 9Z  - 6Z - 7               |
|                                           |
|o4 : QQ[Z]                                 |
+-------------------------------------------+
|i5 : univariateEliminant(x,I,Strategy => 1)|
|                                           |
|      4     3     2                        |
|o5 = Z  - 2Z  - 9Z  - 6Z - 7               |
|                                           |
|o5 : QQ[Z]                                 |
+-------------------------------------------+

See also
========

  * minimalPolynomial -- the minimal polynomial of an
    element of an Artinian ring

Ways to use univariateEliminant:
================================

  * "univariateEliminant(RingElement,Ideal)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:692:0.

variations -- the number of sign changes of an ordered list of numbers
**********************************************************************

  * Usage:
        variations(l)
  * Inputs:
      * l, a list (Macaulay2Doc),  of numbers
  * Outputs:
      * an integer (Macaulay2Doc), the number of sign changes in the
        ordered list l

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

This computes the number of sign changes in the ordered list l.

+----------------------------------------------------+
|i1 : L = for i to 10 list random(-50,50)            |
|                                                    |
|o1 = {-26, 15, 21, 22, -31, -31, 41, 22, 43, 29, 22}|
|                                                    |
|o1 : List                                           |
+----------------------------------------------------+
|i2 : variations(L)                                  |
|                                                    |
|o2 = 3                                              |
+----------------------------------------------------+

Ways to use variations:
=======================

  * "variations(List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in RealRoots.m2:883:0.