This is CoincidentRootLoci.info, produced by Macaulay2, version 1.20

CoincidentRootLoci -- A package for computations with coincident root loci
**************************************************************************

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

This package accompanies the paper On the algebraic boundaries among typical
ranks for real binary forms (see https://arxiv.org/abs/1804.08309 ) (see also
Algebraic boundaries among typical ranks for real binary forms of arbitrary
degree (see https://arxiv.org/abs/1911.01958 )). It provides some tools that
can be useful for working with symmetric tensors of dimension 2. Such tensors
are bijectively associated with homogeneous polynomials in two variables, which
are also called binary forms. One of the main methods is realrank,
which uses QEPCAD (see
https://www.usna.edu/CS/qepcadweb/B/QEPCAD.html ) to compute the real rank of
binary forms defined over $\mathbb{Q}$.

Contributors
============

  * Maria Chiara Brambilla <brambilla@dipmat.univpm.it>

Author
======

  * Giovanni Staglianò <giovannistagliano@gmail.com>

Version
=======

This documentation describes version 0.1.3 of CoincidentRootLoci.

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

The source code from which this documentation is derived is in the file
CoincidentRootLoci.m2 (see common/share/Macaulay2/CoincidentRootLoci.m2 ). The
auxiliary files accompanying it are in the directory CoincidentRootLoci/ (see
common/share/Macaulay2/CoincidentRootLoci/ ).

Exports
=======

  * Types
      * CoincidentRootLocus -- the class of all
        coincident root loci
  * Functions and commands
      * apolar -- the apolar map
      * coincidentRootLocus -- makes a coincident
        root locus
      * "projectiveJoin" -- see CoincidentRootLocus * CoincidentRootLocus,
        --
        projective join of coincident root loci
      * complexrank -- compute the complex rank
      * CRL (missing documentation)
      * "generic" -- see generic(CoincidentRootLocus),
        -- get the generic element
      * polarDegrees -- polar degrees of a coincident root
        locus
      * projectiveTangentSpace -- projective
        tangent space
      * randomBinaryForm -- random homogeneous
        polynomial in two variables
      * "randomInCoisotropic" -- see
        randomInCoisotropic(CoincidentRootLocus,ZZ),
        -- get a random
        element
      * realrank -- compute the real rank
      * realRankBoundary -- algebraic boundaries among
        typical ranks for real binary forms
      * realroots -- real roots of a binary form
      * recover -- recover the binary form from its apolar
        ideal
      * "supsets" -- see supsets(CoincidentRootLocus),
        -- produce all the suploci
  * Methods
      * "apolar(ZZ,ZZ)" -- see apolar, -- the apolar map
      * "apolar(ZZ,ZZ,Ring)" -- see apolar, -- the apolar map
      * apolar(RingElement) -- the apolar ideal
      * apolar(RingElement,ZZ), --
        homogeneous components of the apolar ideal
      * chowForm(CoincidentRootLocus),
        -- Chow form of a coincident root locus
      * codim(CoincidentRootLocus), --
        compute the codimension
      * coefficientRing(CoincidentRootLocus)
        -- get the coefficient ring
      * "coincidentRootLocus(List)" -- see coincidentRootLocus,
        -- makes a coincident root locus
      * "coincidentRootLocus(VisibleList,Ring)" -- see
        coincidentRootLocus, -- makes a coincident root
        locus
      * CoincidentRootLocus * CoincidentRootLocus
        -- projective join of coincident root loci
      * "complexrank(RingElement)" -- see complexrank, --
        compute the complex rank
      * degree(CoincidentRootLocus), --
        compute the degree
      * dim(CoincidentRootLocus), --
        compute the dimension
      * dual(CoincidentRootLocus) -- the
        projectively dual to a coincident root locus
      * generic(CoincidentRootLocus),
        -- get the generic element
      * ideal(CoincidentRootLocus), --
        the defining ideal of a coincident root locus
      * isInCoisotropic(Ideal,CoincidentRootLocus)
        -- test membership in
        a coisotropic hypersurface
      * isSubset(CoincidentRootLocus,CoincidentRootLocus)
        -- whether one
        object is a subset of another
      * map(CoincidentRootLocus) -- the
        map associated to a coincident root locus
      * member(RingElement,CoincidentRootLocus)
        -- test membership in a
        coincident root locus
      * partition(CoincidentRootLocus)
        -- the partition associated to a
        coincident root locus
      * "polarDegrees(CoincidentRootLocus)" -- see polarDegrees,
        -- polar degrees of a coincident root locus
      * "projectiveTangentSpace(CoincidentRootLocus,RingElement)" -- see
        projectiveTangentSpace, -- projective tangent
        space
      * random(CoincidentRootLocus), --
        get a random element
      * "randomBinaryForm(ZZ)" -- see randomBinaryForm,
        -- random homogeneous polynomial in two variables
      * "randomBinaryForm(ZZ,Ring)" -- see randomBinaryForm,
        -- random homogeneous polynomial in two variables
      * "randomBinaryForm(ZZ,Thing,Thing)" -- see randomBinaryForm,
        -- random homogeneous polynomial in two variables
      * "randomBinaryForm(ZZ,Thing,Thing,Ring)" -- see randomBinaryForm,
        -- random homogeneous polynomial in two variables
      * randomInCoisotropic(CoincidentRootLocus,ZZ)
        -- get a random
        element
      * "realrank(RingElement)" -- see realrank, -- compute the
        real rank
      * "realRankBoundary(ZZ,ZZ)" -- see realRankBoundary,
        -- algebraic boundaries among typical ranks for real
        binary forms
      * "realRankBoundary(ZZ,ZZ,Ring)" -- see realRankBoundary,
        -- algebraic boundaries among typical ranks for real
        binary forms
      * "realroots(RingElement)" -- see realroots, -- real
        roots of a binary form
      * "recover(Ideal)" -- see recover, -- recover the binary
        form from its apolar ideal
      * "recover(RingElement,RingElement)" -- see recover, --
        recover the binary form from its apolar ideal
      * ring(CoincidentRootLocus) -- get
        the ring of a coincident root locus
      * singularLocus(CoincidentRootLocus)
        -- the singular locus of a
        coincident root locus
      * subsets(CoincidentRootLocus),
        -- produce all the subloci
      * supsets(CoincidentRootLocus),
        -- produce all the suploci
      * "switch(Ideal)" -- see switch(RingElement),
      * "switch(List)" -- see switch(RingElement),
      * switch(RingElement)
  * Symbols
      * QepcadOptions -- set the number of cells in the
        garbage collected space

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

The object CoincidentRootLoci, is a package (Macaulay2Doc).

apolar -- the apolar map
************************

Synopsis
========

  * Usage:
        apolar(n,s,K)
        apolar(n,s)
  * Inputs:
      * n, an integer (Macaulay2Doc),
      * s, an integer (Macaulay2Doc),
      * K, a ring (Macaulay2Doc), the coefficient ring (optional
        with default value QQ (Macaulay2Doc))
  * Optional inputs (Macaulay2Doc),:
      * Variable,
        => ..., default value "t", specify a name for a variable
  * Outputs:
      * a rational map (Cremona), the map from
        $\mathbb{P}^n$ to $Grass(2s-n-1,s)$ that sends a generic binary form
        $F\in K[x,y]$ of degree $n$ to the set of binary forms of degree $s$
        that annihilate $F$, which can be identified with a
        $(2s-n-1)$-dimensional linear subspace of $\mathbb{P}^s$.

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

We illustrate two ways of using this method.

1. Given a binary form $F$ of degree $n$ we can obtain a basis for the space of
forms of degree $s$ that annihilate $F$, say for example $(n,s)=(6,4)$.

+-----------------------------------------------------------------------------+
|i1 : (n,s) = (6,4)                                                           |
|                                                                             |
|o1 = (6, 4)                                                                  |
|                                                                             |
|o1 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i2 : F = randomBinaryForm n                                                  |
|                                                                             |
|        6     5       4 2     3 3     2 4       5     6                      |
|o2 = 18t  + 2t t  + 9t t  + 2t t  + 4t t  + 3t t  + 6t                       |
|        0     0 1     0 1     0 1     0 1     0 1     1                      |
|                                                                             |
|o2 : QQ[t ..t ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i3 : phi = apolar(n,s)                                                       |
|                                                                             |
|o3 = -- rational map --                                                      |
|     source: Proj(QQ[t , t , t , t , t , t , t ])                            |
|                      0   1   2   3   4   5   6                              |
|     target: subvariety of Proj(QQ[t   , t   , t   , t   , t   , t   , t   , |
|                                    0,1   0,2   1,2   0,3   1,3   2,3   0,4  |
|             {                                                               |
|              t   t    - t   t    + t   t   ,                                |
|               2,3 1,4    1,3 2,4    1,2 3,4                                 |
|                                                                             |
|              t   t    - t   t    + t   t   ,                                |
|               2,3 0,4    0,3 2,4    0,2 3,4                                 |
|                                                                             |
|              t   t    - t   t    + t   t   ,                                |
|               1,3 0,4    0,3 1,4    0,1 3,4                                 |
|                                                                             |
|              t   t    - t   t    + t   t   ,                                |
|               1,2 0,4    0,2 1,4    0,1 2,4                                 |
|                                                                             |
|              t   t    - t   t    + t   t                                    |
|               1,2 0,3    0,2 1,3    0,1 2,3                                 |
|             }                                                               |
|     defining forms: {                                                       |
|                           3                   2      2                      |
|                      - 24t  + 48t t t  - 24t t  - 24t t  + 24t t t ,        |
|                           4      3 4 5      2 5      3 6      2 4 6         |
|                                                                             |
|                           2      2                     2                    |
|                      16t t  - 16t t  - 16t t t  + 16t t  + 16t t t  - 16t t |
|                         3 4      3 5      2 4 5      1 5      2 3 6      1 4|
|                                                                             |
|                            2                           2                    |
|                      - 4t t  + 4t t t  + 4t t t  - 4t t  - 4t t t  + 4t t t |
|                          2 4     2 3 5     1 4 5     0 5     1 3 6     0 4 6|
|                                                                             |
|                           2          2                            2         |
|                      - 24t t  + 24t t  + 24t t t  - 24t t t  - 24t t  + 24t |
|                           3 4      2 4      2 3 5      1 4 5      2 6      1|
|                                                                             |
|                                    2     2                                  |
|                      6t t t  - 6t t  - 6t t  + 6t t t  + 6t t t  - 6t t t , |
|                        2 3 4     1 4     2 5     0 4 5     1 2 6     0 3 6  |
|                                                                             |
|                          2                                     2            |
|                      - 4t t  + 4t t t  + 4t t t  - 4t t t  - 4t t  + 4t t t |
|                          2 4     1 3 4     1 2 5     0 3 5     1 6     0 2 6|
|                                                                             |
|                         3                    2      2                       |
|                      96t  - 192t t t  + 96t t  + 96t t  - 96t t t ,         |
|                         3       2 3 4      1 4      2 5      1 3 5          |
|                                                                             |
|                             2      2                     2                  |
|                      - 24t t  + 24t t  + 24t t t  - 24t t  - 24t t t  + 24t |
|                           2 3      2 4      1 3 4      0 4      1 2 5      0|
|                                                                             |
|                         2          2                            2           |
|                      16t t  - 16t t  - 16t t t  + 16t t t  + 16t t  - 16t t |
|                         2 3      1 3      1 2 4      0 3 4      1 5      0 2|
|                                                                             |
|                           3                   2      2                      |
|                      - 24t  + 48t t t  - 24t t  - 24t t  + 24t t t          |
|                           2      1 2 3      0 3      1 4      0 2 4         |
|                     }                                                       |
|                                                                             |
|o3 : RationalMap (cubic rational map from PP^6 to 6-dimensional subvariety of|
|-----------------------------------------------------------------------------|
|t   , t   , t   ]) defined by                                                |
| 1,4   2,4   3,4                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|t ,                                                                          |
| 6                                                                           |
|                                                                             |
|                                                                             |
|,                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|t t ,                                                                        |
| 3 6                                                                         |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|,                                                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|t t ,                                                                        |
| 3 5                                                                         |
|                                                                             |
|                                                                             |
|t ,                                                                          |
| 5                                                                           |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
| PP^9)                                                                       |
+-----------------------------------------------------------------------------+
|i4 : P = switch plucker phi switch switch F                                  |
|                                                                             |
|                  3          2 2           3        4        4          2 2  |
|o4 = ideal (20458t t  - 4533t t  - 52230t t  + 4213t , 10229t  - 325779t t  +|
|                  0 1        0 1         0 1        1        0          0 1  |
|     ------------------------------------------------------------------------|
|             3        4                                                      |
|     99734t t  + 5145t )                                                     |
|           0 1        1                                                      |
|                                                                             |
|o4 : Ideal of QQ[t ..t ]                                                     |
|                  0   1                                                      |
+-----------------------------------------------------------------------------+
|i5 : diff(gens P,F) == 0                                                     |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+

2. We can recover the form $F$ from the above output.

+-------------------------------------------------------+
|i6 : switch phi^* plucker switch P                     |
|                                                       |
|        6     5       4 2     3 3     2 4       5     6|
|o6 = 18t  + 2t t  + 9t t  + 2t t  + 4t t  + 3t t  + 6t |
|        0     0 1     0 1     0 1     0 1     0 1     1|
|                                                       |
|o6 : QQ[t ..t ]                                        |
|         0   1                                         |
+-------------------------------------------------------+
|i7 : oo == F                                           |
|                                                       |
|o7 = true                                              |
+-------------------------------------------------------+

See also
========

  * apolar(RingElement) -- the apolar ideal
  * apolar(RingElement,ZZ) -- homogeneous
    components of the apolar ideal
  * recover(Ideal) -- recover the binary form from its apolar
    ideal
  * switch(RingElement) (missing documentation)
  * plucker (Resultants) -- get the Plücker coordinates of a
    linear subspace

Ways to use apolar :
====================

  * "apolar(ZZ,ZZ)"
  * "apolar(ZZ,ZZ,Ring)"
  * apolar(RingElement) -- the apolar ideal
  * apolar(RingElement,ZZ) -- homogeneous
    components of the apolar ideal

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

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

apolar(RingElement) -- the apolar ideal
***************************************

Synopsis
========

  * Function: apolar,
  * Usage:
        apolar F
  * Inputs:
      * F, a ring element (Macaulay2Doc), a binary form
  * Optional inputs (Macaulay2Doc),:
      * Variable,
        => ..., default value "t", specify a name for a variable
  * Outputs:
      * an ideal (Macaulay2Doc), the ideal generated by all binary
        forms that annihilate $F$

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

+-----------------------------------------------------------------------------+
|i1 : F = randomBinaryForm 7                                                  |
|                                                                             |
|        7     6       5 2     4 3     3 4     2 5       6     7              |
|o1 = 18t  + 2t t  + 9t t  + 2t t  + 4t t  + 3t t  + 6t t  + 3t               |
|        0     0 1     0 1     0 1     0 1     0 1     0 1     1              |
|                                                                             |
|o1 : QQ[t ..t ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i2 : apolar F                                                                |
|                                                                             |
|                  4          3             2 2             3          4      |
|o2 = ideal (75621t  + 740842t t  - 3587636t t  - 2099787t t  + 741116t ,     |
|                  0          0 1           0 1           0 1          1      |
|     ------------------------------------------------------------------------|
|          3 2        2 3          4        5                                 |
|     1355t t  - 5785t t  - 3840t t  + 1321t )                                |
|          0 1        0 1        0 1        1                                 |
|                                                                             |
|o2 : Ideal of QQ[t ..t ]                                                     |
|                  0   1                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * apolar(RingElement,ZZ) -- homogeneous
    components of the apolar ideal
  * apolar(ZZ,ZZ) -- the apolar map

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

  * apolar(RingElement) -- the apolar ideal

apolar(RingElement,ZZ) -- homogeneous components of the apolar ideal
********************************************************************

Synopsis
========

  * Function: apolar,
  * Usage:
        apolar(F,s)
  * Inputs:
      * F, a ring element (Macaulay2Doc), a binary form
      * s, an integer (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Variable,
        => ..., default value "t", specify a name for a variable
  * Outputs:
      * an ideal (Macaulay2Doc), the ideal generated by the binary
        forms of degree $s$ that annihilate $F$

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

+-----------------------------------------------------------------------------+
|i1 : F = randomBinaryForm 7                                                  |
|                                                                             |
|        7     6       5 2     4 3     3 4     2 5       6     7              |
|o1 = 18t  + 2t t  + 9t t  + 2t t  + 4t t  + 3t t  + 6t t  + 3t               |
|        0     0 1     0 1     0 1     0 1     0 1     0 1     1              |
|                                                                             |
|o1 : QQ[t ..t ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i2 : apolar(F,4)                                                             |
|                                                                             |
|                 4          3             2 2             3          4       |
|o2 = ideal(75621t  + 740842t t  - 3587636t t  - 2099787t t  + 741116t )      |
|                 0          0 1           0 1           0 1          1       |
|                                                                             |
|o2 : Ideal of QQ[t ..t ]                                                     |
|                  0   1                                                      |
+-----------------------------------------------------------------------------+
|i3 : apolar(F,5)                                                             |
|                                                                             |
|                 3 2        2 3          4        5       4          2 3     |
|o3 = ideal (1355t t  - 5785t t  - 3840t t  + 1321t , 1355t t  - 7610t t  -   |
|                 0 1        0 1        0 1        1       0 1        0 1     |
|     ------------------------------------------------------------------------|
|         4       5      5         2 3           4         5                  |
|     5t t  + 338t , 271t  - 47505t t  - 33770t t  + 11872t )                 |
|       0 1       1      0         0 1         0 1         1                  |
|                                                                             |
|o3 : Ideal of QQ[t ..t ]                                                     |
|                  0   1                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * apolar(RingElement) -- the apolar ideal
  * apolar(ZZ,ZZ) -- the apolar map

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

  * apolar(RingElement,ZZ) -- homogeneous
    components of the apolar ideal

chowForm(CoincidentRootLocus) -- Chow form of a coincident root locus
*********************************************************************

Synopsis
========

  * Function: chowForm (Resultants),
  * Usage:
        chowForm X
  * Inputs:
      * X, a coincident root locus,
  * Optional inputs (Macaulay2Doc),:
      * AffineChartGrass (Resultants), => ..., default
        value true, null
      * AffineChartProj (Resultants), => ..., default
        value true, null
      * Duality (Resultants), => ..., default value null, null
      * Variable (Resultants),
        => ..., default value null, null
  * Outputs:
      * a ring element (Macaulay2Doc), the Chow form of $X$

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

This is equivalent to chowForm ideal X, but should be faster. See
chowForm(Ideal) (Resultants).

+-----------------------------------------------------------------------------+
|i1 : X = coincidentRootLocus {3,1}                                           |
|                                                                             |
|o1 = CRL(3,1)                                                                |
|                                                                             |
|o1 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i2 : chowForm X                                                              |
|                                                                             |
|        3   3                    3            2   3        2   4             |
|o2 = 16t   t    - 24t   t   t   t    + 32t   t   t    + 27t   t    -         |
|        1,2 2,3      0,2 1,2 1,3 2,3      0,1 1,3 2,3      0,2 2,3           |
|     ------------------------------------------------------------------------|
|                4                4        3                                  |
|     48t   t   t    - 36t   t   t    - 24t   t   t   t    +                  |
|        0,1 1,2 2,3      0,1 0,3 2,3      1,2 1,3 2,3 2,4                    |
|     ------------------------------------------------------------------------|
|                2                    3                   2   2               |
|     36t   t   t   t   t    - 48t   t   t   t    + 6t   t   t   t    -       |
|        0,2 1,2 1,3 2,3 2,4      0,1 1,3 2,3 2,4     0,2 1,2 2,3 2,4         |
|     ------------------------------------------------------------------------|
|        2       2                        2                        2          |
|     42t   t   t   t    + 60t   t   t   t   t    + 56t   t   t   t   t    +  |
|        0,2 1,3 2,3 2,4      0,1 1,2 1,3 2,3 2,4      0,1 0,3 1,3 2,3 2,4    |
|     ------------------------------------------------------------------------|
|               3            4   2            2       2       2   2   2       |
|     6t   t   t   t    + 27t   t    - 42t   t   t   t    - 9t   t   t    +   |
|       0,1 0,2 2,3 2,4      1,2 2,4      0,2 1,2 1,3 2,4     0,2 1,3 2,4     |
|     ------------------------------------------------------------------------|
|                2   2                2   2        2           2              |
|     72t   t   t   t    + 12t   t   t   t    + 48t   t   t   t    -          |
|        0,1 1,2 1,3 2,4      0,1 0,3 1,3 2,4      0,2 1,2 2,3 2,4            |
|     ------------------------------------------------------------------------|
|            2       2        2           2            2       2              |
|     90t   t   t   t    + 12t   t   t   t    - 16t   t   t   t    -          |
|        0,1 1,2 2,3 2,4      0,2 0,3 2,3 2,4      0,1 0,3 2,3 2,4            |
|     ------------------------------------------------------------------------|
|                        2        2   2   2        2           2              |
|     84t   t   t   t   t    + 87t   t   t    + 12t   t   t   t    -          |
|        0,1 0,2 1,3 2,3 2,4      0,1 2,3 2,4      0,2 1,2 1,4 2,4            |
|     ------------------------------------------------------------------------|
|            2       2                        2       2   2   2        3   3  |
|     18t   t   t   t    - 18t   t   t   t   t    + 3t   t   t    - 16t   t   |
|        0,1 1,2 1,4 2,4      0,1 0,2 1,3 1,4 2,4     0,1 1,4 2,4      0,2 2,4|
|     ------------------------------------------------------------------------|
|                      3                    3       2       3                 |
|     + 36t   t   t   t    + 24t   t   t   t    - 2t   t   t    -             |
|          0,1 0,2 1,2 2,4      0,1 0,2 0,3 2,4     0,1 1,3 2,4               |
|     ------------------------------------------------------------------------|
|       2       3        3   2                    3                4          |
|     4t   t   t    + 32t   t   t    - 48t   t   t   t    + 64t   t   t    -  |
|       0,1 0,4 2,4      1,2 1,3 3,4      0,2 1,2 1,3 3,4      0,1 1,3 3,4    |
|     ------------------------------------------------------------------------|
|        4                    2                    2   2                      |
|     48t   t   t    + 60t   t   t   t   t    + 72t   t   t   t    -          |
|        1,2 2,3 3,4      0,2 1,2 1,3 2,3 3,4      0,2 1,3 2,3 3,4            |
|     ------------------------------------------------------------------------|
|                 2                        2                2       2         |
|     192t   t   t   t   t    - 96t   t   t   t   t    - 90t   t   t   t    + |
|         0,1 1,2 1,3 2,3 3,4      0,1 0,3 1,3 2,3 3,4      0,2 1,2 2,3 3,4   |
|     ------------------------------------------------------------------------|
|             2   2            2       2                2   2                 |
|     168t   t   t   t    - 18t   t   t   t    + 24t   t   t   t    +         |
|         0,1 1,2 2,3 3,4      0,2 0,3 2,3 3,4      0,1 0,3 2,3 3,4           |
|     ------------------------------------------------------------------------|
|                     2             2   3            4                        |
|     136t   t   t   t   t    - 160t   t   t    - 36t   t   t    +            |
|         0,1 0,2 1,3 2,3 3,4       0,1 2,3 3,4      1,2 1,4 3,4              |
|     ------------------------------------------------------------------------|
|            2                    2   2                        2              |
|     56t   t   t   t   t    + 12t   t   t   t    - 96t   t   t   t   t    -  |
|        0,2 1,2 1,3 1,4 3,4      0,2 1,3 1,4 3,4      0,1 1,2 1,3 1,4 3,4    |
|     ------------------------------------------------------------------------|
|                2                2       2                2   2              |
|     16t   t   t   t   t    - 16t   t   t   t    + 24t   t   t   t    +      |
|        0,1 0,3 1,3 1,4 3,4      0,2 1,2 1,4 3,4      0,1 1,2 1,4 3,4        |
|     ------------------------------------------------------------------------|
|                    2           2   3               3                        |
|     24t   t   t   t   t    - 4t   t   t    + 6t   t   t   t    -            |
|        0,1 0,2 1,3 1,4 3,4     0,1 1,4 3,4     0,2 1,2 2,4 3,4              |
|     ------------------------------------------------------------------------|
|        2                             2                                      |
|     84t   t   t   t   t    + 136t   t   t   t   t    -                      |
|        0,2 1,2 1,3 2,4 3,4       0,1 1,2 1,3 2,4 3,4                        |
|     ------------------------------------------------------------------------|
|        2                            2                                       |
|     18t   t   t   t   t    + 24t   t   t   t   t    +                       |
|        0,2 0,3 1,3 2,4 3,4      0,1 0,3 1,3 2,4 3,4                         |
|     ------------------------------------------------------------------------|
|                 2                3                                          |
|     144t   t   t   t   t    + 36t   t   t   t    -                          |
|         0,1 0,2 1,3 2,4 3,4      0,2 2,3 2,4 3,4                            |
|     ------------------------------------------------------------------------|
|                                                                             |
|     78t   t   t   t   t   t    - 52t   t   t   t   t   t    -               |
|        0,1 0,2 1,2 2,3 2,4 3,4      0,1 0,2 0,3 2,3 2,4 3,4                 |
|     ------------------------------------------------------------------------|
|        2                        3                                           |
|     96t   t   t   t   t    + 24t   t   t   t    - 52t   t   t   t   t   t   |
|        0,1 1,3 2,3 2,4 3,4      0,2 1,4 2,4 3,4      0,1 0,2 1,2 1,4 2,4 3,4|
|     ------------------------------------------------------------------------|
|                                      2                                      |
|     - 36t   t   t   t   t   t    + 6t   t   t   t   t    -                  |
|          0,1 0,2 0,3 1,4 2,4 3,4     0,1 0,4 1,4 2,4 3,4                    |
|     ------------------------------------------------------------------------|
|        2       2           2       2            2   2   2                   |
|     28t   t   t   t    + 6t   t   t   t    + 87t   t   t    -               |
|        0,1 1,2 2,4 3,4     0,1 0,3 2,4 3,4      0,2 1,2 3,4                 |
|     ------------------------------------------------------------------------|
|             3   2       2   2   2           3   2       3       2           |
|     160t   t   t    + 3t   t   t    - 4t   t   t    - 2t   t   t    -       |
|         0,1 1,2 3,4     0,2 0,3 3,4     0,1 0,3 3,4     0,2 1,3 3,4         |
|     ------------------------------------------------------------------------|
|                        2        2   2   2            2       2              |
|     96t   t   t   t   t    - 48t   t   t    - 28t   t   t   t    +          |
|        0,1 0,2 1,2 1,3 3,4      0,1 1,3 3,4      0,1 0,2 2,3 3,4            |
|     ------------------------------------------------------------------------|
|         2           2        2           2       3       2                  |
|     192t   t   t   t    + 48t   t   t   t    - 4t   t   t    +              |
|         0,1 1,2 2,3 3,4      0,1 0,3 2,3 3,4     0,2 0,4 3,4                |
|     ------------------------------------------------------------------------|
|                       2      2   2   2           2       2                  |
|     6t   t   t   t   t    - t   t   t    + 6t   t   t   t    +              |
|       0,1 0,2 0,3 0,4 3,4    0,1 0,4 3,4     0,1 0,2 1,4 3,4                |
|     ------------------------------------------------------------------------|
|        2           2       2           2        2           2        3   3  |
|     48t   t   t   t    - 4t   t   t   t    - 18t   t   t   t    + 12t   t   |
|        0,1 1,2 1,4 3,4     0,1 0,3 1,4 3,4      0,1 0,2 2,4 3,4      0,1 3,4|
|                                                                             |
|                                                      QQ[t   ..t   , t   , t |
|                                                          0,1   0,2   1,2   0|
|o2 : ------------------------------------------------------------------------|
|     (t   t    - t   t    + t   t   , t   t    - t   t    + t   t   , t   t  |
|       2,3 1,4    1,3 2,4    1,2 3,4   2,3 0,4    0,3 2,4    0,2 3,4   1,3 0,|
|-----------------------------------------------------------------------------|
|  , t   , t   , t   , t   , t   , t   ]                                      |
|,3   1,3   2,3   0,4   1,4   2,4   3,4                                       |
|-----------------------------------------------------------------------------|
|  - t   t    + t   t   , t   t    - t   t    + t   t   , t   t    - t   t    |
|4    0,3 1,4    0,1 3,4   1,2 0,4    0,2 1,4    0,1 2,4   1,2 0,3    0,2 1,3 |
|-----------------------------------------------------------------------------|
|-----------                                                                  |
|+ t   t   )                                                                  |
|   0,1 2,3                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * chowForm(Ideal) (Resultants) -- Chow form of a projective
    variety

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

  * chowForm(CoincidentRootLocus), --
    Chow form of a coincident root locus

codim(CoincidentRootLocus) -- compute the codimension
*****************************************************

Synopsis
========

  * Function: codim (Macaulay2Doc),
  * Usage:
        codim X
  * Inputs:
      * X, a coincident root locus,
  * Outputs:
      * an integer (Macaulay2Doc), the codimension of X as a
        projective variety

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

+--------------------------------------------+
|i1 : X = coincidentRootLocus {3,2,2,1,1,1,1}|
|                                            |
|o1 = CRL(3,2,2,1,1,1,1)                     |
|                                            |
|o1 : Coincident root locus                  |
+--------------------------------------------+
|i2 : codim X                                |
|                                            |
|o2 = 4                                      |
+--------------------------------------------+

See also
========

  * dim(CoincidentRootLocus) -- compute
    the dimension

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

  * codim(CoincidentRootLocus), --
    compute the codimension

coefficientRing(CoincidentRootLocus) -- get the coefficient ring
****************************************************************

Synopsis
========

  * Function: coefficientRing (Macaulay2Doc),
  * Usage:
        coefficientRing X
  * Inputs:
      * X, a coincident root locus,
  * Outputs:
      * a ring (Macaulay2Doc), the coefficient ring of the ring of
        X

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

+--------------------------------------------+
|i1 : X = coincidentRootLocus {3,2}          |
|                                            |
|o1 = CRL(3,2)                               |
|                                            |
|o1 : Coincident root locus                  |
+--------------------------------------------+
|i2 : coefficientRing X                      |
|                                            |
|o2 = QQ                                     |
|                                            |
|o2 : Ring                                   |
+--------------------------------------------+
|i3 : X' = coincidentRootLocus({3,2},ZZ/3331)|
|                                            |
|o3 = CRL(3,2;ZZ/3331)                       |
|                                            |
|o3 : Coincident root locus                  |
+--------------------------------------------+
|i4 : coefficientRing X'                     |
|                                            |
|      ZZ                                    |
|o4 = ----                                   |
|     3331                                   |
|                                            |
|o4 : QuotientRing                           |
+--------------------------------------------+

See also
========

  * ring(CoincidentRootLocus) -- get the
    ring of a coincident root locus

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

  * coefficientRing(CoincidentRootLocus)
    -- get the coefficient ring

CoincidentRootLocus -- the class of all coincident root loci
************************************************************

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

The coincident root locus associated with a partition
$\lambda=(\lambda_1,\ldots,\lambda_d)$ of a number $n$ is the closed subvariety
of the projective space $\mathbb{P}^n = \mathbb{P}(Sym^n(K^2))$ given by binary
forms that factor as ${L_1}^{\lambda_1}\cdots{L_d}^{\lambda_d}$ for some linear
forms $L_1,\ldots,L_d$ over $\bar{K}$. For instance, if
$\lambda=(2,1,\ldots,1)$, then we have the classical discriminant hypersurface;
in the opposite case, if $\lambda=(n)$ we have the rational normal curve of
degree $n$.

See also
========

  * coincidentRootLocus -- makes a coincident root
    locus

Functions and methods returning a coincident root locus :
=========================================================

  * coincidentRootLocus -- makes a coincident root
    locus

Methods that use a coincident root locus :
==========================================

  * chowForm(CoincidentRootLocus), --
    Chow form of a coincident root locus
  * codim(CoincidentRootLocus), --
    compute the codimension
  * coefficientRing(CoincidentRootLocus)
    -- get the coefficient ring
  * CoincidentRootLocus * CoincidentRootLocus
    -- projective join of coincident root loci
  * degree(CoincidentRootLocus), --
    compute the degree
  * dim(CoincidentRootLocus) -- compute
    the dimension
  * dual(CoincidentRootLocus) -- the
    projectively dual to a coincident root locus
  * generic(CoincidentRootLocus), --
    get the generic element
  * ideal(CoincidentRootLocus) -- the
    defining ideal of a coincident root locus
  * isInCoisotropic(Ideal,CoincidentRootLocus)
    -- test membership in a
    coisotropic hypersurface
  * isSubset(CoincidentRootLocus,CoincidentRootLocus)
    -- whether one
    object is a subset of another
  * map(CoincidentRootLocus) -- the map
    associated to a coincident root locus
  * member(RingElement,CoincidentRootLocus)
    -- test membership in a
    coincident root locus
  * partition(CoincidentRootLocus),
    -- the partition associated to a coincident root locus
  * "polarDegrees(CoincidentRootLocus)" -- see polarDegrees,
    -- polar degrees of a coincident root locus
  * "projectiveTangentSpace(CoincidentRootLocus,RingElement)" -- see
    projectiveTangentSpace, -- projective tangent space
  * random(CoincidentRootLocus) -- get
    a random element
  * randomInCoisotropic(CoincidentRootLocus,ZZ)
    -- get a random element
  * ring(CoincidentRootLocus) -- get the
    ring of a coincident root locus
  * singularLocus(CoincidentRootLocus)
    -- the singular locus of a
    coincident root locus
  * subsets(CoincidentRootLocus), --
    produce all the subloci
  * supsets(CoincidentRootLocus), --
    produce all the suploci

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

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

coincidentRootLocus -- makes a coincident root locus
****************************************************

Synopsis
========

  * Usage:
        coincidentRootLocus(l,K)
        coincidentRootLocus l
  * Inputs:
      * l, a visible list (Macaulay2Doc), a partition of a
        number $n$, i.e., a list of $d$ positive integers $l_1,\ldots,l_d$
        satisfying ${\sum}_{i} l_i = n$
      * K, a ring (Macaulay2Doc), the coefficient ring (optional
        with default value QQ (Macaulay2Doc))
  * Optional inputs (Macaulay2Doc),:
      * Variable,
        => ..., default value "t", specify a name for a variable
  * Outputs:
      * a coincident root locus, the coincident
        root locus associated with the partition $l$ over $K$, i.e., the
        subvariety of the projective $n$-space $\mathbb{P}(Sym^n(K^2))$ of all
        binary forms whose linear factors are distributed according to $l$

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

+-----------------------------------------------------------------------------+
|i1 : X = coincidentRootLocus {6,4,3,3,2}                                     |
|                                                                             |
|o1 = CRL(6,4,3,3,2)                                                          |
|                                                                             |
|o1 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i2 : describe X                                                              |
|                                                                             |
|o2 = Coincident root locus associated with the partition {6, 4, 3            |
|     ambient: P^18 = Proj(QQ[t_0..t_18])                                     |
|     dim    = 5                                                              |
|     codim  = 13                                                             |
|     degree = 25920                                                          |
|     The singular locus is the union of the coincident root loci             |
|     ({6, 6, 4, 2},{10, 3, 3, 2},{9, 4, 3, 2},{7, 6, 3, 2},{8, 4,            |
|-----------------------------------------------------------------------------|
|, 3, 2} defined over QQ                                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|associated with the partitions:                                              |
| 3, 3},{6, 6, 3, 3},{6, 5, 4, 3})                                            |
+-----------------------------------------------------------------------------+
|i3 : describe dual X                                                         |
|                                                                             |
|o3 = Dual of the coincident root locus associated with the partition {6, 4   |
|     which coincides with the join of the coincident root loci associated    |
|     ({14, 1, 1, 1, 1},{16, 1, 1},{17, 1},{17, 1},{18})                      |
|     ambient: P^18 = Proj(QQ[t_0..t_18])                                     |
|     dim    = 17                                                             |
|     codim  = 1                                                              |
|     degree = 21600                                                          |
|-----------------------------------------------------------------------------|
|, 3, 3, 2} defined over QQ                                                   |
|with the partitions:                                                         |
+-----------------------------------------------------------------------------+

Ways to use coincidentRootLocus :
=================================

  * "coincidentRootLocus(List)"
  * "coincidentRootLocus(VisibleList,Ring)"

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

The object coincidentRootLocus, is a method function with a single argument (Macaulay2Doc).

CoincidentRootLocus * CoincidentRootLocus -- projective join of coincident root loci
************************************************************************************

Synopsis
========

  * Operator: * (Macaulay2Doc),
  * Usage:
        X * Y
        projectiveJoin(X,Y)
  * Inputs:
      * X, a coincident root locus,
      * Y, a coincident root locus,
  * Outputs:
      * the projective join of $X$ and $Y$

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

A partition of a number $n$ is a hook if at most one part is not 1. The inputs
of this method are required to be coincident root loci associated with hook
partitions of $n$. In this case, the returned object is the dual of a certain
coincident root locus; see the paper by H. Lee and B. Sturmfels - Duality of
multiple root loci - J. Algebra 446, 499-526, 2016.

+-----------------------------------------------------------------------+
|i1 : X = coincidentRootLocus {11,1,1,1,1}                              |
|                                                                       |
|o1 = CRL(11,1,1,1,1)                                                   |
|                                                                       |
|o1 : Coincident root locus                                             |
+-----------------------------------------------------------------------+
|i2 : Y = coincidentRootLocus {13,1,1}                                  |
|                                                                       |
|o2 = CRL(13,1,1)                                                       |
|                                                                       |
|o2 : Coincident root locus                                             |
+-----------------------------------------------------------------------+
|i3 : X * Y                                                             |
|                                                                       |
|o3 = CRL(11,1,1,1,1) * CRL(13,1,1) (dual of CRL(6,4,1,1,1,1,1))        |
|                                                                       |
|o3 : Join of 2 coincident root loci                                    |
+-----------------------------------------------------------------------+
|i4 : X * Y * Y                                                         |
|                                                                       |
|o4 = CRL(11,1,1,1,1) * CRL(13,1,1) * CRL(13,1,1) (dual of CRL(6,4,4,1))|
|                                                                       |
|o4 : Join of 3 coincident root loci                                    |
+-----------------------------------------------------------------------+

More generally, if $I_1,I_2,\ldots$ is a sequence of homogeneous ideals (resp.
parameterizations) of projective varieties $X_1,X_2,\ldots \subset
\mathbb{P}^n$, then projectiveJoin(I_1,I_2,...) is the ideal of the projective
join $X_1\,*\,X_2\,*\,\cdots \subset \mathbb{P}^n$.

+-----------------------------------------------------------------------------+
|i5 : I = ideal coincidentRootLocus {4}                                       |
|                                                                             |
|             2                                    2                       2  |
|o5 = ideal (t  - t t , t t  - t t , t t  - t t , t  - t t , t t  - t t , t  -|
|             3    2 4   2 3    1 4   1 3    0 4   2    0 4   1 2    0 3   1  |
|     ------------------------------------------------------------------------|
|     t t )                                                                   |
|      0 2                                                                    |
|                                                                             |
|o5 : Ideal of QQ[t ..t ]                                                     |
|                  0   4                                                      |
+-----------------------------------------------------------------------------+
|i6 : projectiveJoin(I,I)                                                     |
|                                                                             |
|            3                2    2                                          |
|o6 = ideal(t  - 2t t t  + t t  + t t  - t t t )                              |
|            2     1 2 3    0 3    1 4    0 2 4                               |
|                                                                             |
|o6 : Ideal of QQ[t ..t ]                                                     |
|                  0   4                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * dual(CoincidentRootLocus) -- the
    projectively dual to a coincident root locus

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

  * CoincidentRootLocus * CoincidentRootLocus
    -- projective join of coincident root loci

coincidentRootLocus(...,Variable=>...) -- specify a name for a variable
***********************************************************************

Synopsis
========

  * Usage:
        Variable => x
  * Inputs:
      * x, a symbol (Macaulay2Doc),

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

This is an option used to specify a symbol to be used as a name for the
generator of the ambient polynomial ring.

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

  * Default value: t
  * Function: coincidentRootLocus, -- makes a
    coincident root locus
  * Option key: Variable (Macaulay2Doc), -- specify a name for a
    variable

Functions with optional argument named Variable :
=================================================

  * "apolar(...,Variable=>...)"
  * coincidentRootLocus(...,Variable=>...)
    -- specify a name
    for a variable
  * "generic(...,Variable=>...)"
  * "randomBinaryForm(...,Variable=>...)"
  * "realRankBoundary(...,Variable=>...)"
  * conwayPolynomial(...,Variable=>...) (missing documentation)
  * "GF(...,Variable=>...)" -- see GF (Macaulay2Doc), -- make a finite
    field
  * "cayleyTrick(...,Variable=>...)" -- see Grass(...,Variable=>...) (Resultants),
    -- specify a name
    for a variable
  * "chowEquations(...,Variable=>...)" -- see Grass(...,Variable=>...) (Resultants),
    -- specify a name
    for a variable
  * "chowForm(...,Variable=>...)" -- see Grass(...,Variable=>...) (Resultants),
    -- specify a name
    for a variable
  * "conormalVariety(...,Variable=>...)" -- see Grass(...,Variable=>...) (Resultants),
    -- specify a name
    for a variable
  * "fromPluckerToStiefel(...,Variable=>...)" -- see
    Grass(...,Variable=>...) (Resultants),
    -- specify a name
    for a variable
  * Grass(...,Variable=>...) (Resultants)
    -- specify a name
    for a variable
  * "hurwitzForm(...,Variable=>...)" -- see Grass(...,Variable=>...) (Resultants),
    -- specify a name
    for a variable
  * "plucker(...,Variable=>...)" -- see Grass(...,Variable=>...) (Resultants),
    -- specify a name
    for a variable
  * "tangentialChowForm(...,Variable=>...)" -- see
    Grass(...,Variable=>...) (Resultants),
    -- specify a name
    for a variable
  * "veronese(...,Variable=>...)" -- see Grass(...,Variable=>...) (Resultants),
    -- specify a name
    for a variable
  * "Grassmannian(...,Variable=>...)" -- see Grassmannian(ZZ,ZZ) (Macaulay2Doc),
    -- the Grassmannian of linear
    subspaces of a vector space
  * idealizer(...,Variable=>...) (IntegralClosure)
    -- Sets
    the name of the indexed variables introduced in computing the endomorphism
    ring Hom(J,J).
  * integralClosure(...,Variable=>...) (IntegralClosure),
    --
    set the base letter for the indexed variables introduced while computing
    the integral closure
  * "intersectInP(...,Variable=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "multiplicity(...,Variable=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * makeS2(...,Variable=>...) (IntegralClosure)
    -- Sets the
    name of the indexed variables introduced in computing the S2-ification.
  * "ringFromFractions(...,Variable=>...)" -- see ringFromFractions (IntegralClosure),
    -- find presentation for f.g. ring
  * "Schubert(...,Variable=>...)" -- see Schubert(ZZ,ZZ,VisibleList) (Macaulay2Doc),
    -- find the Plücker
    ideal of a Schubert variety
  * "distinguished(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "isReduction(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "jacobianDual(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "normalCone(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "reesAlgebra(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "reesIdeal(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "specialFiber(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * "specialFiberIdeal(...,Variable=>...)" -- see
    symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring
  * symmetricKernel(...,Variable=>...) (ReesAlgebra),
    --
    Choose name for variables in the created ring

complexrank -- compute the complex rank
***************************************

Synopsis
========

  * Usage:
        complexrank F
  * Inputs:
      * F, a ring element (Macaulay2Doc), a binary form
        $F\in K[x,y]$ of degree $d$, where $K$ is either $\mathbb{Q}$, or more
        generally a field
  * Optional inputs (Macaulay2Doc),:
      * Limit, => ...,
        default value infinity, set a bound for the rank
  * Outputs:
      * an integer (Macaulay2Doc), the rank of $F$, i.e., the minimum
        integer $r$ such that there is a decomposition $F =
        c_1\,(l_1)^d+\cdots+c_r\,(l_r)^d$ where $l_1,\ldots,l_r\in\bar{K}[x,y]$
        are linear forms and $c_1,\ldots,c_r\in\bar{K}$

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

This method provides a quick way to calculate the complex rank of a binary form
as an application of the methods apolar(RingElement,ZZ),
and discriminant(RingElement) (Resultants).

+-----------------------------------------------------------------------------+
|i1 : R := QQ[x,y];                                                           |
+-----------------------------------------------------------------------------+
|i2 : F = 325699392019820093805938500473136959995883*x^11-58109075709246448572|
|                                                                             |
|                                                11                           |
|o2 = 325699392019820093805938500473136959995883x   -                         |
|     ------------------------------------------------------------------------|
|                                                 10                          |
|     5810907570924644857232186920803498012892938x  y +                       |
|     ------------------------------------------------------------------------|
|                                                  9 2                        |
|     65819917752061707843768328400359649501719860x y  -                      |
|     ------------------------------------------------------------------------|
|                                                   8 3                       |
|     519457154316395169830396776661486079064173600x y  +                     |
|     ------------------------------------------------------------------------|
|                                                    7 4                      |
|     1705429425321816258526777767700378341505324800x y  -                    |
|     ------------------------------------------------------------------------|
|                                                    6 5                      |
|     3810190868583760635545828188931628645390528000x y  +                    |
|     ------------------------------------------------------------------------|
|                                                    5 6                      |
|     9250941324308079844692884039573393626015320480x y  -                    |
|     ------------------------------------------------------------------------|
|                                                    4 7                      |
|     9323164714263069666482962682446368124512793200x y  +                    |
|     ------------------------------------------------------------------------|
|                                                    3 8                      |
|     1072684515031339121680779290598231336889158000x y  -                    |
|     ------------------------------------------------------------------------|
|                                                  2 9                        |
|     66208958025372412656331871291180685863962950x y  -                      |
|     ------------------------------------------------------------------------|
|                                                   10                        |
|     3357470237827984950448384820635661305324565x*y   +                      |
|     ------------------------------------------------------------------------|
|                                                 11                          |
|     2036327846200712576945384935680953020530520y                            |
|                                                                             |
|o2 : QQ[x..y]                                                                |
|-----------------------------------------------------------------------------|
|32186920803498012892938*x^10*y+65819917752061707843768328400359649501719860*x|
|-----------------------------------------------------------------------------|
|^9*y^2-519457154316395169830396776661486079064173600*x^8*y^3+                |
|-----------------------------------------------------------------------------|
|1705429425321816258526777767700378341505324800*x^7*y^4-                      |
|-----------------------------------------------------------------------------|
|3810190868583760635545828188931628645390528000*x^6*y^5+                      |
|-----------------------------------------------------------------------------|
|9250941324308079844692884039573393626015320480*x^5*y^6-                      |
|-----------------------------------------------------------------------------|
|9323164714263069666482962682446368124512793200*x^4*y^7+                      |
|-----------------------------------------------------------------------------|
|1072684515031339121680779290598231336889158000*x^3*y^8-                      |
|-----------------------------------------------------------------------------|
|66208958025372412656331871291180685863962950*x^2*y^9-                        |
|-----------------------------------------------------------------------------|
|3357470237827984950448384820635661305324565*x*y^10+                          |
|-----------------------------------------------------------------------------|
|2036327846200712576945384935680953020530520*y^11                             |
+-----------------------------------------------------------------------------+
|i3 : complexrank F                                                           |
|                                                                             |
|o3 = 8                                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * realrank -- compute the real rank

Ways to use complexrank :
=========================

  * "complexrank(RingElement)"

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

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

CRL
***

Ways to use coincidentRootLocus :
=================================

  * "coincidentRootLocus(List)" -- see coincidentRootLocus,
    -- makes a coincident root locus
  * "coincidentRootLocus(VisibleList,Ring)" -- see coincidentRootLocus,
    -- makes a coincident root locus

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

The object CRL (missing documentation) is a method function with a single argument (Macaulay2Doc).

degree(CoincidentRootLocus) -- compute the degree
*************************************************

Synopsis
========

  * Function: degree (Macaulay2Doc),
  * Usage:
        degree X
  * Inputs:
      * X, a coincident root locus,
  * Outputs:
      * an integer (Macaulay2Doc), the degree of X as a projective
        variety

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

The formula for the degree of a coincident root locus $X$ associated with a
partition $\lambda=(\lambda_1,\ldots,\lambda_d)$ was determined in the paper by
D. Hilbert - Singularitaten der Diskriminantenflache - Math. Ann. 30, 437-441,
1887.

+--------------------------------------------+
|i1 : X = coincidentRootLocus {3,2,2,1,1,1,1}|
|                                            |
|o1 = CRL(3,2,2,1,1,1,1)                     |
|                                            |
|o1 : Coincident root locus                  |
+--------------------------------------------+
|i2 : degree X                               |
|                                            |
|o2 = 1260                                   |
+--------------------------------------------+

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

  * degree(CoincidentRootLocus), --
    compute the degree

dim(CoincidentRootLocus) -- compute the dimension
*************************************************

Synopsis
========

  * Function: dim (Macaulay2Doc),
  * Usage:
        dim X
  * Inputs:
      * X, a coincident root locus,
  * Outputs:
      * an integer (Macaulay2Doc), the dimension of X as a projective
        variety

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

The dimension of a coincident root locus $X$ associated with a partition
$\lambda=(\lambda_1,\ldots,\lambda_d)$ is $d$, the number of parts of
$\lambda$.

+--------------------------------------------+
|i1 : X = coincidentRootLocus {3,2,2,1,1,1,1}|
|                                            |
|o1 = CRL(3,2,2,1,1,1,1)                     |
|                                            |
|o1 : Coincident root locus                  |
+--------------------------------------------+
|i2 : dim X                                  |
|                                            |
|o2 = 7                                      |
+--------------------------------------------+

See also
========

  * codim(CoincidentRootLocus), --
    compute the codimension

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

  * dim(CoincidentRootLocus) -- compute
    the dimension

dual(CoincidentRootLocus) -- the projectively dual to a coincident root locus
*****************************************************************************

Synopsis
========

  * Function: dual (Macaulay2Doc),
  * Usage:
        dual X
  * Inputs:
      * X, a coincident root locus,
  * Outputs:
      * the dual variety to $X$

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

The dual variety to a coincident root locus is the join of certain coincident
root loci, as described in the paper by H. Lee and B. Sturmfels - Duality of
multiple root loci - J. Algebra 446, 499-526, 2016.

+-----------------------------------------------------------------------------+
|i1 : X = coincidentRootLocus {5,3,2,2,1,1}                                   |
|                                                                             |
|o1 = CRL(5,3,2,2,1,1)                                                        |
|                                                                             |
|o1 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i2 : dual X                                                                  |
|                                                                             |
|o2 = CRL(11,1,1,1) * CRL(13,1) * CRL(14) * CRL(14) (dual of CRL(5,3,2,2,1,1))|
|                                                                             |
|o2 : Join of 4 coincident root loci                                          |
+-----------------------------------------------------------------------------+

In the example below, we apply some of the functions that are available for the
returned objects.

+-----------------------------------------------------------------------------+
|i3 : Y = dual coincidentRootLocus {4,2}                                      |
|                                                                             |
|o3 = CRL(4,1,1) * CRL(6) (dual of CRL(4,2))                                  |
|                                                                             |
|o3 : Join of 2 coincident root loci                                          |
+-----------------------------------------------------------------------------+
|i4 : ring Y                                                                  |
|                                                                             |
|o4 = QQ[t ..t ]                                                              |
|         0   6                                                               |
|                                                                             |
|o4 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i5 : coefficientRing Y                                                       |
|                                                                             |
|o5 = QQ                                                                      |
|                                                                             |
|o5 : Ring                                                                    |
+-----------------------------------------------------------------------------+
|i6 : dim Y                                                                   |
|                                                                             |
|o6 = 5                                                                       |
+-----------------------------------------------------------------------------+
|i7 : codim Y                                                                 |
|                                                                             |
|o7 = 1                                                                       |
+-----------------------------------------------------------------------------+
|i8 : degree Y                                                                |
|                                                                             |
|o8 = 18                                                                      |
+-----------------------------------------------------------------------------+
|i9 : dual Y                                                                  |
|                                                                             |
|o9 = CRL(4,2)                                                                |
|                                                                             |
|o9 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i10 : G = random Y                                                           |
|                                                                             |
|        6      5        4 2      3 3          2 4             5           6  |
|o10 = 3t  + 12t t  + 15t t  + 80t t  - 209655t t  + 2582604t t  - 8474625t   |
|        0      0 1      0 1      0 1          0 1           0 1           1  |
|                                                                             |
|o10 : QQ[t ..t ]                                                             |
|          0   1                                                              |
+-----------------------------------------------------------------------------+
|i11 : member(G,Y)                                                            |
|                                                                             |
|o11 = true                                                                   |
+-----------------------------------------------------------------------------+
|i12 : ideal Y;                                                               |
|                                                                             |
|o12 : Ideal of QQ[t ..t ]                                                    |
|                   0   6                                                     |
+-----------------------------------------------------------------------------+
|i13 : describe Y                                                             |
|                                                                             |
|o13 = Dual of the coincident root locus associated with the partition {4, 2  |
|      which coincides with the join of the coincident root loci associated   |
|      ambient: P^6 = Proj(QQ[t_0..t_6])                                      |
|      dim    = 5                                                             |
|      codim  = 1                                                             |
|      degree = 18                                                            |
|      The defining polynomial has 3140 terms of degree 18                    |
|-----------------------------------------------------------------------------|
|} defined over QQ                                                            |
|with the partitions: ({4, 1, 1},{6})                                         |
+-----------------------------------------------------------------------------+

See also
========

  * CoincidentRootLocus * CoincidentRootLocus
    -- projective join of coincident root loci
  * dualVariety (Resultants) -- projective dual variety

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

  * dual(CoincidentRootLocus) -- the
    projectively dual to a coincident root locus

generic(...,Reduce=>...) -- reduce the number of variables
**********************************************************

Synopsis
========

  * Usage:
        generic(X,Reduce=>b)
  * Inputs:
      * b, a Boolean value (Macaulay2Doc),

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

  * Default value: false (Macaulay2Doc),
  * Function: generic, -- get the
    generic element
  * Option key: Reduce (Macaulay2Doc), -- an optional argument

See also
========

  * generic(CoincidentRootLocus), --
    get the generic element

Functions with optional argument named Reduce :
===============================================

  * generic(...,Reduce=>...),
    -- reduce the number of variables
  * hilbertSeries(...,Reduce=>...) (Macaulay2Doc)
    -- reduce
    the Hilbert series

generic(CoincidentRootLocus) -- get the generic element
*******************************************************

Synopsis
========

  * Function: generic,
  * Usage:
        generic X
  * Inputs:
      * X, a coincident root locus,
  * Optional inputs (Macaulay2Doc),:
      * Reduce, => ...,
        default value false, reduce the number of variables
      * Variable,
        => ..., default value null, specify a name for a variable
  * Outputs:
      * a ring element (Macaulay2Doc), the generic binary
        form which belongs to X

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

+-----------------------------------------------------------------------------+
|i1 : X = coincidentRootLocus {3,1,1}                                         |
|                                                                             |
|o1 = CRL(3,1,1)                                                              |
|                                                                             |
|o1 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i2 : F = generic X                                                           |
|                                                                             |
|       3       5      3           3            2           4        3        |
|o2 = t0 t1 t2 x  + (t0 t1 t2  + t0 t1 t2  + 3t0 t0 t1 t2 )x x  + (t0 t1 t2  +|
|       0  0  0 0      0  0  1     0  1  0      0  1  0  0  0 1      0  1  1  |
|     ------------------------------------------------------------------------|
|        2               2                  2        3 2       2              |
|     3t0 t0 t1 t2  + 3t0 t0 t1 t2  + 3t0 t0 t1 t2 )x x  + (3t0 t0 t1 t2  +   |
|        0  1  0  1      0  1  1  0      0  1  0  0  0 1       0  1  1  1     |
|     ------------------------------------------------------------------------|
|           2               2           3        2 3          2               |
|     3t0 t0 t1 t2  + 3t0 t0 t1 t2  + t0 t1 t2 )x x  + (3t0 t0 t1 t2  +       |
|        0  1  0  1      0  1  1  0     1  0  0  0 1       0  1  1  1         |
|     ------------------------------------------------------------------------|
|       3           3          4     3       5                                |
|     t0 t1 t2  + t0 t1 t2 )x x  + t0 t1 t2 x                                 |
|       1  0  1     1  1  0  0 1     1  1  1 1                                |
|                                                                             |
|o2 : QQ[t0 ..t0 , t1 ..t1 , t2 ..t2 ][x ..x ]                                |
|          0    1    0    1    0    1   0   1                                 |
+-----------------------------------------------------------------------------+
|i3 : member(F,X)                                                             |
|                                                                             |
|o3 = true                                                                    |
+-----------------------------------------------------------------------------+
|i4 : factor F                                                                |
|                                                                             |
|                                                  3                          |
|o4 = (t2 x  + t2 x )(t1 x  + t1 x )(t0 x  + t0 x )                           |
|        0 0     1 1    0 0     1 1    0 0     1 1                            |
|                                                                             |
|o4 : Expression of class Product                                             |
+-----------------------------------------------------------------------------+
|i5 : G = generic(X,Reduce=>true)                                             |
|                                                                             |
|      5 5      4      4      4    4        3 2     3         3               |
|o5 = t x  + (3t t  + t t  + t t )x x  + (3t t  + 3t t t  + 3t t t  +         |
|      0 0      0 1    0 2    0 3  0 1      0 1     0 1 2     0 1 3           |
|     ------------------------------------------------------------------------|
|      3      3 2     2 3     2 2       2 2       2        2 3       3        |
|     t t t )x x  + (t t  + 3t t t  + 3t t t  + 3t t t t )x x  + (t t t  +    |
|      0 2 3  0 1     0 1     0 1 2     0 1 3     0 1 2 3  0 1     0 1 2      |
|     ------------------------------------------------------------------------|
|        3         2        4    3     5                                      |
|     t t t  + 3t t t t )x x  + t t t x                                       |
|      0 1 3     0 1 2 3  0 1    1 2 3 1                                      |
|                                                                             |
|o5 : QQ[t ..t ][x ..x ]                                                      |
|         0   3   0   1                                                       |
+-----------------------------------------------------------------------------+
|i6 : member(G,X)                                                             |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+
|i7 : factor G                                                                |
|                                                                             |
|                                            3                                |
|o7 = (t x  + t x )(t x  + t x )(t x  + t x )                                 |
|       0 0    3 1   0 0    2 1   0 0    1 1                                  |
|                                                                             |
|o7 : Expression of class Product                                             |
+-----------------------------------------------------------------------------+

See also
========

  * random(CoincidentRootLocus) -- get
    a random element
  * member(RingElement,CoincidentRootLocus)
    -- test membership in a
    coincident root locus

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

  * generic(CoincidentRootLocus), --
    get the generic element

ideal(CoincidentRootLocus) -- the defining ideal of a coincident root locus
***************************************************************************

Synopsis
========

  * Function: ideal (Macaulay2Doc),
  * Usage:
        ideal X
  * Inputs:
      * X, a coincident root locus,
  * Outputs:
      * an ideal (Macaulay2Doc), the defining homogeneous ideal of
        X

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

This is the same as image map X.

+-----------------------------------------------------------------------------+
|i1 : X = coincidentRootLocus {3,2}                                           |
|                                                                             |
|o1 = CRL(3,2)                                                                |
|                                                                             |
|o1 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i2 : ideal X                                                                 |
|                                                                             |
|               4        2        2 2          2       3       3      2       |
|o2 = ideal (25t  - 50t t t  + 16t t  + 12t t t  - 3t t , 50t t  - 80t t t  - |
|               4      3 4 5      3 5      2 4 5     1 5     3 4      3 4 5   |
|     ------------------------------------------------------------------------|
|          2            2         2      3       3                    2       |
|     10t t t  + 48t t t  - 7t t t  - t t , 50t t  - 80t t t t  - 5t t t  +   |
|        2 4 5      2 3 5     1 4 5    0 5     2 4      2 3 4 5     1 4 5     |
|     ------------------------------------------------------------------------|
|        2 2         2         2       3                   2            2     |
|     36t t  + 2t t t  - 3t t t , 25t t  - 40t t t t  - t t t  + 18t t t  -   |
|        2 5     1 3 5     0 4 5     1 4      1 3 4 5    0 4 5      1 2 5     |
|     ------------------------------------------------------------------------|
|           2      3                2 2         2     2 2      3              |
|     2t t t , 5t t  - 8t t t t  + t t  + 2t t t , 25t t  - 40t t  +          |
|       0 3 5    0 4     0 3 4 5    1 5     0 2 5     3 4      3 5            |
|     ------------------------------------------------------------------------|
|                       2       2 2         2         2         2        2    |
|     10t t t t  - 10t t t  + 9t t  + 8t t t  - 2t t t , 50t t t  - 80t t t  +|
|        2 3 4 5      1 4 5     2 5     1 3 5     0 4 5     2 3 4      2 3 5  |
|     ------------------------------------------------------------------------|
|        2                        2            2        2         2        2  |
|     30t t t  - 15t t t t  - 8t t t  + 24t t t  - t t t , 25t t t  - 40t t t |
|        2 4 5      1 3 4 5     0 4 5      1 2 5    0 3 5     1 3 4      1 3 5|
|     ------------------------------------------------------------------------|
|                                  2 2        2         2        2       2    |
|     + 15t t t t  - 9t t t t  + 8t t  + t t t , 10t t t  - 16t t t  + 5t t t |
|          1 2 4 5     0 3 4 5     1 5    0 2 5     0 3 4      0 3 5     1 4 5|
|     ------------------------------------------------------------------------|
|                         2     2 2      2            2                       |
|     - 2t t t t  + 3t t t , 25t t  - 30t t t  - 15t t t  + 25t t t t  -      |
|         0 2 4 5     0 1 5     2 4      2 3 5      1 3 5      1 2 4 5        |
|     ------------------------------------------------------------------------|
|                    2 2         2         2                     2            |
|     12t t t t  + 4t t  + 3t t t , 25t t t  - 30t t t t  - 18t t t  +        |
|        0 3 4 5     1 5     0 2 5     1 2 4      1 2 3 5      0 3 5          |
|     ------------------------------------------------------------------------|
|        2                        2         2      2                          |
|     20t t t  - t t t t  + 4t t t , 10t t t  + 10t t t  - 28t t t t  +       |
|        1 4 5    0 2 4 5     0 1 5     0 2 4      1 3 5      0 2 3 5         |
|     ------------------------------------------------------------------------|
|                  2 2     2 2                              2 2        2      |
|     7t t t t  + t t , 25t t  - 48t t t t  + 22t t t t  + t t , 5t t t  +    |
|       0 1 4 5    0 5     1 4      0 2 3 5      0 1 4 5    0 5    0 1 4      |
|     ------------------------------------------------------------------------|
|        2            2                   2       2 2     3                   |
|     10t t t  - 16t t t  - 2t t t t  + 3t t t , t t  + 5t t  - 8t t t t  +   |
|        1 2 5      0 2 5     0 1 3 5     0 4 5   0 4     1 5     0 1 2 5     |
|     ------------------------------------------------------------------------|
|       2         2            2        3                       2        2    |
|     2t t t , 50t t t  - 75t t t  - 90t t  + 160t t t t  + 3t t t  - 60t t t |
|       0 3 5     2 3 4      1 3 4      2 5       1 2 3 5     0 3 5      1 4 5|
|     ------------------------------------------------------------------------|
|                          2                    2          2                  |
|     + 16t t t t  - 4t t t , 25t t t t  - 45t t t  - 45t t t  + 101t t t t  -|
|          0 2 4 5     0 1 5     1 2 3 4      0 3 4      1 2 5       0 2 3 5  |
|     ------------------------------------------------------------------------|
|                    2 2     2                       2            2           |
|     34t t t t  - 2t t , 25t t t  - 30t t t t  - 40t t t  + 46t t t  +       |
|        0 1 4 5     0 5     1 3 4      0 2 3 4      1 2 5      0 2 5         |
|     ------------------------------------------------------------------------|
|                   2        2           2                   3                |
|     7t t t t  - 8t t t , 5t t t  - 8t t t  + 3t t t t  - 8t t  + 11t t t t  |
|       0 1 3 5     0 4 5    1 2 4     0 2 4     0 1 3 4     1 5      0 1 2 5 |
|     ------------------------------------------------------------------------|
|         2         3                     2          2       2          2 2   |
|     - 3t t t , 25t t  - 40t t t t  + 18t t t  - t t t  - 2t t t , 100t t  - |
|         0 3 5     1 4      0 1 2 4      0 3 4    0 1 5     0 2 5      2 3   |
|     ------------------------------------------------------------------------|
|           3       3           2           2                                 |
|     150t t  - 150t t  + 465t t t  + 465t t t  - 1166t t t t  + 414t t t t  +|
|         1 3       2 4       0 3 4       1 2 5        0 2 3 5       0 1 4 5  |
|     ------------------------------------------------------------------------|
|        2 2         2        3        2                       2              |
|     22t t , 50t t t  - 90t t  - 75t t t  + 160t t t t  + 120t t t  -        |
|        0 5     1 2 3      0 3      1 2 4       0 2 3 4       1 2 5          |
|     ------------------------------------------------------------------------|
|           2                    2        2 2         2       2               |
|     189t t t  - 8t t t t  + 32t t t , 5t t  - 6t t t  - 3t t t  + 5t t t t  |
|         0 2 5     0 1 3 5      0 4 5    1 3     0 2 3     0 2 4     0 1 3 4 |
|     ------------------------------------------------------------------------|
|         3                  2         2            2            2            |
|     - 4t t  + 4t t t t  - t t t , 50t t t  - 80t t t  + 30t t t  -          |
|         1 5     0 1 2 5    0 3 5     1 2 3      0 2 3      0 1 3            |
|     ------------------------------------------------------------------------|
|                     2           2      2         3                     2 2  |
|     15t t t t  + 24t t t  - 8t t t  - t t t , 50t t  - 80t t t t  + 36t t  -|
|        0 1 2 4      0 3 4     0 1 5    0 2 5     1 3      0 1 2 3      0 3  |
|     ------------------------------------------------------------------------|
|         2       2         2         2 2        3                  2 2       |
|     5t t t  + 2t t t  - 3t t t , 25t t  - 40t t  + 10t t t t  + 9t t  -     |
|       0 1 4     0 2 4     0 1 5     1 2      0 2      0 1 2 3     0 3       |
|     ------------------------------------------------------------------------|
|          2       2         2         3            2        2        2       |
|     10t t t  + 8t t t  - 2t t t , 50t t  - 80t t t  - 10t t t  + 48t t t  - |
|        0 1 4     0 2 4     0 1 5     1 2      0 1 2      0 1 3      0 2 3   |
|     ------------------------------------------------------------------------|
|       2        3       4        2        2 2      2         3               |
|     7t t t  - t t , 25t  - 50t t t  + 16t t  + 12t t t  - 3t t )            |
|       0 1 4    0 5     1      0 1 2      0 2      0 1 3     0 4             |
|                                                                             |
|o2 : Ideal of QQ[t ..t ]                                                     |
|                  0   5                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * map(CoincidentRootLocus) -- the map
    associated to a coincident root locus

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

  * ideal(CoincidentRootLocus) -- the
    defining ideal of a coincident root locus

isInCoisotropic(Ideal,CoincidentRootLocus) -- test membership in a coisotropic hypersurface
*******************************************************************************************

Synopsis
========

  * Function: isInCoisotropic (Resultants),
  * Usage:
        isInCoisotropic(I,X)
  * Inputs:
      * I, an ideal (Macaulay2Doc), generated by $r+1$ linearly
        independent binary forms of the same degree $n$, which corresponds to a
        point $p_I\in Grass(r,\mathbb{P}(Sym^n(K^2)))=Grass(r,n)$
      * X, a coincident root locus, of dimension
        $d$ and codimension $n-d$
  * Optional inputs (Macaulay2Doc),:
      * Duality (Resultants), => ..., default value null, null
      * SingularLocus (Resultants), => ..., default value
        null, null
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether $p_I$ belongs to
        the $(r+d+1-n)$-th coisotropic hypersurface of $X$

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

+-----------------------------------------------------------------------------+
|i1 : X = coincidentRootLocus({2,2,1},ZZ/101)                                 |
|                                                                             |
|o1 = CRL(2,2,1;ZZ/101)                                                       |
|                                                                             |
|o1 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i2 : I = randomInCoisotropic(X,1)                                            |
|                                                                             |
|             3 2      2 3        4      5   4        2 3       4      5   5  |
|o2 = ideal (t t  + 42t t  + 32t t  - 32t , t t  + 14t t  + 4t t  - 44t , t  -|
|             0 1      0 1      0 1      1   0 1      0 1     0 1      1   0  |
|     ------------------------------------------------------------------------|
|        2 3        4      5                                                  |
|     40t t  - 18t t  - 36t )                                                 |
|        0 1      0 1      1                                                  |
|                                                                             |
|               ZZ                                                            |
|o2 : Ideal of ---[t ..t ]                                                    |
|              101  0   1                                                     |
+-----------------------------------------------------------------------------+
|i3 : isInCoisotropic(I,X)                                                    |
|                                                                             |
|o3 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * randomInCoisotropic(CoincidentRootLocus,ZZ)
    -- get a random element
  * isInCoisotropic (Resultants) -- test membership in a
    coisotropic hypersurface

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

  * isInCoisotropic(Ideal,CoincidentRootLocus)
    -- test membership in a
    coisotropic hypersurface

isSubset(CoincidentRootLocus,CoincidentRootLocus) -- whether one object is a subset of another
**********************************************************************************************

Synopsis
========

  * Function: isSubset (Macaulay2Doc),
  * Usage:
        isSubset(X,Y)
  * Inputs:
      * X, a coincident root locus, associated with
        a partition $\lambda$
      * Y, a coincident root locus, associated with
        a partition $\mu$
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether $X$ is contained
        in $Y$, i.e., whether the partition $\mu$ is a refinement of the
        partition $\lambda$

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

+--------------------------------------+
|i1 : X = coincidentRootLocus {6,4}    |
|                                      |
|o1 = CRL(6,4)                         |
|                                      |
|o1 : Coincident root locus            |
+--------------------------------------+
|i2 : Y = coincidentRootLocus {5,2,2,1}|
|                                      |
|o2 = CRL(5,2,2,1)                     |
|                                      |
|o2 : Coincident root locus            |
+--------------------------------------+
|i3 : isSubset(X,Y)                    |
|                                      |
|o3 = true                             |
+--------------------------------------+
|i4 : X' = coincidentRootLocus {6,3,1} |
|                                      |
|o4 = CRL(6,3,1)                       |
|                                      |
|o4 : Coincident root locus            |
+--------------------------------------+
|i5 : isSubset(X',Y)                   |
|                                      |
|o5 = false                            |
+--------------------------------------+

See also
========

  * subsets(CoincidentRootLocus), --
    produce all the subloci
  * supsets(CoincidentRootLocus), --
    produce all the suploci

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

  * isSubset(CoincidentRootLocus,CoincidentRootLocus)
    -- whether one
    object is a subset of another

map(CoincidentRootLocus) -- the map associated to a coincident root locus
*************************************************************************

Synopsis
========

  * Function: map (Macaulay2Doc),
  * Usage:
        map X
  * Inputs:
      * X, a coincident root locus,
  * Optional inputs (Macaulay2Doc),:
      * Degree (Macaulay2Doc), => ..., default value null, null
      * DegreeLift (Macaulay2Doc), => ...,
        default value null, null
      * DegreeMap (Macaulay2Doc), => ...,
        default value null, null
  * Outputs:
      * a rational map (Cremona), a unirational
        parameterization of X

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

If $X\subset\mathbb{P}^n$ is the coincident root locus associated with the
partition $(\lambda_1,\ldots,\lambda_d)$, then we have a map
$\mathbb{P}^1\times\cdots\times\mathbb{P}^1\to\mathbb{P}^n$ which sends a
$d$-tuple of linear forms $(L_1,\ldots,L_d)$ to
${L_1}^{\lambda_1}\cdots{L_d}^{\lambda_d}$. It is this map that is returned.

+-----------------------------------------------------------------------------+
|i1 : X = coincidentRootLocus {3,2,2}                                         |
|                                                                             |
|o1 = CRL(3,2,2)                                                              |
|                                                                             |
|o1 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i2 : f = map X                                                               |
|                                                                             |
|o2 = -- rational map --                                                      |
|     source: Proj(QQ[t0 , t0 ]) x Proj(QQ[t1 , t1 ]) x Proj(QQ[t2 , t2 ])    |
|                       0    1               0    1               0    1      |
|     target: Proj(QQ[t , t , t , t , t , t , t , t ])                        |
|                      0   1   2   3   4   5   6   7                          |
|     defining forms: {                                                       |
|                        3  2  2                                              |
|                      t0 t1 t2 ,                                             |
|                        0  0  0                                              |
|                                                                             |
|                      2  3  2         2  3        2   3  2     2  2          |
|                      -t0 t1 t2 t2  + -t0 t1 t1 t2  + -t0 t0 t1 t2 ,         |
|                      7  0  0  0  1   7  0  0  1  0   7  0  1  0  0          |
|                                                                             |
|                       1  3  2  2    4  3                1  3  2  2   2      |
|                      --t0 t1 t2  + --t0 t1 t1 t2 t2  + --t0 t1 t2  + -t0    |
|                      21  0  0  1   21  0  0  1  0  1   21  0  1  0   7      |
|                                                                             |
|                       2  3        2    2  3  2          3  2     2  2       |
|                      --t0 t1 t1 t2  + --t0 t1 t2 t2  + --t0 t0 t1 t2  +     |
|                      35  0  0  1  1   35  0  1  0  1   35  0  1  0  1       |
|                                                                             |
|                       1  3  2  2    6  2           2    6  2     2          |
|                      --t0 t1 t2  + --t0 t0 t1 t1 t2  + --t0 t0 t1 t2 t2     |
|                      35  0  1  1   35  0  1  0  1  1   35  0  1  1  0  1    |
|                                                                             |
|                      1  2     2  2   2     2        2   2     2  2          |
|                      -t0 t0 t1 t2  + -t0 t0 t1 t1 t2  + -t0 t0 t1 t2 t2     |
|                      7  0  1  1  1   7  0  1  0  1  1   7  0  1  1  0  1    |
|                                                                             |
|                      3     2  2  2   2  3        2   2  3  2                |
|                      -t0 t0 t1 t2  + -t0 t1 t1 t2  + -t0 t1 t2 t2 ,         |
|                      7  0  1  1  1   7  1  0  1  1   7  1  1  0  1          |
|                                                                             |
|                        3  2  2                                              |
|                      t0 t1 t2                                               |
|                        1  1  1                                              |
|                     }                                                       |
|                                                                             |
|o2 : MultihomogeneousRationalMap (rational map from PP^1 x PP^1 x PP^1 to    |
|-----------------------------------------------------------------------------|
|2     2         2  2           2   1     2  2  2                             |
| t0 t1 t2 t2  + -t0 t0 t1 t1 t2  + -t0 t0 t1 t2 ,                            |
|0  1  0  0  1   7  0  1  0  1  0   7  0  1  0  0                             |
|                                                                             |
|12  2                   3  2     2  2    6     2  2                          |
|--t0 t0 t1 t1 t2 t2  + --t0 t0 t1 t2  + --t0 t0 t1 t2 t2  +                  |
|35  0  1  0  1  0  1   35  0  1  1  0   35  0  1  0  0  1                    |
|                                                                             |
|    3     2  2  2   12     2                3     2  2  2                    |
| + --t0 t0 t1 t2  + --t0 t0 t1 t1 t2 t2  + --t0 t0 t1 t2  +                  |
|   35  0  1  0  1   35  0  1  0  1  0  1   35  0  1  1  0                    |
|                                                                             |
|    1  3  2  2    4  3                1  3  2  2                             |
| + --t0 t1 t2  + --t0 t1 t1 t2 t2  + --t0 t1 t2 ,                            |
|   21  1  0  1   21  1  0  1  0  1   21  1  1  0                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
| PP^7)                                                                       |
|-----------------------------------------------------------------------------|
| 6     2        2    1  3  2  2                                              |
|--t0 t0 t1 t1 t2  + --t0 t1 t2 ,                                             |
|35  0  1  0  1  0   35  1  0  0                                              |
|                                                                             |
| 2  3  2          2  3        2                                              |
|--t0 t1 t2 t2  + --t0 t1 t1 t2 ,                                             |
|35  1  0  0  1   35  1  0  1  0                                              |
+-----------------------------------------------------------------------------+
|i3 : describe f                                                              |
|                                                                             |
|o3 = rational map defined by multiforms of degree {3, 2, 2}                  |
|     source variety: PP^1 x PP^1 x PP^1                                      |
|     target variety: PP^7                                                    |
|     image: 3-dimensional variety of degree 36 in PP^7 cut out by 364        |
|     dominance: false                                                        |
|     birationality: false                                                    |
|     coefficient ring: QQ                                                    |
|-----------------------------------------------------------------------------|
|hypersurfaces of degree 6                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * ideal(CoincidentRootLocus) -- the
    defining ideal of a coincident root locus

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

  * map(CoincidentRootLocus) -- the map
    associated to a coincident root locus

member(RingElement,CoincidentRootLocus) -- test membership in a coincident root locus
*************************************************************************************

Synopsis
========

  * Function: member (Macaulay2Doc),
  * Usage:
        member(F,X)
  * Inputs:
      * F, a ring element (Macaulay2Doc), a binary form
      * X, a coincident root locus,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether $F$ belongs to
        $X$

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

+------------------------------------------------------------------------+
|i1 : R := QQ[x,y];                                                      |
+------------------------------------------------------------------------+
|i2 : F = x^7-3*x^6*y+5*x^5*y^2-7*x^4*y^3+7*x^3*y^4-5*x^2*y^5+3*x*y^6-y^7|
|                                                                        |
|      7     6      5 2     4 3     3 4     2 5       6    7             |
|o2 = x  - 3x y + 5x y  - 7x y  + 7x y  - 5x y  + 3x*y  - y              |
|                                                                        |
|o2 : QQ[x..y]                                                           |
+------------------------------------------------------------------------+
|i3 : member(F,coincidentRootLocus {3,2,2})                              |
|                                                                        |
|o3 = true                                                               |
+------------------------------------------------------------------------+
|i4 : member(F,coincidentRootLocus {5,2})                                |
|                                                                        |
|o4 = false                                                              |
+------------------------------------------------------------------------+

See also
========

  * random(CoincidentRootLocus) -- get
    a random element

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

  * member(RingElement,CoincidentRootLocus)
    -- test membership in a
    coincident root locus

partition(CoincidentRootLocus) -- the partition associated to a coincident root locus
*************************************************************************************

Synopsis
========

  * Function: partition (Macaulay2Doc),
  * Usage:
        partition X
  * Inputs:
      * X, a coincident root locus, associated with
        the partition $(\lambda_1,\ldots,\lambda_d)$
  * Outputs:
      * a list (Macaulay2Doc), the partition
        $(\lambda_1,\ldots,\lambda_d)$

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

+------------------------------------+
|i1 : X = coincidentRootLocus {3,2,2}|
|                                    |
|o1 = CRL(3,2,2)                     |
|                                    |
|o1 : Coincident root locus          |
+------------------------------------+
|i2 : partition X                    |
|                                    |
|o2 = {3, 2, 2}                      |
|                                    |
|o2 : List                           |
+------------------------------------+

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

  * partition(CoincidentRootLocus),
    -- the partition associated to a coincident root locus

polarDegrees -- polar degrees of a coincident root locus
********************************************************

Synopsis
========

  * Usage:
        polarDegrees X
  * Inputs:
      * X, a coincident root locus,
  * Outputs:
      * a list (Macaulay2Doc), the polar degrees of X

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

This method is based on a conjecture given in Algebraic boundaries among
typical ranks for real binary forms of arbitrary degree (see
https://arxiv.org/abs/1911.01958 ), which has been verified for all the
coincident root loci $X\subset\mathbb{P}^r$ with $r\leq 7$.

+-----------------------------------+
|i1 : X = coincidentRootLocus(3,2,2)|
|                                   |
|o1 = CRL(3,2,2)                    |
|                                   |
|o1 : Coincident root locus         |
+-----------------------------------+
|i2 : polarDegrees X                |
|                                   |
|o2 = {36, 80, 66, 24}              |
|                                   |
|o2 : List                          |
+-----------------------------------+

See also
========

  * conormalVariety (Resultants) -- conormal variety
  * multidegree (Macaulay2Doc) -- multidegree

Ways to use polarDegrees :
==========================

  * "polarDegrees(CoincidentRootLocus)"

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

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

projectiveTangentSpace -- projective tangent space
**************************************************

Synopsis
========

  * Usage:
        projectiveTangentSpace(X,F)
  * Inputs:
      * X, a coincident root locus,
      * F, a ring element (Macaulay2Doc), a binary form that
        belongs to X
  * Outputs:
      * an ideal (Macaulay2Doc), generated by binary forms of the
        same degree as that of F, which corresponds to the projective tangent
        space to X at F

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

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : F = x^7+2*x^6*y-x^5*y^2-4*x^4*y^3-x^3*y^4+2*x^2*y^5+x*y^6               |
|                                                                             |
|      7     6     5 2     4 3    3 4     2 5      6                          |
|o2 = x  + 2x y - x y  - 4x y  - x y  + 2x y  + x*y                           |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+
|i3 : X = coincidentRootLocus(4,2,1)                                          |
|                                                                             |
|o3 = CRL(4,2,1)                                                              |
|                                                                             |
|o3 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i4 : projectiveTangentSpace(X,F)                                             |
|                                                                             |
|             4 3     3 4       6    7   5 2     3 4     2 5       6     7    |
|o4 = ideal (x y  + 2x y  - 2x*y  - y , x y  - 4x y  - 2x y  + 3x*y  + 2y ,   |
|     ------------------------------------------------------------------------|
|      6      3 4     2 5       6     7   7     3 4     2 5       6     7     |
|     x y + 6x y  + 3x y  - 6x*y  - 4y , x  - 9x y  - 6x y  + 8x*y  + 6y )    |
|                                                                             |
|o4 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

See also
========

  * member(RingElement,CoincidentRootLocus)
    -- test membership in a
    coincident root locus
  * singularLocus(CoincidentRootLocus)
    -- the singular locus of a
    coincident root locus

Ways to use projectiveTangentSpace :
====================================

  * "projectiveTangentSpace(CoincidentRootLocus,RingElement)"

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

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

QepcadOptions -- set the number of cells in the garbage collected space
***********************************************************************

Synopsis
========

  * Usage:
        realrank(F,QepcadOptions=>(a,b))
  * Inputs:
      * a, an integer (Macaulay2Doc),
      * b, an integer (Macaulay2Doc),

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

This specifies how the program QEPCAD is executed: $qe/bin/qepcad +Na +Lb. For
details, we refer to the documentation QEPCAD - Basic User Information (see
https://www.usna.edu/CS/qepcadweb/B/user/UsingQEPCAD.html ).

Functions with optional argument named QepcadOptions :
======================================================

  * "realrank(...,QepcadOptions=>...)"

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

The object QepcadOptions, is a symbol (Macaulay2Doc).

random(CoincidentRootLocus) -- get a random element
***************************************************

Synopsis
========

  * Function: random (Macaulay2Doc),
  * Usage:
        random X
  * Inputs:
      * X, a coincident root locus,
  * Optional inputs (Macaulay2Doc),:
      * Density (Macaulay2Doc), => ...,
        default value 1, null
      * Height (Macaulay2Doc), => ..., default value 10,
        null
      * MaximalRank (Macaulay2Doc), => ...,
        default value false, null
      * UpperTriangular (Macaulay2Doc), =>
        ..., default value false, null
  * Outputs:
      * a ring element (Macaulay2Doc), a random binary form
        which belongs to X

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

+-----------------------------------------------------------------------------+
|i1 : X = coincidentRootLocus {3,3,2}                                         |
|                                                                             |
|o1 = CRL(3,3,2)                                                              |
|                                                                             |
|o1 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i2 : F = random X                                                            |
|                                                                             |
|        8        7           6 2          5 3           4 4            3 5   |
|o2 = 72t  - 3108t t  + 56018t t  - 546831t t  + 3136401t t  - 10714113t t  + |
|        0        0 1         0 1          0 1           0 1            0 1   |
|     ------------------------------------------------------------------------|
|              2 6              7           8                                 |
|     21001761t t  - 21257640t t  + 8503056t                                  |
|              0 1            0 1           1                                 |
|                                                                             |
|o2 : QQ[t ..t ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i3 : member(F,X)                                                             |
|                                                                             |
|o3 = true                                                                    |
+-----------------------------------------------------------------------------+
|i4 : factor F                                                                |
|                                                                             |
|               3           3           2                                     |
|o4 = (t  - 9t ) (2t  - 9t ) (3t  - 4t )                                      |
|       0     1     0     1     0     1                                       |
|                                                                             |
|o4 : Expression of class Product                                             |
+-----------------------------------------------------------------------------+

See also
========

  * member(RingElement,CoincidentRootLocus)
    -- test membership in a
    coincident root locus

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

  * random(CoincidentRootLocus) -- get
    a random element

randomBinaryForm -- random homogeneous polynomial in two variables
******************************************************************

Synopsis
========

  * Usage:
        randomBinaryForm d
        randomBinaryForm(d,r,c)
        randomBinaryForm(d,r,)
        randomBinaryForm(d,,c)
  * Inputs:
      * d, an integer (Macaulay2Doc),
      * r, an integer (Macaulay2Doc),
      * c, an integer (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Variable,
        => ..., default value "t", specify a name for a variable
  * Outputs:
      * a ring element (Macaulay2Doc), a random binary form
        of degree d, real rank r and complex rank c

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

+-----------------------------------------------------------------------------+
|i1 : F = randomBinaryForm 5                                                  |
|                                                                             |
|        5     4       3 2     2 3       4     5                              |
|o1 = 18t  + 2t t  + 9t t  + 2t t  + 4t t  + 3t                               |
|        0     0 1     0 1     0 1     0 1     1                              |
|                                                                             |
|o1 : QQ[t ..t ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i2 : F = randomBinaryForm(5,4,3)                                             |
|                                                                             |
|               5              4                3 2              2 3          |
|o2 = 209884591t  - 1249398325t t  + 2795829750t t  - 2971862250t t  +        |
|               0              0 1              0 1              0 1          |
|     ------------------------------------------------------------------------|
|                  4             5                                            |
|     1613878875t t  - 366993425t                                             |
|                0 1             1                                            |
|                                                                             |
|o2 : QQ[t ..t ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i3 : (realrank F,complexrank F)                                              |
|                                                                             |
|o3 = (4, 3)                                                                  |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i4 : F = randomBinaryForm(6,4,4)                                             |
|                                                                             |
|                         6                       5                           |
|o4 = 1230199624506159891t  - 5175463851202866480t t  +                       |
|                         0                       0 1                         |
|     ------------------------------------------------------------------------|
|                          4 2                        3 3                     |
|     10338793433232831000t t  - 12367324363544640000t t  +                   |
|                          0 1                        0 1                     |
|     ------------------------------------------------------------------------|
|                         2 4                         5                       |
|     9222909060317400000t t  - 4370569934562783000t t  +                     |
|                         0 1                       0 1                       |
|     ------------------------------------------------------------------------|
|                         6                                                   |
|     1233040823578529525t                                                    |
|                         1                                                   |
|                                                                             |
|o4 : QQ[t ..t ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i5 : (realrank F,complexrank F)                                              |
|                                                                             |
|o5 = (4, 4)                                                                  |
|                                                                             |
|o5 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * realrank -- compute the real rank
  * complexrank -- compute the complex rank

Ways to use randomBinaryForm :
==============================

  * "randomBinaryForm(ZZ)"
  * "randomBinaryForm(ZZ,Ring)"
  * "randomBinaryForm(ZZ,Thing,Thing)"
  * "randomBinaryForm(ZZ,Thing,Thing,Ring)"

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

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

randomInCoisotropic(CoincidentRootLocus,ZZ) -- get a random element
*******************************************************************

Synopsis
========

  * Function: randomInCoisotropic,
  * Usage:
        randomInCoisotropic(X,i)
  * Inputs:
      * X, a coincident root locus, of dimension
        $d$ and codimension $n-d$
      * i, an integer (Macaulay2Doc),
  * Outputs:
      * an ideal (Macaulay2Doc), generated by $n-d+i$ linearly
        independent binary forms of the same degree $n$, which corresponds to a
        random point of the $i$-th coisotropic hypersurface $CH_i(X)\subset
        Grass(n-d-1+i,\mathbb{P}(Sym^n(K^2)))$

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

+-----------------------------------------------------------------------------+
|i1 : X = coincidentRootLocus({2,2,1},ZZ/101)                                 |
|                                                                             |
|o1 = CRL(2,2,1;ZZ/101)                                                       |
|                                                                             |
|o1 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i2 : I = randomInCoisotropic(X,1)                                            |
|                                                                             |
|             3 2      2 3        4      5   4        2 3       4      5   5  |
|o2 = ideal (t t  + 42t t  + 32t t  - 32t , t t  + 14t t  + 4t t  - 44t , t  -|
|             0 1      0 1      0 1      1   0 1      0 1     0 1      1   0  |
|     ------------------------------------------------------------------------|
|        2 3        4      5                                                  |
|     40t t  - 18t t  - 36t )                                                 |
|        0 1      0 1      1                                                  |
|                                                                             |
|               ZZ                                                            |
|o2 : Ideal of ---[t ..t ]                                                    |
|              101  0   1                                                     |
+-----------------------------------------------------------------------------+
|i3 : isInCoisotropic(I,X)                                                    |
|                                                                             |
|o3 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * isInCoisotropic(Ideal,CoincidentRootLocus)
    -- test membership in a
    coisotropic hypersurface

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

  * randomInCoisotropic(CoincidentRootLocus,ZZ)
    -- get a random element

realrank -- compute the real rank
*********************************

Synopsis
========

  * Usage:
        realrank F
  * Inputs:
      * F, a ring element (Macaulay2Doc), a binary form
        $F\in K[x,y]$ of degree $d$, where $K$ is either $\mathbb{Q}$ or a
        polynomial ring over $\mathbb{Q}$ (currently, with only one variable)
  * Optional inputs (Macaulay2Doc),:
      * Limit, => ...,
        default value infinity, set a bound for the rank
      * QepcadOptions, => ..., default value
        (20000000,10000), set the number of cells in the garbage collected
        space
      * Range, => ...,
        default value (-infinity,infinity), can be assigned an interval
      * Verbose, => ...,
        default value false, request verbose feedback
  * Outputs:
      * an integer (Macaulay2Doc), the real rank of $F$, i.e., the
        minimum integer $r$ such that there is a decomposition $F =
        c_1\,(l_1)^d+\cdots+c_r\,(l_r)^d$ where $l_1,\ldots,l_r$ are real
        linear forms and $c_1,\ldots,c_r\in\mathbb{R}$

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

This method requires generally the program QEPCAD (see
https://www.usna.edu/CS/qepcadweb/B/QEPCAD.html ) to be installed. Source code
and installation instructions for it are available at Downloading and
Installing QEPCAD (see https://www.usna.edu/CS/qepcadweb/INSTALL/IQ.html ).

Below we compute the real rank of a binary form of degree 7.

i1 : R := QQ[x,y];

i2 : F = 2*x^7+7*x^6*y+168*x^5*y^2+140*x^4*y^3+70*x^3*y^4+21*x^2*y^5+56*x*y^6+4

       7     6        5 2       4 3      3 4      2 5        6     7
o2 = 2x  + 7x y + 168x y  + 140x y  + 70x y  + 21x y  + 56x*y  + 4y

o2 : QQ[x..y]

i3 : realrank F

o3 = 5
-------------------------------------------------------------------------------
*y^7

In the case when the coefficient ring $K$ contains a variable, say $u$, then
the method returns a value $r$ if the real rank of $F$ is $r$ for all the real
values of $u$ in the range specified by the option
realrank(...,Range=>...). An error
is thrown if the answer is not uniform.

i4 : Ru := QQ[u][x,y];

i5 : F = u*x^4*y+2*x^2*y^3

        4      2 3
o5 = u*x y + 2x y

o5 : QQ[u][x..y]

i6 : realrank(F,Range=>(0,infinity))

o6 = 3

i7 : realrank(F,Range=>[-1,0])

o7 = 3

i8 : realrank(F,Range=>(-infinity,-1))

o8 = 3

See also
========

  * complexrank -- compute the complex rank

Ways to use realrank :
======================

  * "realrank(RingElement)"

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

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

realrank(...,Limit=>...) -- set a bound for the rank
****************************************************

Synopsis
========

  * Usage:
        realrank(F,Limit=>r)
        complexrank(F,Limit=>r)
  * Inputs:
      * r, an integer (Macaulay2Doc),

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

This tells the method to search the rank in the range between 1 and $r-1$. If
the output is not an integer then the rank is greater than or equal to $r$.

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

  * Default value: infinity (Macaulay2Doc),
  * Function: realrank, -- compute the real rank
  * Option key: Limit (Macaulay2Doc), -- an optional argument

See also
========

  * realrank -- compute the real rank
  * complexrank -- compute the complex rank

Functions with optional argument named Limit :
==============================================

  * "basis(...,Limit=>...)" -- see basis (Macaulay2Doc), -- basis
    or generating set of all or part of a ring, ideal or module
  * hermite(...,Limit=>...) (missing documentation)
  * icFracP(...,Limit=>...) (IntegralClosure)
    -- Limits the
    number of computed intermediate modules.
  * "independentSets(...,Limit=>...)" -- see independentSets (Macaulay2Doc),
    -- some size-maximal independent subsets of
    variables modulo an ideal
  * integralClosure(...,Limit=>...) (IntegralClosure)
    -- do a
    partial integral closure
  * kernelLLL(...,Limit=>...) (missing documentation)
  * LLL(...,Limit=>...) (missing documentation)
  * "minors(...,Limit=>...)" -- see minors(ZZ,Matrix) (Macaulay2Doc),
    -- ideal generated by minors
  * "oeis(...,Limit=>...)" -- see oeis (OnlineLookup), -- OEIS
    lookup
  * "complexrank(...,Limit=>...)"
  * realrank(...,Limit=>...),
    -- set a bound for the rank
  * "simpleDocFrob(...,Limit=>...)" -- see simpleDocFrob (SimpleDoc),
    -- a sample documentation node

realrank(...,Range=>...) -- can be assigned an interval
*******************************************************

Synopsis
========

  * Usage:
        realrank(F,Range=>(a,b))
        realrank(F,Range=>[a,b])
  * Inputs:
      * F, a ring element (Macaulay2Doc), a binary form
        $F_u(x,y)\in \mathbb{Q}[u][x,y]$
      * a, a rational number (Macaulay2Doc), or an
        InfiniteNumber (Macaulay2Doc),
      * b, a rational number (Macaulay2Doc), or an
        InfiniteNumber (Macaulay2Doc),
  * Outputs:
      * r, an integer (Macaulay2Doc), if the real rank of $F_u(x,y)$
        is $r$ for all the values $u\in(a,b)$ or $u\in[a,b]$

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

If the real rank of $F_u(x,y)$ is not constant over the interval, then an error
message will be returned. The default value is (-infinity,infinity).

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

  * Default value: (-infinity,infinity)
  * Function: realrank, -- compute the real rank
  * Option key: Range (Macaulay2Doc), -- can be assigned a integral
    interval

Functions with optional argument named Range :
==============================================

  * "getPrimeWithRootOfUnity(...,Range=>...)" -- see
    getPrimeWithRootOfUnity (Macaulay2Doc), -- find a
    prime p with a primitive n-th root of unity r in ZZ/p
  * realrank(...,Range=>...),
    -- can be assigned an interval

realrank(...,Verbose=>...) -- request verbose feedback
******************************************************

Synopsis
========

  * Usage:
        realrank(F,Verbose=>b)
        realroots(F,Verbose=>b)
  * Inputs:
      * b, a Boolean value (Macaulay2Doc),

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

  * Default value: false (Macaulay2Doc),
  * Function: realrank, -- compute the real rank
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

Functions with optional argument named Verbose :
================================================

  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "approximateInverseMap(...,Verbose=>...)" -- see
    inverseMap(...,Verbose=>...) (Cremona),
  * "ChernSchwartzMacPherson(...,Verbose=>...)" -- see
    inverseMap(...,Verbose=>...) (Cremona),
  * "degreeMap(...,Verbose=>...)" -- see inverseMap(...,Verbose=>...) (Cremona),
  * "EulerCharacteristic(...,Verbose=>...)" -- see
    inverseMap(...,Verbose=>...) (Cremona),
  * inverseMap(...,Verbose=>...) (Cremona)
  * "isBirational(...,Verbose=>...)" -- see inverseMap(...,Verbose=>...) (Cremona),
  * "isDominant(...,Verbose=>...)" -- see inverseMap(...,Verbose=>...) (Cremona),
  * "projectiveDegrees(...,Verbose=>...)" -- see
    inverseMap(...,Verbose=>...) (Cremona),
  * "SegreClass(...,Verbose=>...)" -- see inverseMap(...,Verbose=>...) (Cremona),
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabalistic test for isomorphism of modules
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * realrank(...,Verbose=>...)
    -- request verbose feedback
  * "realroots(...,Verbose=>...)"
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree

realRankBoundary -- algebraic boundaries among typical ranks for real binary forms
**********************************************************************************

Synopsis
========

  * Usage:
        realRankBoundary(n,i)
  * Inputs:
      * n, an integer (Macaulay2Doc),
      * i, an integer (Macaulay2Doc), a typical rank
  * Optional inputs (Macaulay2Doc),:
      * Variable,
        => ..., default value "t", specify a name for a variable
  * Outputs:
      * the irreducible components of the real algebraic boundary that
        separates real rank $i$ from the other typical ranks in the real
        projective space $\mathbb{P}^n=\mathbb{P}(Sym^n(\mathbb{R}^2))$ of
        binary forms of degree $n$

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

Define ${\mathcal{R}}_{n,i}$ as the interior of the set $\{F\in
Sym^n(\mathbb{R}^2) : realrank(F) = i\}$. Then ${\mathcal{R}}_{n,i}$ is a
semi-algebraic set which is non-empty exactly when $(n+1)/2 \leq i\leq n$ (in
this case we say that $i$ is a typical rank); see the paper by G. Blekherman -
Typical real ranks of binary forms - Found. Comput. Math. 15, 793-798, 2015.
The topological boundary $\partial({\mathcal{R}}_{n,i})$ is the set-theoretic
difference of the closure of ${\mathcal{R}}_{n,i}$ minus the interior of the
closure of ${\mathcal{R}}_{n,i}$. In the range $(n+1)/2 \leq i\leq n-1$, it is
a semi-algebraic set of pure codimension one. The (real) algebraic boundary
$\partial_{alg}({\mathcal{R}}_{n,i})$ is defined as the Zariski closure of the
topological boundary $\partial({\mathcal{R}}_{n,i})$. This is viewed as a
hypersurface in $\mathbb{P}(Sym^n(\mathbb{R}^2))$ and the method returns its
irreducible components over $\mathbb{C}$.

In the case $i = n$, the algebraic boundary
$\partial_{alg}({\mathcal{R}}_{n,n})$ is the discriminant hypersurface; see the
paper by A. Causa and R. Re - On the maximum rank of a real binary form - Ann.
Mat. Pura Appl. 190, 55-59, 2011; see also the paper by P. Comon, G. Ottaviani
- On the typical rank of real binary forms - Linear Multilinear Algebra 60,
657-667, 2012.

+-----------------------------------------------------------------------------+
|i1 : D77 = realRankBoundary(7,7)                                             |
|                                                                             |
|o1 = CRL(2,1,1,1,1,1)                                                        |
|                                                                             |
|o1 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i2 : describe D77                                                            |
|                                                                             |
|o2 = Coincident root locus associated with the partition {2, 1, 1, 1, 1, 1}  |
|     ambient: P^7 = Proj(QQ[t_0..t_7])                                       |
|     dim    = 6                                                              |
|     codim  = 1                                                              |
|     degree = 12                                                             |
|     The singular locus is the union of the coincident root loci associated  |
|     ({2, 2, 1, 1, 1},{3, 1, 1, 1, 1})                                       |
|     The defining polynomial has 1103 terms of degree 12                     |
|-----------------------------------------------------------------------------|
|defined over QQ                                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|with the partitions:                                                         |
+-----------------------------------------------------------------------------+

In the opposite extreme case, $i = ceiling((n+1)/2)$, the algebraic boundary
$\partial_{alg}({\mathcal{R}}_{n,i})$ has been described in the paper by H. Lee
and B. Sturmfels - Duality of multiple root loci - J. Algebra 446, 499-526,
2016. It is irreducible if $n$ is odd, and has two irreducible components if
$n$ is even.

+-----------------------------------------------------------------------------+
|i3 : D64 = realRankBoundary(6,4)                                             |
|                                                                             |
|o3 = {CRL(5,1) * CRL(5,1) (dual of CRL(3,3)), CRL(4,1,1) * CRL(6) (dual of   |
|     ------------------------------------------------------------------------|
|     CRL(4,2))}                                                              |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : describe first D64                                                      |
|                                                                             |
|o4 = Dual of the coincident root locus associated with the partition {3, 3   |
|     which coincides with the join of the coincident root loci associated    |
|     ambient: P^6 = Proj(QQ[t_0..t_6])                                       |
|     dim    = 5                                                              |
|     codim  = 1                                                              |
|     degree = 12                                                             |
|     The defining polynomial has 560 terms of degree 12                      |
|-----------------------------------------------------------------------------|
|} defined over QQ                                                            |
|with the partitions: ({5, 1},{5, 1})                                         |
+-----------------------------------------------------------------------------+
|i5 : describe last D64                                                       |
|                                                                             |
|o5 = Dual of the coincident root locus associated with the partition {4, 2   |
|     which coincides with the join of the coincident root loci associated    |
|     ambient: P^6 = Proj(QQ[t_0..t_6])                                       |
|     dim    = 5                                                              |
|     codim  = 1                                                              |
|     degree = 18                                                             |
|     The defining polynomial has 3140 terms of degree 18                     |
|-----------------------------------------------------------------------------|
|} defined over QQ                                                            |
|with the partitions: ({4, 1, 1},{6})                                         |
+-----------------------------------------------------------------------------+
|i6 : D74 = realRankBoundary(7,4)                                             |
|                                                                             |
|o6 = CRL(6,1) * CRL(7) * CRL(7) (dual of CRL(3,2,2))                         |
|                                                                             |
|o6 : Join of 3 coincident root loci                                          |
+-----------------------------------------------------------------------------+
|i7 : describe D74                                                            |
|                                                                             |
|o7 = Dual of the coincident root locus associated with the partition {3, 2   |
|     which coincides with the join of the coincident root loci associated    |
|     ({6, 1},{7},{7})                                                        |
|     ambient: P^7 = Proj(QQ[t_0..t_7])                                       |
|     dim    = 6                                                              |
|     codim  = 1                                                              |
|     degree = 24                                                             |
|-----------------------------------------------------------------------------|
|, 2} defined over QQ                                                         |
|with the partitions:                                                         |
+-----------------------------------------------------------------------------+

In the next example, we compute the irreducible components of the algebraic
boundaries $\partial_{alg}({\mathcal{R}}_{7,5})$ and
$\partial_{alg}({\mathcal{R}}_{7,6})$.

+-----------------------------------------------------------------------------+
|i8 : D75 = realRankBoundary(7,5)                                             |
|                                                                             |
|o8 = {CRL(6,1) * CRL(7) * CRL(7) (dual of CRL(3,2,2)), CRL(5,1,1) * CRL(6,1) |
|     ------------------------------------------------------------------------|
|     (dual of CRL(4,3)), CRL(4,1,1,1) * CRL(7) (dual of CRL(5,2))}           |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : describe D75_0                                                          |
|                                                                             |
|o9 = Dual of the coincident root locus associated with the partition {3, 2   |
|     which coincides with the join of the coincident root loci associated    |
|     ({6, 1},{7},{7})                                                        |
|     ambient: P^7 = Proj(QQ[t_0..t_7])                                       |
|     dim    = 6                                                              |
|     codim  = 1                                                              |
|     degree = 24                                                             |
|-----------------------------------------------------------------------------|
|, 2} defined over QQ                                                         |
|with the partitions:                                                         |
+-----------------------------------------------------------------------------+
|i10 : describe D75_1                                                         |
|                                                                             |
|o10 = Dual of the coincident root locus associated with the partition {4, 3  |
|      which coincides with the join of the coincident root loci associated   |
|      ambient: P^7 = Proj(QQ[t_0..t_7])                                      |
|      dim    = 6                                                             |
|      codim  = 1                                                             |
|      degree = 36                                                            |
|-----------------------------------------------------------------------------|
|} defined over QQ                                                            |
|with the partitions: ({5, 1, 1},{6, 1})                                      |
+-----------------------------------------------------------------------------+
|i11 : describe D75_2                                                         |
|                                                                             |
|o11 = Dual of the coincident root locus associated with the partition {5, 2  |
|      which coincides with the join of the coincident root loci associated   |
|      ambient: P^7 = Proj(QQ[t_0..t_7])                                      |
|      dim    = 6                                                             |
|      codim  = 1                                                             |
|      degree = 24                                                            |
|-----------------------------------------------------------------------------|
|} defined over QQ                                                            |
|with the partitions: ({4, 1, 1, 1},{7})                                      |
+-----------------------------------------------------------------------------+
|i12 : D76 = realRankBoundary(7,6)                                            |
|                                                                             |
|o12 = {CRL(5,1,1) * CRL(6,1) (dual of CRL(4,3)), CRL(4,1,1,1) * CRL(7) (dual |
|      -----------------------------------------------------------------------|
|      of CRL(5,2)), CRL(2,1,1,1,1,1)}                                        |
|                                                                             |
|o12 : List                                                                   |
+-----------------------------------------------------------------------------+
|i13 : describe D76_0                                                         |
|                                                                             |
|o13 = Dual of the coincident root locus associated with the partition {4, 3  |
|      which coincides with the join of the coincident root loci associated   |
|      ambient: P^7 = Proj(QQ[t_0..t_7])                                      |
|      dim    = 6                                                             |
|      codim  = 1                                                             |
|      degree = 36                                                            |
|-----------------------------------------------------------------------------|
|} defined over QQ                                                            |
|with the partitions: ({5, 1, 1},{6, 1})                                      |
+-----------------------------------------------------------------------------+
|i14 : describe D76_1                                                         |
|                                                                             |
|o14 = Dual of the coincident root locus associated with the partition {5, 2  |
|      which coincides with the join of the coincident root loci associated   |
|      ambient: P^7 = Proj(QQ[t_0..t_7])                                      |
|      dim    = 6                                                             |
|      codim  = 1                                                             |
|      degree = 24                                                            |
|-----------------------------------------------------------------------------|
|} defined over QQ                                                            |
|with the partitions: ({4, 1, 1, 1},{7})                                      |
+-----------------------------------------------------------------------------+
|i15 : describe D76_2                                                         |
|                                                                             |
|o15 = Coincident root locus associated with the partition {2, 1, 1, 1, 1, 1} |
|      ambient: P^7 = Proj(QQ[t_0..t_7])                                      |
|      dim    = 6                                                             |
|      codim  = 1                                                             |
|      degree = 12                                                            |
|      The singular locus is the union of the coincident root loci associated |
|      ({2, 2, 1, 1, 1},{3, 1, 1, 1, 1})                                      |
|      The defining polynomial has 1103 terms of degree 12                    |
|-----------------------------------------------------------------------------|
|defined over QQ                                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|with the partitions:                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * CoincidentRootLocus -- the class of all
    coincident root loci
  * dual(CoincidentRootLocus) -- the
    projectively dual to a coincident root locus
  * realrank -- compute the real rank

Ways to use realRankBoundary :
==============================

  * "realRankBoundary(ZZ,ZZ)"
  * "realRankBoundary(ZZ,ZZ,Ring)"

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

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

realroots -- real roots of a binary form
****************************************

Synopsis
========

  * Usage:
        realroots F
  * Inputs:
      * F, a ring element (Macaulay2Doc), a binary form over
        $\mathbb{Q}$
  * Optional inputs (Macaulay2Doc),:
      * Verbose, => ...,
        default value false, request verbose feedback
  * Outputs:
      * a list (Macaulay2Doc), a list of pairs of elements of
        RR (Macaulay2Doc), the real roots of $F$ (multiple roots appear
        multiple times)

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

This is a simple application of the method roots (Macaulay2Doc).

+-----------------------------------------------+
|i1 : F = randomBinaryForm 5                    |
|                                               |
|        5     4       3 2     2 3       4     5|
|o1 = 18t  + 2t t  + 9t t  + 2t t  + 4t t  + 3t |
|        0     0 1     0 1     0 1     0 1     1|
|                                               |
|o1 : QQ[t ..t ]                                |
|         0   1                                 |
+-----------------------------------------------+
|i2 : realroots F                               |
|                                               |
|o2 = {[-.495276, 1]}                           |
|                                               |
|o2 : List                                      |
+-----------------------------------------------+

See also
========

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

Ways to use realroots :
=======================

  * "realroots(RingElement)"

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

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

recover -- recover the binary form from its apolar ideal
********************************************************

Synopsis
========

  * Usage:
        recover I
  * Inputs:
      * I, an ideal (Macaulay2Doc), the apolar ideal of a binary
        form $F\in K[x,y]$, or one of its homogeneous components of
        sufficiently large degree
  * Outputs:
      * a ring element (Macaulay2Doc), the binary form $F$
        (up to a multiplicative constant)

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

+-----------------------------------------------------------------------------+
|i1 : F = randomBinaryForm 7                                                  |
|                                                                             |
|        7     6       5 2     4 3     3 4     2 5       6     7              |
|o1 = 18t  + 2t t  + 9t t  + 2t t  + 4t t  + 3t t  + 6t t  + 3t               |
|        0     0 1     0 1     0 1     0 1     0 1     0 1     1              |
|                                                                             |
|o1 : QQ[t ..t ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i2 : I = apolar F                                                            |
|                                                                             |
|                  4          3             2 2             3          4      |
|o2 = ideal (75621t  + 740842t t  - 3587636t t  - 2099787t t  + 741116t ,     |
|                  0          0 1           0 1           0 1          1      |
|     ------------------------------------------------------------------------|
|          3 2        2 3          4        5                                 |
|     1355t t  - 5785t t  - 3840t t  + 1321t )                                |
|          0 1        0 1        0 1        1                                 |
|                                                                             |
|o2 : Ideal of QQ[t ..t ]                                                     |
|                  0   1                                                      |
+-----------------------------------------------------------------------------+
|i3 : I5 = apolar(F,5)                                                        |
|                                                                             |
|                 3 2        2 3          4        5       4          2 3     |
|o3 = ideal (1355t t  - 5785t t  - 3840t t  + 1321t , 1355t t  - 7610t t  -   |
|                 0 1        0 1        0 1        1       0 1        0 1     |
|     ------------------------------------------------------------------------|
|         4       5      5         2 3           4         5                  |
|     5t t  + 338t , 271t  - 47505t t  - 33770t t  + 11872t )                 |
|       0 1       1      0         0 1         0 1         1                  |
|                                                                             |
|o3 : Ideal of QQ[t ..t ]                                                     |
|                  0   1                                                      |
+-----------------------------------------------------------------------------+
|i4 : recover I                                                               |
|                                                                             |
|        7     6       5 2     4 3     3 4     2 5       6     7              |
|o4 = 18t  + 2t t  + 9t t  + 2t t  + 4t t  + 3t t  + 6t t  + 3t               |
|        0     0 1     0 1     0 1     0 1     0 1     0 1     1              |
|                                                                             |
|o4 : QQ[t ..t ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i5 : recover I5                                                              |
|                                                                             |
|        7     6       5 2     4 3     3 4     2 5       6     7              |
|o5 = 18t  + 2t t  + 9t t  + 2t t  + 4t t  + 3t t  + 6t t  + 3t               |
|        0     0 1     0 1     0 1     0 1     0 1     0 1     1              |
|                                                                             |
|o5 : QQ[t ..t ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+

See also
========

  * apolar(ZZ,ZZ) -- the apolar map
  * apolar(RingElement) -- the apolar ideal
  * apolar(RingElement,ZZ) -- homogeneous
    components of the apolar ideal

Ways to use recover :
=====================

  * "recover(Ideal)"
  * "recover(RingElement,RingElement)"

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

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

ring(CoincidentRootLocus) -- get the ring of a coincident root locus
********************************************************************

Synopsis
========

  * Function: ring (Macaulay2Doc),
  * Usage:
        ring X
  * Inputs:
      * X, a coincident root locus,
  * Outputs:
      * a ring (Macaulay2Doc), the coordinate ring of the target of
        the map of X

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

+--------------------------------------------------------+
|i1 : X = coincidentRootLocus {3,2}                      |
|                                                        |
|o1 = CRL(3,2)                                           |
|                                                        |
|o1 : Coincident root locus                              |
+--------------------------------------------------------+
|i2 : ring X                                             |
|                                                        |
|o2 = QQ[t ..t ]                                         |
|         0   5                                          |
|                                                        |
|o2 : PolynomialRing                                     |
+--------------------------------------------------------+
|i3 : X' = coincidentRootLocus({3,2},ZZ/3331,Variable=>x)|
|                                                        |
|o3 = CRL(3,2;ZZ/3331;'x')                               |
|                                                        |
|o3 : Coincident root locus                              |
+--------------------------------------------------------+
|i4 : ring X'                                            |
|                                                        |
|      ZZ                                                |
|o4 = ----[x ..x ]                                       |
|     3331  0   5                                        |
|                                                        |
|o4 : PolynomialRing                                     |
+--------------------------------------------------------+

See also
========

  * coefficientRing(CoincidentRootLocus)
    -- get the coefficient ring
  * map(CoincidentRootLocus) -- the map
    associated to a coincident root locus
  * target(RationalMap) (Cremona) -- coordinate
    ring of the target for a rational map

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

  * ring(CoincidentRootLocus) -- get the
    ring of a coincident root locus

singularLocus(CoincidentRootLocus) -- the singular locus of a coincident root locus
***********************************************************************************

Synopsis
========

  * Function: singularLocus (Macaulay2Doc),
  * Usage:
        singularLocus X
  * Inputs:
      * X, a coincident root locus,
  * Outputs:
      * a list (Macaulay2Doc), a list of coincident root loci such
        that their union coincides with the singular locus of X

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

The singular locus of a coincident root locus is the union of certain subloci,
as described in the paper by J. Chipalkatti - On equations defining coincident
root loci - J. Algebra 267, 246-271, 2003; see also the paper by S. Kurmann -
Some remarks on equations defining coincident root loci - J. Algebra 352,
223-231, 2012.

+-----------------------------------------------------------------------------+
|i1 : X = coincidentRootLocus {3,2,2,1,1,1,1}                                 |
|                                                                             |
|o1 = CRL(3,2,2,1,1,1,1)                                                      |
|                                                                             |
|o1 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i2 : singularLocus X                                                         |
|                                                                             |
|o2 = {CRL(4,4,3), CRL(3,3,2,2,1), CRL(3,2,2,2,1,1), CRL(5,2,1,1,1,1),        |
|     ------------------------------------------------------------------------|
|     CRL(4,2,2,1,1,1), CRL(3,3,2,1,1,1)}                                     |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * subsets(CoincidentRootLocus), --
    produce all the subloci

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

  * singularLocus(CoincidentRootLocus)
    -- the singular locus of a
    coincident root locus

subsets(CoincidentRootLocus) -- produce all the subloci
*******************************************************

Synopsis
========

  * Function: subsets (Macaulay2Doc),
  * Usage:
        subsets X
  * Inputs:
      * X, a coincident root locus,
  * Outputs:
      * a list (Macaulay2Doc), the list of the coincident root loci
        that are contained in X

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

+-----------------------------------------------------------------------------+
|i1 : X = coincidentRootLocus {5,2,2,1}                                       |
|                                                                             |
|o1 = CRL(5,2,2,1)                                                            |
|                                                                             |
|o1 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i2 : subsets X                                                               |
|                                                                             |
|o2 = {CRL(10), CRL(7,3), CRL(8,2), CRL(9,1), CRL(6,4), CRL(5,5), CRL(5,3,2), |
|     ------------------------------------------------------------------------|
|     CRL(5,4,1), CRL(6,2,2), CRL(7,2,1), CRL(5,2,2,1)}                       |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * isSubset(CoincidentRootLocus,CoincidentRootLocus)
    -- whether one
    object is a subset of another
  * supsets(CoincidentRootLocus), --
    produce all the suploci

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

  * subsets(CoincidentRootLocus), --
    produce all the subloci

supsets(CoincidentRootLocus) -- produce all the suploci
*******************************************************

Synopsis
========

  * Function: supsets,
  * Usage:
        supsets X
  * Inputs:
      * X, a coincident root locus,
  * Outputs:
      * a list (Macaulay2Doc), the list of the coincident root loci
        that contain X

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

+-----------------------------------------------------------------------------+
|i1 : X = coincidentRootLocus {4,2}                                           |
|                                                                             |
|o1 = CRL(4,2)                                                                |
|                                                                             |
|o1 : Coincident root locus                                                   |
+-----------------------------------------------------------------------------+
|i2 : supsets X                                                               |
|                                                                             |
|o2 = {CRL(4,2), CRL(3,2,1), CRL(4,1,1), CRL(2,2,2), CRL(2,2,1,1),            |
|     ------------------------------------------------------------------------|
|     CRL(3,1,1,1), CRL(2,1,1,1,1), CRL(1,1,1,1,1,1)}                         |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * isSubset(CoincidentRootLocus,CoincidentRootLocus)
    -- whether one
    object is a subset of another
  * subsets(CoincidentRootLocus), --
    produce all the subloci

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

  * supsets(CoincidentRootLocus), --
    produce all the suploci

switch(RingElement)
*******************

Synopsis
========

  * Function: switch (Macaulay2Doc),

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

A binary form $F(t_0,t_1) =
a_0\,t_0^n+n\,a_1\,t_0^{n-1}\,t_1+1/2\,n\,(n-1)\,a_2\,t_0^{n-2}\,t_1^2+\,\cdots
\,+n\,a_{n-1}\,t_0\,t_1^{n-1}+a_n\,t_1^n$ can be identified with the list
$\{a_0,a_1,\ldots,a_n\}$ of its coefficients, and also with the ideal of the
corresponding point of $\mathbb{P}^n$. The method switch when applied to a
binary form returns the list of its coefficients; when applied to a list of
coefficients returns the ideal of the corresponding point; when applied to the
ideal of a point returns the corresponding binary form.

+-----------------------------------------------------------------------------+
|i1 : F = randomBinaryForm 9                                                  |
|                                                                             |
|         9      8        7 2      6 3      5 4      4 5      3 6      2 7    |
|o1 = 162t  + 18t t  + 81t t  + 18t t  + 36t t  + 27t t  + 54t t  + 27t t  +  |
|         0      0 1      0 1      0 1      0 1      0 1      0 1      0 1    |
|     ------------------------------------------------------------------------|
|          8      9                                                           |
|     63t t  + 28t                                                            |
|        0 1      1                                                           |
|                                                                             |
|o1 : QQ[t ..t ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i2 : L = switch F                                                            |
|                                                                             |
|              9   3  2   3   9  3                                            |
|o2 = {162, 2, -, --, -, --, --, -, 7, 28}                                    |
|              4  14  7  14  14  4                                            |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : I = switch L                                                            |
|                                                                             |
|o3 = ideal (4t  - t , 112t  - 3t , 392t  - 9t , 392t  - 3t , 98t  - t , 392t |
|              8    9      7     9      6     9      5     9     4    9      3|
|     ------------------------------------------------------------------------|
|     - 3t , 112t  - 9t , 14t  - t , 14t  - 81t )                             |
|         9      2     9     1    9     0      9                              |
|                                                                             |
|o3 : Ideal of QQ[t ..t ]                                                     |
|                  0   9                                                      |
+-----------------------------------------------------------------------------+
|i4 : switch I                                                                |
|                                                                             |
|         9      8        7 2      6 3      5 4      4 5      3 6      2 7    |
|o4 = 162t  + 18t t  + 81t t  + 18t t  + 36t t  + 27t t  + 54t t  + 27t t  +  |
|         0      0 1      0 1      0 1      0 1      0 1      0 1      0 1    |
|     ------------------------------------------------------------------------|
|          8      9                                                           |
|     63t t  + 28t                                                            |
|        0 1      1                                                           |
|                                                                             |
|o4 : QQ[t ..t ]                                                              |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i5 : oo == F                                                                 |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+

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

  * "switch(Ideal)"
  * "switch(List)"
  * switch(RingElement)