This is DeterminantalRepresentations.info, produced by Macaulay2, version 1.21

DeterminantalRepresentations -- computing determinantal representations of polynomials
**************************************************************************************

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

The goal of this package is to compute symmetric determinantal representations
of real polynomials. A polynomial $f$ in $\mathbb{R}[x_1, \ldots, x_n]$ of
total degree $d$ (not necessarily homogeneous) is called determinantal if $f$
is the determinant of a matrix of linear forms - in other words, there exist
matrices $A_0, \ldots, A_n\in \mathbb{R}^{d\times d}$ such that $f(x_1, \ldots,
x_n) = det(A_0 + x_1A_1 + \ldots + x_nA_n)$. The matrix pencil $A_0 + x_1A_1 +
\ldots + x_nA_n$ is said to give a determinantal representation of $f$ of size
$d$. If the matrices $A_i$ can be chosen to be all symmetric, then the
determinantal representation is called symmetric. The determinantal
representation is called definite if $A_0$ is positive definite, and monic if
$A_0 = I_d$ is the identity matrix.

Deciding whether or not a degree $d$ polynomial has a determinantal
representation of size $d$ is in general difficult, and computing such a
representation even more so. Computing (monic) symmetric determinantal
representations (even in 2 variables) is of interest owing to a connection with
real-zero and hyperbolic polynomials, due to a celebrated theorem of
Helton-Vinnikov. In general, determinantal polynomials also have connections to
convex algebraic geometry and semidefinite programming.

Currently, the functions in this package are geared towards computing monic
symmetric determinantal representations of quadrics, as well as plane curves of
low degree (i.e., cubics and quartics). The algorithms implemented in this
package can be found in [1], [2].

Additionally, a number of helper functions are included for creating/working
with various classes of matrices, which may be of general interest (and are not
limited to the scope of determinantal representations). These include:
creating/testing orthogonal, symmetric, doubly stochastic, unipotent, and
positive semidefinite matrices, Hadamard products, Cholesky decomposition, and
lifting/rounding matrices from CC (Macaulay2Doc), to RR (Macaulay2Doc),
/see QQ (Macaulay2Doc).

References:

  * [1] Dey, P., Definite Determinantal Representations via Orthostochastic
    Matrices, arXiv:1708.09559 (see http://arxiv.org/abs/1708.09559 )
  * [2] Dey, P., Definite Determinantal Representations of Multivariate
    Polynomials, arXiv:1708.09557 (see http://arxiv.org/abs/1708.09557 )

Authors
=======

  * Justin Chen <jchen646@gatech.edu>
  * Papri Dey <papridey@berkeley.edu>

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

Version 1.3.0 of this package was accepted for publication in volume 10 (see
https://msp.org/jsag/2020/10-1/ ) of The Journal of Software for Algebra and
Geometry (see http://j-sag.org/ ) on 5 December 2019, in the article Computing
symmetric determinantal representations (see
https://msp.org/jsag/2020/10-1/p02.xhtml ). That version can be obtained from
the journal (see https://msp.org/jsag/2020/10-1/jsag-v10-n1-x02-
DeterminantalRepresentations.m2 ) or from the Macaulay2 source code repository
(see http://github.com/Macaulay2/M2/blob/
f3c4030a3e66ae51f54ec24a89e1d5b1992a82eb/M2/Macaulay2/packages/
DeterminantalRepresentations.m2 ).

Version
=======

This documentation describes version 1.3.1 of DeterminantalRepresentations.

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

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

Exports
=======

  * Functions and commands
      * bivariateDiagEntries -- computes diagonal
        entries and eigenvalues for a determinantal representation of a
        bivariate polynomial
      * cholesky -- computes the Cholesky decomposition of a
        positive semidefinite matrix
      * coeffMatrices -- gets coefficient matrices for a
        matrix of linear forms
      * companionMatrix -- companion matrix of a
        univariate polynomial
      * detRep -- compute determinantal representations
      * generalizedMixedDiscriminant, --
        computes generalized mixed discriminant of a list of matrices
      * hadamard -- computes the Hadamard product of two
        matrices
      * isDoublyStochastic -- whether a matrix is
        doubly stochastic
      * isOrthogonal -- whether a matrix is orthogonal
      * orthogonalFromOrthostochastic, --
        computes orthogonal matrices for a given orthostochastic matrix
      * randomIntegerSymmetric -- constructs a
        random integer symmetric matrix
      * randomOrthogonal -- constructs a random
        special orthogonal matrix
      * randomPSD -- constructs a random positive
        semidefinite matrix
      * randomUnipotent -- constructs a random
        unipotent matrix
      * realPartMatrix -- real part of a matrix over CC
      * roundMatrix -- lifts matrix over RR to matrix over
        QQ
  * Methods
      * "bivariateDiagEntries(RingElement)" -- see bivariateDiagEntries,
        -- computes diagonal entries and eigenvalues for
        a determinantal representation of a bivariate polynomial
      * "cholesky(Matrix)" -- see cholesky, -- computes the
        Cholesky decomposition of a positive semidefinite matrix
      * "coeffMatrices(Matrix)" -- see coeffMatrices, --
        gets coefficient matrices for a matrix of linear forms
      * "companionMatrix(RingElement)" -- see companionMatrix,
        -- companion matrix of a univariate polynomial
      * "detRep(RingElement)" -- see detRep, -- compute
        determinantal representations
      * "generalizedMixedDiscriminant(List)" -- see
        generalizedMixedDiscriminant, -- computes
        generalized mixed discriminant of a list of matrices
      * "hadamard(Matrix,Matrix)" -- see hadamard, -- computes
        the Hadamard product of two matrices
      * "isDoublyStochastic(Matrix)" -- see isDoublyStochastic,
        -- whether a matrix is doubly stochastic
      * "isOrthogonal(Matrix)" -- see isOrthogonal, --
        whether a matrix is orthogonal
      * "orthogonalFromOrthostochastic(Matrix)" -- see
        orthogonalFromOrthostochastic, --
        computes orthogonal matrices for a given orthostochastic matrix
      * "randomIntegerSymmetric(ZZ)" -- see randomIntegerSymmetric,
        -- constructs a random integer symmetric matrix
      * "randomIntegerSymmetric(ZZ,Ring)" -- see randomIntegerSymmetric,
        -- constructs a random integer symmetric matrix
      * "randomOrthogonal(ZZ)" -- see randomOrthogonal,
        -- constructs a random special orthogonal matrix
      * "randomOrthogonal(ZZ,Thing)" -- see randomOrthogonal,
        -- constructs a random special orthogonal matrix
      * "randomPSD(ZZ)" -- see randomPSD, -- constructs a
        random positive semidefinite matrix
      * "randomPSD(ZZ,RR)" -- see randomPSD, -- constructs a
        random positive semidefinite matrix
      * "randomPSD(ZZ,ZZ)" -- see randomPSD, -- constructs a
        random positive semidefinite matrix
      * "randomPSD(ZZ,ZZ,RR)" -- see randomPSD, -- constructs
        a random positive semidefinite matrix
      * "randomUnipotent(ZZ)" -- see randomUnipotent, --
        constructs a random unipotent matrix
      * "randomUnipotent(ZZ,Thing)" -- see randomUnipotent,
        -- constructs a random unipotent matrix
      * "realPartMatrix(Matrix)" -- see realPartMatrix,
        -- real part of a matrix over CC
      * "roundMatrix(ZZ,Matrix)" -- see roundMatrix, --
        lifts matrix over RR to matrix over QQ
  * Symbols
      * "HyperbolicPt" -- see Determinantal representations of hyperbolic plane cubics,

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

The object DeterminantalRepresentations, is a package (Macaulay2Doc).

bivariateDiagEntries -- computes diagonal entries and eigenvalues for a determinantal representation of a bivariate polynomial
******************************************************************************************************************************

Synopsis
========

  * Usage:
        bivariateDiagEntries f
        bivariateDiagEntries(f, Tolerance => 1e-6)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a bivariate
        polynomial with real coefficients
  * Optional inputs (Macaulay2Doc),:
      * Tolerance => ..., default value .000001
  * Outputs:
      * a sequence (Macaulay2Doc), of eigenvalues and diagonal
        entries of a determinantal representation of $f$

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

This method computes the eigenvalues and diagonal entries of a monic symmetric
determinantal representation of a real bivariate polynomial $f$, or gives an
error if certain necessary conditions for existence of such a representation
are not met. For a symmetric determinantal representation $f = det(I + x_1A_1 +
x_2A_2)$, this method computes diagonal entries and eigenvalues of $A_1$ and
$A_2$. The output is a 4-tuple of column vectors: (eigenvalues of A_1,
eigenvalues of $A_2$, diagonal entries of $A_1$, diagonal entries of $A_2$).

When working over an InexactFieldFamily (Macaulay2Doc),
like RR (Macaulay2Doc), or CC (Macaulay2Doc),
the option Tolerance can be used to specify the internal
threshold for checking equality (any floating point number below the tolerance
is treated as numerically zero).

+---------------------------------------------------------+
|i1 : R = RR[x1, x2]                                      |
|                                                         |
|o1 = R                                                   |
|                                                         |
|o1 : PolynomialRing                                      |
+---------------------------------------------------------+
|i2 : f = 15*x1^2 + 20*x1*x2 - 36*x2^2 + 20*x1 + 16*x2 + 1|
|                                                         |
|         2                 2                             |
|o2 = 15x1  + 20x1*x2 - 36x2  + 20x1 + 16x2 + 1           |
|                                                         |
|o2 : R                                                   |
+---------------------------------------------------------+
|i3 : bivariateDiagEntries f                              |
|                                                         |
|o3 = (| 19.2195 |, | 18 |, | 17 |, | 15.5926 |)          |
|      | .780456 |  | -2 |  | 3  |  | .407434 |           |
|                                                         |
|o3 : Sequence                                            |
+---------------------------------------------------------+

See also
========

  * detRep -- compute determinantal representations
  * Determinantal representations of bivariate polynomials
  * Determinantal representations of hyperbolic plane cubics

Ways to use bivariateDiagEntries :
==================================

  * "bivariateDiagEntries(RingElement)"

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

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

cholesky -- computes the Cholesky decomposition of a positive semidefinite matrix
*********************************************************************************

Synopsis
========

  * Usage:
        cholesky A
  * Inputs:
      * A, an $n\times n$ PSD matrix
  * Optional inputs (Macaulay2Doc),:
      * Tolerance => ..., default value .000001
  * Outputs:
      * L, a matrix (Macaulay2Doc), a lower-triangular matrix,
        with $A = LL^T$

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

This method computes the Cholesky decomposition of a symmetric positive
semidefinite matrix $A$, which is a factorization $A = LL^T$, where $L$ is
lower-triangular. If $A$ is not positive-definite, then the Cholesky
decomposition is not unique - in this case, this method will attempt to give an
output which is as sparse as possible.

When working over an InexactFieldFamily (Macaulay2Doc),
like RR (Macaulay2Doc), or CC (Macaulay2Doc),
the option Tolerance can be used to specify the internal
threshold for checking equality (any floating point number below the tolerance
is treated as numerically zero).

+----------------------------------------------------------------------------+
|i1 : A = randomPSD 5 -- 5x5 PSD of full rank                                |
|                                                                            |
|o1 = | .585298   -.0545901 .0184505  -.0599728  -.149145   |                |
|     | -.0545901 .761001   -.0118983 -.160458   -.02979    |                |
|     | .0184505  -.0118983 .56512    .0605255   -.0250409  |                |
|     | -.0599728 -.160458  .0605255  .609506    -.00367036 |                |
|     | -.149145  -.02979   -.0250409 -.00367036 .761799    |                |
|                                                                            |
|                5          5                                                |
|o1 : Matrix RR    <--- RR                                                   |
|              53         53                                                 |
+----------------------------------------------------------------------------+
|i2 : L = cholesky A                                                         |
|                                                                            |
|o2 = | .765048   0         0         0         0      |                     |
|     | -.0713552 .869431   0         0         0      |                     |
|     | .0241168  -.0117059 .751266   0         0      |                     |
|     | -.078391  -.190989  .0801052  .748643   0      |                     |
|     | -.194949  -.0502634 -.0278566 -.0351581 .84809 |                     |
|                                                                            |
|                5          5                                                |
|o2 : Matrix RR    <--- RR                                                   |
|              53         53                                                 |
+----------------------------------------------------------------------------+
|i3 : clean(1e-12, A - L*transpose L) == 0                                   |
|                                                                            |
|o3 = true                                                                   |
+----------------------------------------------------------------------------+
|i4 : B = randomPSD(7, 3) -- 7x7 PSD matrix of rank 3                        |
|                                                                            |
|o4 = | .174021  .0402662  .192987  .117982   .118213   -.124471  .0219834  ||
|     | .0402662 .211585   .0846263 .192158   -.224018  .0837642  -.0805872 ||
|     | .192987  .0846263  .222408  .159648   .0747663  -.128752  .0127036  ||
|     | .117982  .192158   .159648  .243413   -.0734574 .107218   -.0954143 ||
|     | .118213  -.224018  .0747663 -.0734574 .483189   -.0482137 .0499495  ||
|     | -.124471 .0837642  -.128752 .107218   -.0482137 .494878   -.202561  ||
|     | .0219834 -.0805872 .0127036 -.0954143 .0499495  -.202561  .0954897  ||
|                                                                            |
|                7          7                                                |
|o4 : Matrix RR    <--- RR                                                   |
|              53         53                                                 |
+----------------------------------------------------------------------------+
|i5 : L = cholesky B                                                         |
|                                                                            |
|o5 = | .417158  0        0        0 0 0 0 |                                 |
|     | .096525  .449742  0        0 0 0 0 |                                 |
|     | .462623  .0888769 .0221228 0 0 0 0 |                                 |
|     | .282823  .366563  -.170457 0 0 0 0 |                                 |
|     | .283377  -.558922 -.300821 0 0 0 0 |                                 |
|     | -.298379 .250289  -.585836 0 0 0 0 |                                 |
|     | .052698  -.190496 .237537  0 0 0 0 |                                 |
|                                                                            |
|                7          7                                                |
|o5 : Matrix RR    <--- RR                                                   |
|              53         53                                                 |
+----------------------------------------------------------------------------+
|i6 : clean(1e-12, B - L*transpose L) == 0                                   |
|                                                                            |
|o6 = true                                                                   |
+----------------------------------------------------------------------------+

Ways to use cholesky :
======================

  * "cholesky(Matrix)"

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

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

coeffMatrices -- gets coefficient matrices for a matrix of linear forms
***********************************************************************

Synopsis
========

  * Usage:
        coeffMatrices(M)
  * Inputs:
      * M, a matrix (Macaulay2Doc), of linear forms
  * Outputs:
      * a list (Macaulay2Doc), of matrices

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

Given a linear matrix pencil $M = I_d + x_1A_1 + ... + x_nA_n$, this method
returns the list of matrices $A_1, ..., A_n$.

+-----------------------------------------------------------------------+
|i1 : R = QQ[x,y,z]                                                     |
|                                                                       |
|o1 = R                                                                 |
|                                                                       |
|o1 : PolynomialRing                                                    |
+-----------------------------------------------------------------------+
|i2 : M = id_(R^3) + random(R^3,R^{3:-1})                               |
|                                                                       |
|o2 = | 9/2x+1/2y+9/4z+1 7/9x+7/10y+1/2z 2/3x+y+2z    |                 |
|     | 1/2x+y+3/4z      7/10x+7/3y+7z+1 6x+5/4y+2/9z |                 |
|     | 3/2x+3/4y+7/4z   3/7x+5/2y+6/7z  5x+3/10y+z+1 |                 |
|                                                                       |
|             3       3                                                 |
|o2 : Matrix R  <--- R                                                  |
+-----------------------------------------------------------------------+
|i3 : coeffs = coeffMatrices M                                          |
|                                                                       |
|o3 = {{1} | 9/2 7/9  2/3 |, {1} | 1/2 7/10 1    |, {1} | 9/4 1/2 2   |}|
|      {1} | 1/2 7/10 6   |  {1} | 1   7/3  5/4  |  {1} | 3/4 7   2/9 | |
|      {1} | 3/2 3/7  5   |  {1} | 3/4 5/2  3/10 |  {1} | 7/4 6/7 1   | |
|                                                                       |
|o3 : List                                                              |
+-----------------------------------------------------------------------+
|i4 : M - sum(#gens R, i -> R_i*coeffs#i)                               |
|                                                                       |
|o4 = | 1 0 0 |                                                         |
|     | 0 1 0 |                                                         |
|     | 0 0 1 |                                                         |
|                                                                       |
|             3       3                                                 |
|o4 : Matrix R  <--- R                                                  |
+-----------------------------------------------------------------------+

Caveat
======

This method does not return the constant term, or coefficients of terms of
degree $> 1$.

Ways to use coeffMatrices :
===========================

  * "coeffMatrices(Matrix)"

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

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

companionMatrix -- companion matrix of a univariate polynomial
**************************************************************

Synopsis
========

  * Usage:
        companionMatrix f
  * Inputs:
      * f, a ring element (Macaulay2Doc), a univariate
        polynomial
  * Outputs:
      * a matrix (Macaulay2Doc),

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

For a monic univariate polynomial $f$ of degree $d$, this method returns the
companion matrix $C(f)$, which is a $d\times d$ matrix whose characteristic
polynomial is $f$. Explicitly, $C(f)$ has entries $1$ on the first subdiagonal
(the diagonal below the main diagonal), negative coefficients of $f$ in the
last column (other than the leading coefficient of $1$), and $0$ elsewhere.

If $f$ is not monic, then this method returns the companion matrix of the
normalized monic polynomial $(1/a_n)f$, where $a_n$ is the leading coefficient
of $f$.

+-----------------------------------------------------------------------------+
|i1 : R = CC[x]                                                               |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : eigenvalues companionMatrix(9*x^2 - 1)                                  |
|                                                                             |
|o2 = {.333333 }                                                              |
|     {-.333333}                                                              |
|                                                                             |
|o2 : VerticalList                                                            |
+-----------------------------------------------------------------------------+
|i3 : f = x^10 + sum(10, i -> random(i, R))                                   |
|-- warning: experimental computation over inexact field begun                |
|--          results not reliable (one warning given per session)             |
|                                                                             |
|      10                          9                          8               |
|o3 = x   + (.741046 + .108386*ii)x  + (.127435 + .254482*ii)x  + (.362835 +  |
|     ------------------------------------------------------------------------|
|                 7                           6                          5    |
|     .706096*ii)x  + (.0741835 + .808694*ii)x  + (.909047 + .314897*ii)x  +  |
|     ------------------------------------------------------------------------|
|                            4                         3                      |
|     (.461944 + .775187*ii)x  + (.89189 + .231053*ii)x  + (.0258884 +        |
|     ------------------------------------------------------------------------|
|                 2                                                           |
|     .714827*ii)x  + (.29398 + .632944*ii)x + .892712 + .673395*ii           |
|                                                                             |
|o3 : R                                                                       |
+-----------------------------------------------------------------------------+
|i4 : C = companionMatrix f                                                   |
|                                                                             |
|o4 = | 0 0 0 0 0 0 0 0 0 -.892712-.673395ii  |                               |
|     | 1 0 0 0 0 0 0 0 0 -.29398-.632944ii   |                               |
|     | 0 1 0 0 0 0 0 0 0 -.0258884-.714827ii |                               |
|     | 0 0 1 0 0 0 0 0 0 -.89189-.231053ii   |                               |
|     | 0 0 0 1 0 0 0 0 0 -.461944-.775187ii  |                               |
|     | 0 0 0 0 1 0 0 0 0 -.909047-.314897ii  |                               |
|     | 0 0 0 0 0 1 0 0 0 -.0741835-.808694ii |                               |
|     | 0 0 0 0 0 0 1 0 0 -.362835-.706096ii  |                               |
|     | 0 0 0 0 0 0 0 1 0 -.127435-.254482ii  |                               |
|     | 0 0 0 0 0 0 0 0 1 -.741046-.108386ii  |                               |
|                                                                             |
|                10          10                                               |
|o4 : Matrix CC     <--- CC                                                   |
|              53          53                                                 |
+-----------------------------------------------------------------------------+
|i5 : clean(1e-10, f - det(x*id_(R^10) - C))                                  |
|                                                                             |
|o5 = 0                                                                       |
|                                                                             |
|o5 : R                                                                       |
+-----------------------------------------------------------------------------+
|i6 : all(eigenvalues C, z -> clean(1e-10, sub(f, R_0 => z)) == 0)            |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

Ways to use companionMatrix :
=============================

  * "companionMatrix(RingElement)"

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

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

Determinantal representations of bivariate polynomials
******************************************************

This page demonstrates how the method detRep, computes a monic
symmetric determinantal representation of a bivariate polynomial, if such a
representation exists.

First, if the polynomial $f$ is homogeneous, then over CC (Macaulay2Doc),
$f$ splits as a product of linear forms, and it admits a
real symmetric determinantal representation if and only if all the linear
factors are defined over RR (Macaulay2Doc). If this is the case, this
method returns the diagonal matrix of linear factors of $f$, which is a
symmetric determinantal representation:

+----------------------------------------------------------+
|i1 : R = RR[x,y]                                          |
|                                                          |
|o1 = R                                                    |
|                                                          |
|o1 : PolynomialRing                                       |
+----------------------------------------------------------+
|i2 : detRep(x^2 - 3*y^2)                                  |
|No determinantal representation                           |
+----------------------------------------------------------+
|i3 : detRep(x^5+6*x^4*y-2*x^3*y^2-36*x^2*y^3+x*y^4+30*y^5)|
|                                                          |
|o3 = {| x-1y 0    0    0    0   |}                        |
|      | 0    x-2y 0    0    0   |                         |
|      | 0    0    x+5y 0    0   |                         |
|      | 0    0    0    x+3y 0   |                         |
|      | 0    0    0    0    x+y |                         |
|                                                          |
|o3 : List                                                 |
+----------------------------------------------------------+

Here it is assumed that the dehomogenization of $f$ (with respect to the first
variable in its support (Macaulay2Doc)) is monic - this can
always be achieved by rescaling.

Now suppose $f$ is not homogeneous. For a symmetric determinantal
representation $f = det(I + x_1A_1 + x_2A_2)$, by suitable conjugation one may
assume $A_1 = D_1$ is a diagonal matrix. We also have that $D_1$ and the
diagonal entries of $A_2$ can be found using the method
bivariateDiagEntries. From this data, here are 2
approaches to numerically compute a determinantal representation of $f$,  which
can be specified by the option Strategy.

The first (and default) strategy is "DirectSystem", which computes the
off-diagonal entries of $A_2$ directly as solutions to a $(d choose 2)\times (d
choose 2)$ polynomial system.

The second strategy is "Orthogonal", which computes the orthogonal
change-of-basis matrices $V$ such that $VA_2V^T = D_2$ is diagonal. Since $D_2$
can be found using bivariateDiagEntries, $A_2$ can
be recovered from $V$.

Both strategies use numerical algebraic geometry, specifically a
numericalIrreducibleDecomposition (NumericalAlgebraicGeometry).

When working over an InexactFieldFamily (Macaulay2Doc),
like RR (Macaulay2Doc), or CC (Macaulay2Doc),
the option Tolerance can be used to specify the internal
threshold for checking equality (any floating point number below the tolerance
is treated as numerically zero). The option Software (NumericalAlgebraicGeometry),
specifies the numerical algebraic
geometry software used to perform a numerical irreducible decomposition: by
default, the native routines provided by Macaulay2 are used, although other
valid options include BERTINI and PHCPACK (if the user has these installed on
their system).

+----------------------------------------------------------------+
|i4 : R = RR[x1, x2]                                             |
|                                                                |
|o4 = R                                                          |
|                                                                |
|o4 : PolynomialRing                                             |
+----------------------------------------------------------------+
|i5 : f=(1/2)*(x1^4+x2^4-3*x1^2-3*x2^2+x1^2*x2^2)+1              |
|                                                                |
|         4       2  2       4        2        2                 |
|o5 = .5x1  + .5x1 x2  + .5x2  - 1.5x1  - 1.5x2  + 1             |
|                                                                |
|o5 : R                                                          |
+----------------------------------------------------------------+
|i6 : repList = detRep f;                                        |
|-- warning: experimental computation over inexact field begun   |
|--          results not reliable (one warning given per session)|
+----------------------------------------------------------------+
|i7 : #repList                                                   |
|                                                                |
|o7 = 64                                                         |
+----------------------------------------------------------------+
|i8 : repList#0                                                  |
|                                                                |
|o8 = | 1x1+1      -.442783x2  .691504x2    -.317837x2 |         |
|     | -.442783x2 .707107x1+1 .224745x2    .691504x2  |         |
|     | .691504x2  .224745x2   -.707107x1+1 .442783x2  |         |
|     | -.317837x2 .691504x2   .442783x2    -x1+1      |         |
|                                                                |
|             4       4                                          |
|o8 : Matrix R  <--- R                                           |
+----------------------------------------------------------------+
|i9 : all(repList, A -> clean(1e-10, f - det A) == 0)            |
|                                                                |
|o9 = true                                                       |
+----------------------------------------------------------------+

Caveat
======

As this algorithm implements relatively brute-force algorithms, it may not
terminate for non-homogeneous polynomials of large degree (e.g., degree >= 5).

See also
========

  * detRep -- compute determinantal representations
  * bivariateDiagEntries -- computes diagonal
    entries and eigenvalues for a determinantal representation of a bivariate
    polynomial

Determinantal representations of hyperbolic plane cubics
********************************************************

This page demonstrates how the method detRep, computes monic
symmetric determinantal representations of a hyperbolic cubic $f$ in $3$
variables, or gives an error if certain necessary conditions for existence of
such a representation are not met. First, the polynomial is dehomogenized to
obtain a bivariate polynomial. Next, if $f = det(I + x_1A_1 + x_2A_2)$ is a
symmetric determinantal representation, then by suitable conjugation one may
assume $A_1 = D_1$ is a diagonal matrix. Since $A_2$ is symmetric, there exists
an orthogonal change-of-basis matrix $V$ such that $VA_2V^T = D_2$ is diagonal.
Since $D_1, D_2$ can be found using the method bivariateDiagEntries,
to find a symmetric determinantal representation of $f$
it suffices to compute the possible orthogonal matrices $V$. This method
computes the orthostochastic matrices which are the Hadamard squares of $V$,
via the algorithm in [1], and returns the associated determinantal
representation (using the method orthogonalFromOrthostochastic,
- see that method for more on the possible
orthogonal matrices returned).

For a generic hyperbolic polynomial of degree $d$ in 3 variables, the number of
definite determinantal representations is $2^g$, where $g = (d-1)(d-2)/2$ is
the genus of the plane curve.

For plane curves in special position, the option HyperbolicPt allows the user
to specify a point $e$ such that the polynomial is hyperbolic with respect to
$e$. In this case, a general coordinate change which brings $e$ to $(1,0,0)$ is
applied before computing the determinantal representation (which will then be
inverted before giving the result - note that the representation will no longer
be monic in general).

When working over an InexactFieldFamily (Macaulay2Doc),
like RR (Macaulay2Doc), or CC (Macaulay2Doc),
the option Tolerance can be used to specify the internal
threshold for checking equality (any floating point number below the tolerance
is treated as numerically zero).

+-----------------------------------------------------------------------------+
|i1 : R = RR[x1, x2, x3]                                                      |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : f = 6*x1^3+36*x1^2*x2+66*x1*x2^2+36*x2^3+11*x1^2*x3+42*x1*x2*x3+36*x2^2*|
|                                                                             |
|        3       2            2       3       2                      2        |
|o2 = 6x1  + 36x1 x2 + 66x1*x2  + 36x2  + 11x1 x3 + 42x1*x2*x3 + 36x2 x3 +    |
|     ------------------------------------------------------------------------|
|           2          2     3                                                |
|     6x1*x3  + 11x2*x3  + x3                                                 |
|                                                                             |
|o2 : R                                                                       |
|-----------------------------------------------------------------------------|
|x3+6*x1*x3^2+11*x2*x3^2+x3^3                                                 |
+-----------------------------------------------------------------------------+
|i3 : repList = detRep f                                                      |
|                                                                             |
|o3 = {| 1.81712x1+5.45136x2+1.36284x3 .489588x3                              |
|      | .489588x3                     1.81712x1+3.63424x2+1.21141x3          |
|      | .0462468x3                    .237183x3                              |
|     ------------------------------------------------------------------------|
|     .0462468x3                    |, | 1.81712x1+5.45136x2+1.36284x3        |
|     .237183x3                     |  | .438081x3                            |
|     1.81712x1+1.81712x2+.757134x3 |  | .312572x3                            |
|     ------------------------------------------------------------------------|
|     .438081x3                     .312572x3                     |}          |
|     1.81712x1+3.63424x2+1.21141x3 .0920576x3                    |           |
|     .0920576x3                    1.81712x1+1.81712x2+.757134x3 |           |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : all(repList, A -> clean(1e-10, f - det A) == 0)                         |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+
|i5 : g = product gens R -- hyperbolic with respect to (1,1,1)                |
|                                                                             |
|o5 = x1*x2*x3                                                                |
|                                                                             |
|o5 : R                                                                       |
+-----------------------------------------------------------------------------+
|i6 : B = clean(1e-6, first detRep(g, HyperbolicPt => matrix{{1_RR},{1},{1}}))|
|                                                                             |
|o6 = | .826721x1 0         0         |                                       |
|     | 0         .926078x2 0         |                                       |
|     | 0         0         1.30615x3 |                                       |
|                                                                             |
|             3       3                                                       |
|o6 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i7 : clean(1e-6, g - det B)                                                  |
|                                                                             |
|o7 = 0                                                                       |
|                                                                             |
|o7 : R                                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * detRep -- compute determinantal representations
  * bivariateDiagEntries -- computes diagonal
    entries and eigenvalues for a determinantal representation of a bivariate
    polynomial
  * orthogonalFromOrthostochastic, --
    computes orthogonal matrices for a given orthostochastic matrix
  * Determinantal representations of bivariate polynomials

Determinantal representations of quadrics
*****************************************

Synopsis
========

  * Usage:
        detRep f
        detRep(f, Tolerance => 1e-6)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a quadric with
        real coefficients
  * Outputs:
      * a matrix (Macaulay2Doc), giving a determinantal
        representation of $f$

This page demonstrates how the method detRep, computes a monic
symmetric determinantal representation of a real quadric $f$ (in any number of
variables), or returns false if no such representation exists.

If a quadratic determinantal representation of size $2$ exists, then it is
returned. Otherwise, the method will find a determinantal representation of
size $n+1$, where $n$ is the number of variables (if it exists). If no monic
symmetric determinantal representation exists, then null (Macaulay2Doc),
is returned.

When working over an InexactFieldFamily (Macaulay2Doc),
like RR (Macaulay2Doc), or CC (Macaulay2Doc),
the option Tolerance can be used to specify the internal
threshold for checking equality (any floating point number below the tolerance
is treated as numerically zero).

+-----------------------------------------------------------------------------+
|i1 : R = RR[x1, x2, x3, x4]                                                  |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : f = 260*x1^2+180*x1*x2-25*x2^2-140*x1*x3-170*x2*x3-121*x3^2+248*x1*x4+94|
|                                                                             |
|          2                  2                              2                |
|o2 = 260x1  + 180x1*x2 - 25x2  - 140x1*x3 - 170x2*x3 - 121x3  + 248x1*x4 +   |
|     ------------------------------------------------------------------------|
|                              2                                              |
|     94x2*x4 - 142x3*x4 + 35x4  + 36x1 + 18x2 + 2x3 + 20x4 + 1               |
|                                                                             |
|o2 : R                                                                       |
|-----------------------------------------------------------------------------|
|*x2*x4-142*x3*x4+35*x4^2+36*x1+18*x2+2*x3+20*x4+1                            |
+-----------------------------------------------------------------------------+
|i3 : A = first detRep f                                                      |
|                                                                             |
|o3 = | 17.8243x1+13.8011x2-.241342x3+5.84723x4+1                             |
|     | 7.99807x1+9.10764x2+10.9754x3+6.91046x4                               |
|     ------------------------------------------------------------------------|
|     7.99807x1+9.10764x2+10.9754x3+6.91046x4   |                             |
|     18.1757x1+4.19887x2+2.24134x3+14.1528x4+1 |                             |
|                                                                             |
|             2       2                                                       |
|o3 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i4 : clean(1e-10, f - det A)                                                 |
|                                                                             |
|o4 = 0                                                                       |
|                                                                             |
|o4 : R                                                                       |
+-----------------------------------------------------------------------------+
|i5 : g = -61*x1^2-96*x1*x2-177*x2^2-126*x1*x3-202*x2*x3-86*x3^2-94*x1*x4-190*|
|                                                                             |
|           2                  2                             2                |
|o5 = - 61x1  - 96x1*x2 - 177x2  - 126x1*x3 - 202x2*x3 - 86x3  - 94x1*x4 -    |
|     ------------------------------------------------------------------------|
|                               2                                             |
|     190x2*x4 - 140x3*x4 - 67x4  + 8x1 + 3x2 + 5x3 + 3x4 + 1                 |
|                                                                             |
|o5 : R                                                                       |
|-----------------------------------------------------------------------------|
|x2*x4-140*x3*x4-67*x4^2+8*x1+3*x2+5*x3+3*x4+1                                |
+-----------------------------------------------------------------------------+
|i6 : B = first detRep g                                                      |
|                                                                             |
|o6 = | 1                                       0                             |
|     | 0                                       1                             |
|     | 0                                       0                             |
|     | 0                                       0                             |
|     | 7.81025x1+6.14577x2+8.06632x3+6.01773x4 11.7996x2+4.35832x3+4.91683x4 |
|     ------------------------------------------------------------------------|
|     0                    0         7.81025x1+6.14577x2+8.06632x3+6.01773x4 ||
|     0                    0         11.7996x2+4.35832x3+4.91683x4           ||
|     1                    0         1.39265x3+.0214748x4                    ||
|     0                    1         2.57123x4                               ||
|     1.39265x3+.0214748x4 2.57123x4 8x1+3x2+5x3+3x4+1                       ||
|                                                                             |
|             5       5                                                       |
|o6 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i7 : clean(1e-10, g - det B)                                                 |
|                                                                             |
|o7 = 0                                                                       |
|                                                                             |
|o7 : R                                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * detRep -- compute determinantal representations

detRep -- compute determinantal representations
***********************************************

Synopsis
========

  * Usage:
        detRep f
        detRep(f, Tolerance => 1e-6)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a polynomial with
        real coefficients
  * Optional inputs (Macaulay2Doc),:
      * HyperbolicPt,
        => ..., default value null, null
      * Software,
        => ..., default value M2engine, null
      * Tolerance => ..., default value .000001
  * Outputs:
      * a list (Macaulay2Doc), of matrices, each giving a
        determinantal representation of $f$

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

This method is a wrapper function for the various methods implemented in this
package. Currently it accepts quadrics (in any number of variables), bivariate
polynomials or homogeneous trivariate polynomials, and cubic polynomials in 4
variables. By default, all polynomials are assumed to have real coefficients.
For any polynomial falling in one of these categories, the user may call this
method, and the correct algorithm will be automatically applied. For details on
each case, see the pages below.

See also
========

  * Determinantal representations of quadrics
  * Determinantal representations of bivariate polynomials
  * Determinantal representations of hyperbolic plane cubics

Ways to use detRep :
====================

  * "detRep(RingElement)"

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

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

generalizedMixedDiscriminant -- computes generalized mixed discriminant of a list of matrices
*********************************************************************************************

Synopsis
========

  * Usage:
        generalizedMixedDiscriminant L
  * Inputs:
      * L, a list (Macaulay2Doc), an $n$-tuple of $n\times n$
        matrices
  * Outputs:
      * a ring element (Macaulay2Doc), the generalized mixed
        discriminant of L

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

This method computes the generalized mixed discriminant of an $n$-tuple of
$n\times n$ matrices. The generalized mixed discriminants give formulas for the
coefficients of a determinantal polynomial, which are polynomial in the entries
of the representing matrices. Thus, computing determinantal representations can
be viewed as solving a system of specializations of generalized mixed
discriminants, i.e., recovering a set of matrices from its generalized mixed
discriminants.

+-----------------------------------------------------------------------------+
|i1 : n = 3                                                                   |
|                                                                             |
|o1 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i2 : R = QQ[a_(1,1)..a_(n,n),b_(1,1)..b_(n,n),c_(1,1)..c_(n,n)][x_1..x_n]    |
|                                                                             |
|o2 = R                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : A = sub(transpose genericMatrix(coefficientRing R,n,n), R)              |
|                                                                             |
|o3 = {0, -1} | a_(1,1) a_(1,2) a_(1,3) |                                     |
|     {0, -1} | a_(2,1) a_(2,2) a_(2,3) |                                     |
|     {0, -1} | a_(3,1) a_(3,2) a_(3,3) |                                     |
|                                                                             |
|             3       3                                                       |
|o3 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i4 : B = sub(transpose genericMatrix(coefficientRing R,b_(1,1),n,n), R)      |
|                                                                             |
|o4 = {0, -1} | b_(1,1) b_(1,2) b_(1,3) |                                     |
|     {0, -1} | b_(2,1) b_(2,2) b_(2,3) |                                     |
|     {0, -1} | b_(3,1) b_(3,2) b_(3,3) |                                     |
|                                                                             |
|             3       3                                                       |
|o4 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i5 : C = sub(transpose genericMatrix(coefficientRing R,c_(1,1),n,n), R)      |
|                                                                             |
|o5 = {0, -1} | c_(1,1) c_(1,2) c_(1,3) |                                     |
|     {0, -1} | c_(2,1) c_(2,2) c_(2,3) |                                     |
|     {0, -1} | c_(3,1) c_(3,2) c_(3,3) |                                     |
|                                                                             |
|             3       3                                                       |
|o5 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i6 : P = det(id_(R^n) + x_1*A + x_2*B + x_3*C);                              |
+-----------------------------------------------------------------------------+
|i7 : gmd = generalizedMixedDiscriminant({A,B,C})                             |
|                                                                             |
|o7 = a   b   c    - a   b   c    - a   b   c    + a   b   c    - a   b   c   |
|      3,3 2,2 1,1    3,2 2,3 1,1    2,3 3,2 1,1    2,2 3,3 1,1    3,3 2,1 1,2|
|     ------------------------------------------------------------------------|
|     + a   b   c    + a   b   c    - a   b   c    + a   b   c    -           |
|        3,1 2,3 1,2    2,3 3,1 1,2    2,1 3,3 1,2    3,2 2,1 1,3             |
|     ------------------------------------------------------------------------|
|     a   b   c    - a   b   c    + a   b   c    - a   b   c    + a   b   c   |
|      3,1 2,2 1,3    2,2 3,1 1,3    2,1 3,2 1,3    3,3 1,2 2,1    3,2 1,3 2,1|
|     ------------------------------------------------------------------------|
|     + a   b   c    - a   b   c    + a   b   c    - a   b   c    -           |
|        1,3 3,2 2,1    1,2 3,3 2,1    3,3 1,1 2,2    3,1 1,3 2,2             |
|     ------------------------------------------------------------------------|
|     a   b   c    + a   b   c    - a   b   c    + a   b   c    + a   b   c   |
|      1,3 3,1 2,2    1,1 3,3 2,2    3,2 1,1 2,3    3,1 1,2 2,3    1,2 3,1 2,3|
|     ------------------------------------------------------------------------|
|     - a   b   c    + a   b   c    - a   b   c    - a   b   c    +           |
|        1,1 3,2 2,3    2,3 1,2 3,1    2,2 1,3 3,1    1,3 2,2 3,1             |
|     ------------------------------------------------------------------------|
|     a   b   c    - a   b   c    + a   b   c    + a   b   c    - a   b   c   |
|      1,2 2,3 3,1    2,3 1,1 3,2    2,1 1,3 3,2    1,3 2,1 3,2    1,1 2,3 3,2|
|     ------------------------------------------------------------------------|
|     + a   b   c    - a   b   c    - a   b   c    + a   b   c                |
|        2,2 1,1 3,3    2,1 1,2 3,3    1,2 2,1 3,3    1,1 2,2 3,3             |
|                                                                             |
|o7 : R                                                                       |
+-----------------------------------------------------------------------------+
|i8 : coeff = (last coefficients(P, Monomials => {x_1*x_2*x_3}))_(0,0)        |
|                                                                             |
|o8 = a   b   c    - a   b   c    - a   b   c    + a   b   c    - a   b   c   |
|      3,3 2,2 1,1    3,2 2,3 1,1    2,3 3,2 1,1    2,2 3,3 1,1    3,3 2,1 1,2|
|     ------------------------------------------------------------------------|
|     + a   b   c    + a   b   c    - a   b   c    + a   b   c    -           |
|        3,1 2,3 1,2    2,3 3,1 1,2    2,1 3,3 1,2    3,2 2,1 1,3             |
|     ------------------------------------------------------------------------|
|     a   b   c    - a   b   c    + a   b   c    - a   b   c    + a   b   c   |
|      3,1 2,2 1,3    2,2 3,1 1,3    2,1 3,2 1,3    3,3 1,2 2,1    3,2 1,3 2,1|
|     ------------------------------------------------------------------------|
|     + a   b   c    - a   b   c    + a   b   c    - a   b   c    -           |
|        1,3 3,2 2,1    1,2 3,3 2,1    3,3 1,1 2,2    3,1 1,3 2,2             |
|     ------------------------------------------------------------------------|
|     a   b   c    + a   b   c    - a   b   c    + a   b   c    + a   b   c   |
|      1,3 3,1 2,2    1,1 3,3 2,2    3,2 1,1 2,3    3,1 1,2 2,3    1,2 3,1 2,3|
|     ------------------------------------------------------------------------|
|     - a   b   c    + a   b   c    - a   b   c    - a   b   c    +           |
|        1,1 3,2 2,3    2,3 1,2 3,1    2,2 1,3 3,1    1,3 2,2 3,1             |
|     ------------------------------------------------------------------------|
|     a   b   c    - a   b   c    + a   b   c    + a   b   c    - a   b   c   |
|      1,2 2,3 3,1    2,3 1,1 3,2    2,1 1,3 3,2    1,3 2,1 3,2    1,1 2,3 3,2|
|     ------------------------------------------------------------------------|
|     + a   b   c    - a   b   c    - a   b   c    + a   b   c                |
|        2,2 1,1 3,3    2,1 1,2 3,3    1,2 2,1 3,3    1,1 2,2 3,3             |
|                                                                             |
|o8 : R                                                                       |
+-----------------------------------------------------------------------------+
|i9 : gmd == coeff                                                            |
|                                                                             |
|o9 = true                                                                    |
+-----------------------------------------------------------------------------+

Ways to use generalizedMixedDiscriminant :
==========================================

  * "generalizedMixedDiscriminant(List)"

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

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

hadamard -- computes the Hadamard product of two matrices
*********************************************************

Synopsis
========

  * Usage:
        hadamard(A, B)
  * Inputs:
      * A, an $m\times n$ matrix
      * B, an $m\times n$ matrix
  * Outputs:
      * a matrix (Macaulay2Doc), the Hadamard product of $A$ and
        $B$

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

This method computes the Hadamard product of two matrices $A, B$ of the same
size. The Hadamard product is defined as the componentwise product, i.e., if
$A, B$ are $m\times n$ matrices, then the Hadamard product is the $m\times n$
matrix with $(i,j)$ entry equal to $A_{i,j}*B_{i,j}$.

+--------------------------------------------------------+
|i1 : (A1, A2) = (random(ZZ^2, ZZ^3), random(ZZ^2, ZZ^3))|
|                                                        |
|o1 = (| 8 3 8 |, | 3 8 5 |)                             |
|      | 1 7 3 |  | 7 8 7 |                              |
|                                                        |
|o1 : Sequence                                           |
+--------------------------------------------------------+
|i2 : hadamard(A1, A2)                                   |
|                                                        |
|o2 = | 24 24 40 |                                       |
|     | 7  56 21 |                                       |
|                                                        |
|              2        3                                |
|o2 : Matrix ZZ  <--- ZZ                                 |
+--------------------------------------------------------+

Ways to use hadamard :
======================

  * "hadamard(Matrix,Matrix)"

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

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

isDoublyStochastic -- whether a matrix is doubly stochastic
***********************************************************

Synopsis
========

  * Usage:
        isDoublyStochastic A
  * Inputs:
      * A, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Tolerance => ..., default value .000001
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether $A$ is a doubly
        stochastic matrix

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

This method determines whether a given matrix is doubly stochastic, i.e., is a
real square matrix with all entries nonnegative and all row and column sums
equal to $1$.

When working over an InexactFieldFamily (Macaulay2Doc),
like RR (Macaulay2Doc), or CC (Macaulay2Doc),
the option Tolerance can be used to specify the internal
threshold for checking equality (any floating point number below the tolerance
is treated as numerically zero).

+----------------------------------+
|i1 : O = randomOrthogonal 3       |
|                                  |
|o1 = | .54916   .312336 .775158  ||
|     | .413897  .704145 -.576947 ||
|     | -.726025 .637672 .257413  ||
|                                  |
|                3          3      |
|o1 : Matrix RR    <--- RR         |
|              53         53       |
+----------------------------------+
|i2 : A = hadamard(O, O)           |
|                                  |
|o2 = | .301576 .0975537 .60087   ||
|     | .171311 .495821  .332868  ||
|     | .527113 .406625  .0662616 ||
|                                  |
|                3          3      |
|o2 : Matrix RR    <--- RR         |
|              53         53       |
+----------------------------------+
|i3 : isDoublyStochastic A         |
|                                  |
|o3 = true                         |
+----------------------------------+

Ways to use isDoublyStochastic :
================================

  * "isDoublyStochastic(Matrix)"

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

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

isOrthogonal -- whether a matrix is orthogonal
**********************************************

Synopsis
========

  * Usage:
        isOrthogonal A
  * Inputs:
      * A, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Tolerance => ..., default value .000001
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether $A$ is
        orthogonal

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

This method determines whether a given matrix is orthogonal, i.e., has inverse
equal to its transpose.

When working over an InexactFieldFamily (Macaulay2Doc),
like RR (Macaulay2Doc), or CC (Macaulay2Doc),
the option Tolerance can be used to specify the internal
threshold for checking equality (any floating point number below the tolerance
is treated as numerically zero). If the given matrix does not have floating
point entries, then this option is not used.

+-----------------------------------------------------------------------------+
|i1 : O1 = randomOrthogonal 5                                                 |
|                                                                             |
|o1 = | .442386  -.0306554 .751799   -.317548 .370563  |                      |
|     | .133864  .768167   -.0944111 -.513838 -.345046 |                      |
|     | -.60855  -.385718  .234815   -.587034 -.284854 |                      |
|     | -.42001  .39448    .591227   .519553  -.220209 |                      |
|     | -.489525 .323399   -.145593  -.143489 .783576  |                      |
|                                                                             |
|                5          5                                                 |
|o1 : Matrix RR    <--- RR                                                    |
|              53         53                                                  |
+-----------------------------------------------------------------------------+
|i2 : isOrthogonal O1                                                         |
|                                                                             |
|o2 = true                                                                    |
+-----------------------------------------------------------------------------+
|i3 : O2 = randomOrthogonal(5, QQ)                                            |
|                                                                             |
|o3 = | -22142569999/27593776175 90555408/788393605   -5532008344/27593776175 |
|     | 193172688/788393605      145827307/157678721  24042978/788393605      |
|     | 591854008/5518755235     -5780466/157678721   -5151709442/5518755235  |
|     | -598559432/27593776175   -200993706/788393605 7495643483/27593776175  |
|     | -84039992/157678721      40244400/157678721   18443792/157678721      |
|     ------------------------------------------------------------------------|
|     -5025793592/27593776175  2046480376/3941968025 |                        |
|     -216954846/788393605     70436016/788393605    |                        |
|     -1194249041/5518755235   -206975072/788393605  |                        |
|     -25053509506/27593776175 -751964432/3941968025 |                        |
|     22251808/157678721       -123874657/157678721  |                        |
|                                                                             |
|              5        5                                                     |
|o3 : Matrix QQ  <--- QQ                                                      |
+-----------------------------------------------------------------------------+
|i4 : isOrthogonal O2                                                         |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * randomOrthogonal -- constructs a random special
    orthogonal matrix

Ways to use isOrthogonal :
==========================

  * "isOrthogonal(Matrix)"

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

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

orthogonalFromOrthostochastic -- computes orthogonal matrices for a given orthostochastic matrix
************************************************************************************************

Synopsis
========

  * Usage:
        orthogonalFromOrthostochastic A
        orthogonalFromOrthostochastic(A, Tolerance => 1e-6)
  * Inputs:
      * A, a matrix (Macaulay2Doc), an orthostochastic matrix
  * Optional inputs (Macaulay2Doc),:
      * Tolerance => ..., default value .000001
  * Outputs:
      * a list (Macaulay2Doc), of orthogonal matrices whose
        Hadamard square is $A$

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

This method computes orthogonal matrices whose Hadamard square is a given
orthostochastic matrix. This is a helper function to detRep,
which computes symmetric determinantal representations of real cubic bivariate
polynomials.

Given a $n\times n$ orthostochastic matrix $A$, there are $2^{n^2}$ possible
matrices whose Hadamard square is $A$ (not all of which will be orthogonal in
general though). Let $G\cong (\ZZ/2\ZZ)^n$ be the group of diagonal matrices
with diagonal entries equal to &plusmn;1. Then $G \times G$ acts (by $(g_1,
g_2) O = g_1Og_2$) on the set of orthogonal matrices whose Hadamard square is
$A$. This method computes all such orthogonal matrices, modulo the action of
$G\times G$. The representative for each orbit is chosen so that the first row
and column will have all nonnegative entries, and modulo this restriction on
the signs, the algorithm is essentially a brute-force search. Note that for
generic choices of the orthostochastic matrix $A$, there will be exactly one
$G\times G$-orbit of orthogonal matrices with Hadamard square equal to $A$.

When working over an InexactFieldFamily (Macaulay2Doc),
like RR (Macaulay2Doc), or CC (Macaulay2Doc),
the option Tolerance can be used to specify the internal
threshold for checking equality (any floating point number below the tolerance
is treated as numerically zero).

+-------------------------------------------------+
|i1 : O = randomOrthogonal 4                      |
|                                                 |
|o1 = | .277276   -.291644 .290194     -.868245 | |
|     | .939685   .270779  -.000487755 .208973  | |
|     | -.0964589 .153934  .954496     .236511  | |
|     | .175514   -.904393 .0687354    .38281   | |
|                                                 |
|                4          4                     |
|o1 : Matrix RR    <--- RR                        |
|              53         53                      |
+-------------------------------------------------+
|i2 : A = hadamard(O, O)                          |
|                                                 |
|o2 = | .076882   .085056  .0842128   .753849  |  |
|     | .883009   .0733215 2.37905e-7 .0436696 |  |
|     | .00930432 .0236956 .911062    .0559377 |  |
|     | .0308051  .817927  .00472455  .146543  |  |
|                                                 |
|                4          4                     |
|o2 : Matrix RR    <--- RR                        |
|              53         53                      |
+-------------------------------------------------+
|i3 : orthogonalFromOrthostochastic A             |
|                                                 |
|o3 = {| .277276  .291644  .290194     .868245  |}|
|      | .939685  -.270779 -.000487755 -.208973 | |
|      | .0964589 .153934  -.954496    .236511  | |
|      | .175514  .904393  .0687354    -.38281  | |
|                                                 |
|o3 : List                                        |
+-------------------------------------------------+

See also
========

  * detRep -- compute determinantal representations

Ways to use orthogonalFromOrthostochastic :
===========================================

  * "orthogonalFromOrthostochastic(Matrix)"

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

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

randomIntegerSymmetric -- constructs a random integer symmetric matrix
**********************************************************************

Synopsis
========

  * Usage:
        randomIntegerSymmetric n
        randomIntegerSymmetric(n, R)
  * Inputs:
      * n, an integer (Macaulay2Doc),
      * R, a ring (Macaulay2Doc), or RR (Macaulay2Doc), or
        CC (Macaulay2Doc), (of type InexactFieldFamily (Macaulay2Doc))
  * Outputs:
      * a matrix (Macaulay2Doc), a random $n\times n$ symmetric
        matrix with integer entries, over the ring $R$

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

This method returns a random symmetric matrix of a given size $n$ with integer
entries. This can in turn be specialized to any ring, which may be provided as
an argument.

+--------------------------------------------------------------------+
|i1 : randomIntegerSymmetric 5                                       |
|                                                                    |
|o1 = | 16 4  8  10 14 |                                             |
|     | 4  6  14 14 17 |                                             |
|     | 8  14 16 8  5  |                                             |
|     | 10 14 8  12 15 |                                             |
|     | 14 17 5  15 12 |                                             |
|                                                                    |
|              5        5                                            |
|o1 : Matrix ZZ  <--- ZZ                                             |
+--------------------------------------------------------------------+
|i2 : randomIntegerSymmetric 20                                      |
|                                                                    |
|o2 = | 18 9  3  10 9  5  13 14 8  10 10 10 11 7  11 16 8  8  6  13 ||
|     | 9  2  16 14 4  3  12 6  11 6  10 9  6  10 17 7  11 11 6  14 ||
|     | 3  16 4  6  7  15 5  10 14 13 5  9  2  4  13 10 8  6  10 5  ||
|     | 10 14 6  18 16 11 7  13 15 11 10 16 18 1  13 10 5  10 14 10 ||
|     | 9  4  7  16 6  8  15 5  9  7  14 13 10 13 12 6  16 12 9  9  ||
|     | 5  3  15 11 8  16 3  5  15 10 8  13 10 7  9  1  16 10 9  7  ||
|     | 13 12 5  7  15 3  4  13 9  11 18 10 4  4  8  15 9  8  10 14 ||
|     | 14 6  10 13 5  5  13 4  16 14 4  14 15 7  4  17 9  7  8  5  ||
|     | 8  11 14 15 9  15 9  16 0  8  10 6  5  11 3  12 2  14 15 7  ||
|     | 10 6  13 11 7  10 11 14 8  16 12 6  6  6  9  10 11 9  9  12 ||
|     | 10 10 5  10 14 8  18 4  10 12 18 9  6  8  5  9  3  9  12 11 ||
|     | 10 9  9  16 13 13 10 14 6  6  9  8  14 6  12 6  6  4  8  11 ||
|     | 11 6  2  18 10 10 4  15 5  6  6  14 16 12 2  13 5  7  4  5  ||
|     | 7  10 4  1  13 7  4  7  11 6  8  6  12 4  9  10 10 12 12 4  ||
|     | 11 17 13 13 12 9  8  4  3  9  5  12 2  9  4  4  3  11 8  11 ||
|     | 16 7  10 10 6  1  15 17 12 10 9  6  13 10 4  4  3  15 13 7  ||
|     | 8  11 8  5  16 16 9  9  2  11 3  6  5  10 3  3  0  10 14 10 ||
|     | 8  11 6  10 12 10 8  7  14 9  9  4  7  12 11 15 10 18 7  14 ||
|     | 6  6  10 14 9  9  10 8  15 9  12 8  4  12 8  13 14 7  10 11 ||
|     | 13 14 5  10 9  7  14 5  7  12 11 11 5  4  11 7  10 14 11 4  ||
|                                                                    |
|              20        20                                          |
|o2 : Matrix ZZ   <--- ZZ                                            |
+--------------------------------------------------------------------+
|i3 : R = RR[x,y]                                                    |
|                                                                    |
|o3 = R                                                              |
|                                                                    |
|o3 : PolynomialRing                                                 |
+--------------------------------------------------------------------+
|i4 : randomIntegerSymmetric(3, R)                                   |
|                                                                    |
|o4 = | 14 13 6  |                                                   |
|     | 13 0  13 |                                                   |
|     | 6  13 2  |                                                   |
|                                                                    |
|             3       3                                              |
|o4 : Matrix R  <--- R                                               |
+--------------------------------------------------------------------+

Caveat
======

The entries of the constructed matrix will be integers between 0 and 18,
inclusive.

See also
========

  * genericSymmetricMatrix (Macaulay2Doc) -- make
    a generic symmetric matrix

Ways to use randomIntegerSymmetric :
====================================

  * "randomIntegerSymmetric(ZZ)"
  * "randomIntegerSymmetric(ZZ,Ring)"

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

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

randomOrthogonal -- constructs a random special orthogonal matrix
*****************************************************************

Synopsis
========

  * Usage:
        randomOrthogonal n
        randomOrthogonal(n, R)
  * Inputs:
      * n, an integer (Macaulay2Doc),
      * R, a ring (Macaulay2Doc), or RR (Macaulay2Doc), or
        CC (Macaulay2Doc), (of type InexactFieldFamily (Macaulay2Doc))
  * Outputs:
      * a matrix (Macaulay2Doc), a random $n\times n$ special
        orthogonal matrix, over the ring $R$

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

This method returns a random orthogonal matrix of a given size $n$. The
orthogonal matrix is constructed via Cayley's correspondence, which gives a
bijection between skew-symmetric matrices, and orthogonal matrices $O$ which do
not have $1$ as an eigenvalue (i.e., $O - I$ is invertible). Up to changing
signs of rows, any orthogonal matrix can be obtained this way: if $G\cong
(\ZZ/2\ZZ)^n$ is the group of diagonal matrices with diagonal entries equal to
&plusmn;1, acting on $n\times n$ matrices by left multiplication, then (as one
may check) every $G$-orbit contains a matrix that does not have $1$ as an
eigenvalue (if the characteristic is not 2).

Note that the matrices which feature in the Cayley correspondence have
determinant $(-1)^n$, so this method scales by $-1$ to return a special
orthogonal matrix. Thus the matrices returned by this method do not have $-1$
as an eigenvalue.

By default a matrix over RR (Macaulay2Doc), is returned. This method
also accepts a ring as an (optional) argument, in which case a special
orthogonal matrix over the ring is returned, with entries in the base coefficient ring (Macaulay2Doc).

+-----------------------------------------------------------------------------+
|i1 : O1 = randomOrthogonal 5                                                 |
|                                                                             |
|o1 = | .442386  -.0306554 .751799   -.317548 .370563  |                      |
|     | .133864  .768167   -.0944111 -.513838 -.345046 |                      |
|     | -.60855  -.385718  .234815   -.587034 -.284854 |                      |
|     | -.42001  .39448    .591227   .519553  -.220209 |                      |
|     | -.489525 .323399   -.145593  -.143489 .783576  |                      |
|                                                                             |
|                5          5                                                 |
|o1 : Matrix RR    <--- RR                                                    |
|              53         53                                                  |
+-----------------------------------------------------------------------------+
|i2 : isOrthogonal O1                                                         |
|                                                                             |
|o2 = true                                                                    |
+-----------------------------------------------------------------------------+
|i3 : eigenvalues O1                                                          |
|                                                                             |
|o3 = {.070857+.997486*ii}                                                    |
|     {.070857-.997486*ii}                                                    |
|     {.803392+.595451*ii}                                                    |
|     {.803392-.595451*ii}                                                    |
|     {1                 }                                                    |
|                                                                             |
|o3 : VerticalList                                                            |
+-----------------------------------------------------------------------------+
|i4 : det O1                                                                  |
|                                                                             |
|o4 = 1                                                                       |
|                                                                             |
|o4 : RR (of precision 53)                                                    |
+-----------------------------------------------------------------------------+
|i5 : R = QQ[x,y]                                                             |
|                                                                             |
|o5 = R                                                                       |
|                                                                             |
|o5 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i6 : O2 = randomOrthogonal(5, R)                                             |
|                                                                             |
|o6 = | -22142569999/27593776175 90555408/788393605   -5532008344/27593776175 |
|     | 193172688/788393605      145827307/157678721  24042978/788393605      |
|     | 591854008/5518755235     -5780466/157678721   -5151709442/5518755235  |
|     | -598559432/27593776175   -200993706/788393605 7495643483/27593776175  |
|     | -84039992/157678721      40244400/157678721   18443792/157678721      |
|     ------------------------------------------------------------------------|
|     -5025793592/27593776175  2046480376/3941968025 |                        |
|     -216954846/788393605     70436016/788393605    |                        |
|     -1194249041/5518755235   -206975072/788393605  |                        |
|     -25053509506/27593776175 -751964432/3941968025 |                        |
|     22251808/157678721       -123874657/157678721  |                        |
|                                                                             |
|             5       5                                                       |
|o6 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i7 : isOrthogonal O2                                                         |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+
|i8 : det(O2), det(O2+id_(R^5))                                               |
|                                                                             |
|          5225472                                                            |
|o8 = (1, ---------)                                                          |
|         157678721                                                           |
|                                                                             |
|o8 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * isOrthogonal -- whether a matrix is orthogonal

Ways to use randomOrthogonal :
==============================

  * "randomOrthogonal(ZZ)"
  * "randomOrthogonal(ZZ,Thing)"

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

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

randomPSD -- constructs a random positive semidefinite matrix
*************************************************************

Synopsis
========

  * Usage:
        randomPSD n
        randomPSD(n, r)
        randomPSD(n, s)
        randomPSD(n, r, s)
  * Inputs:
      * n, an integer (Macaulay2Doc), the size of the output matrix
      * r, an integer (Macaulay2Doc), the desired rank
      * s, a real number (Macaulay2Doc), an upper bound on the
        spectral radius (= largest eigenvalue)
  * Outputs:
      * a matrix (Macaulay2Doc), a random $n\times n$ positive
        semidefinite matrix with real entries, of rank $r$, with eigenvalues
        between $0$ and $s$.

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

This method returns a random symmetric positive semidefinite real matrix of a
given size $n$. The rank $r$ can also be specified: by default, the matrix will
be full rank (with probability 1). An upper bound $s$ on the spectral radius
can also be specified: by default, the matrix will have spectral radius $<= 1$.

+-----------------------------------------------------------------------------+
|i1 : randomPSD 5                                                             |
|                                                                             |
|o1 = | .585298   -.0545901 .0184505  -.0599728  -.149145   |                 |
|     | -.0545901 .761001   -.0118983 -.160458   -.02979    |                 |
|     | .0184505  -.0118983 .56512    .0605255   -.0250409  |                 |
|     | -.0599728 -.160458  .0605255  .609506    -.00367036 |                 |
|     | -.149145  -.02979   -.0250409 -.00367036 .761799    |                 |
|                                                                             |
|                5          5                                                 |
|o1 : Matrix RR    <--- RR                                                    |
|              53         53                                                  |
+-----------------------------------------------------------------------------+
|i2 : A1 = randomPSD(5, 3)                                                    |
|                                                                             |
|o2 = | .0822059   .117626   -.109793  -.00518272 -.0292519 |                 |
|     | .117626    .168797   -.149976  -.0126384  -.0536067 |                 |
|     | -.109793   -.149976  .295902   -.204962   -.0805114 |                 |
|     | -.00518272 -.0126384 -.204962  .460442    -.0253618 |                 |
|     | -.0292519  -.0536067 -.0805114 -.0253618  .349651   |                 |
|                                                                             |
|                5          5                                                 |
|o2 : Matrix RR    <--- RR                                                    |
|              53         53                                                  |
+-----------------------------------------------------------------------------+
|i3 : A2 = randomPSD(5, 3.0)                                                  |
|                                                                             |
|o3 = | .466141  -.549293  .0814037 .326059  -.171432  |                      |
|     | -.549293 2.32094   -.225548 -.826411 -.0874656 |                      |
|     | .0814037 -.225548  .538414  .404872  .190896   |                      |
|     | .326059  -.826411  .404872  .890458  .0658219  |                      |
|     | -.171432 -.0874656 .190896  .0658219 .577543   |                      |
|                                                                             |
|                5          5                                                 |
|o3 : Matrix RR    <--- RR                                                    |
|              53         53                                                  |
+-----------------------------------------------------------------------------+
|i4 : (A1, A2)/eigenvectors -- note the difference!                           |
|                                                                             |
|o4 = (({.626892     }, | .162261  -.415623 .116326  -.582187 .446921 |),     |
|       {.350611     }  | .218178  -.595049 .197553  .726969  .399931 |       |
|       {.379495     }  | -.620177 .364839  .146256  .297715  .673447 |       |
|       {1.83307e-18 }  | .733874  .580879  .109056  .153773  .331088 |       |
|       {-1.37383e-17}  | .05366   -.051451 -.956116 .142456  .277789 |       |
|     ------------------------------------------------------------------------|
|     ({2.93272}, | .248943  -.183226 .443654  .667494  -.511935  |))         |
|      {.851128}  | -.856474 .297886  .368634  .197344  .0536749  |           |
|      {.637309}  | .163236  .62407   .206671  -.464468 -.57048   |           |
|      {.178755}  | .419929  .422352  .467183  .138583  .638603   |           |
|      {.193582}  | .0386539 .556639  -.637422 .52969   -.0421905 |           |
|                                                                             |
|o4 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i5 : A3 = randomPSD(5, 3, 7.0)                                               |
|                                                                             |
|o5 = | 1.20614   -.134804    -.0319069   -.60937  .0177087  |                |
|     | -.134804  .16531      -.000970882 .12522   -.0189459 |                |
|     | -.0319069 -.000970882 .0606769    -.175278 .226441   |                |
|     | -.60937   .12522      -.175278    .932231  -.734734  |                |
|     | .0177087  -.0189459   .226441     -.734734 .86079    |                |
|                                                                             |
|                5          5                                                 |
|o5 : Matrix RR    <--- RR                                                    |
|              53         53                                                  |
+-----------------------------------------------------------------------------+
|i6 : eigenvectors(A3, Hermitian => true)                                     |
|                                                                             |
|o6 = ({-1.5684e-16 }, | -.319106 -.102372 .179599  -.74438  .548938   |)     |
|      {-2.01019e-17}  | .187985  .079509  .97172   .0750933 -.0919877 |      |
|      {.150772     }  | -.502203 .837319  .0245115 .185606  .107882   |      |
|      {1.08742     }  | -.659104 -.277223 .0981496 -.153387 -.674958  |      |
|      {1.98696     }  | -.41977  -.453037 .115199  .618289  .472227   |      |
|                                                                             |
|o6 : Sequence                                                                |
+-----------------------------------------------------------------------------+

Caveat
======

This method works by choosing the eigenvectors and eigenvalues independently
randomly. The distribution on the (compact) set of PSD matrices of bounded
spectral radius may not be uniform or statistically desirable (cf. Wishart
distribution).

See also
========

  * cholesky -- computes the Cholesky decomposition of a
    positive semidefinite matrix

Ways to use randomPSD :
=======================

  * "randomPSD(ZZ)"
  * "randomPSD(ZZ,RR)"
  * "randomPSD(ZZ,ZZ)"
  * "randomPSD(ZZ,ZZ,RR)"

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

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

randomUnipotent -- constructs a random unipotent matrix
*******************************************************

Synopsis
========

  * Usage:
        randomUnipotent n
        randomUnipotent(n, R)
  * Inputs:
      * n, an integer (Macaulay2Doc),
      * R, a ring (Macaulay2Doc), or RR (Macaulay2Doc), or
        CC (Macaulay2Doc), (of type InexactFieldFamily (Macaulay2Doc))
  * Outputs:
      * a matrix (Macaulay2Doc), a random $n\times n$ unipotent
        matrix, over the ring $R$

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

This method returns a random unipotent matrix of a given size $n$, which is
upper triangular with all diagonal entries equal to $1$. if a ring $R$ is
provided, then the output is a matrix over $R$ - by default, the output is a
matrix over QQ (Macaulay2Doc).

+----------------------------------------------+
|i1 : randomUnipotent 5                        |
|                                              |
|o1 = | 1 9/2 1/2 9/4 1/2 |                    |
|     | 0 1   1   3/4 3/2 |                    |
|     | 0 0   1   3/4 7/4 |                    |
|     | 0 0   0   1   7/9 |                    |
|     | 0 0   0   0   1   |                    |
|                                              |
|              5        5                      |
|o1 : Matrix QQ  <--- QQ                       |
+----------------------------------------------+
|i2 : randomUnipotent(3, CC)                   |
|                                              |
|o2 = | 1 .706096+.127435ii .254482+.741046ii ||
|     | 0 1                 .108386+.348931ii ||
|     | 0 0                 1                 ||
|                                              |
|                3          3                  |
|o2 : Matrix CC    <--- CC                     |
|              53         53                   |
+----------------------------------------------+
|i3 : randomUnipotent(3, RR[x,y])              |
|                                              |
|o3 = | 1 .562428 .246268 |                    |
|     | 0 1       .153346 |                    |
|     | 0 0       1       |                    |
|                                              |
|                        3                  3  |
|o3 : Matrix (RR  [x..y])  <--- (RR  [x..y])   |
|               53                 53          |
+----------------------------------------------+

Ways to use randomUnipotent :
=============================

  * "randomUnipotent(ZZ)"
  * "randomUnipotent(ZZ,Thing)"

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

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

realPartMatrix -- real part of a matrix over CC
***********************************************

Synopsis
========

  * Usage:
        realPartMatrix A
  * Inputs:
      * A, a matrix (Macaulay2Doc), with complex entries
  * Outputs:
      * a matrix (Macaulay2Doc), the real matrix whose entries
        are real parts of entries of A

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

Given a complex matrix, this method returns a real matrix obtained by taking
the real part of each entry. It leaves matrices over RR (Macaulay2Doc),
and QQ (Macaulay2Doc), unchanged.

+--------------------------------------------------+
|i1 : A = random(RR^3,RR^5)                        |
|                                                  |
|o1 = | .892712 .632944  .89189  .775187 .0741835 ||
|     | .673395 .0258884 .231053 .909047 .808694  ||
|     | .29398  .714827  .461944 .314897 .362835  ||
|                                                  |
|                3          5                      |
|o1 : Matrix RR    <--- RR                         |
|              53         53                       |
+--------------------------------------------------+
|i2 : A == realPartMatrix A                        |
|                                                  |
|o2 = true                                         |
+--------------------------------------------------+
|i3 : B = sub(A, CC)                               |
|                                                  |
|o3 = | .892712 .632944  .89189  .775187 .0741835 ||
|     | .673395 .0258884 .231053 .909047 .808694  ||
|     | .29398  .714827  .461944 .314897 .362835  ||
|                                                  |
|                3          5                      |
|o3 : Matrix CC    <--- CC                         |
|              53         53                       |
+--------------------------------------------------+
|i4 : C = realPartMatrix B                         |
|                                                  |
|o4 = | .892712 .632944  .89189  .775187 .0741835 ||
|     | .673395 .0258884 .231053 .909047 .808694  ||
|     | .29398  .714827  .461944 .314897 .362835  ||
|                                                  |
|                3          5                      |
|o4 : Matrix RR    <--- RR                         |
|              53         53                       |
+--------------------------------------------------+
|i5 : clean(1e-10, A - C) == 0                     |
|                                                  |
|o5 = true                                         |
+--------------------------------------------------+
|i6 : D = random(QQ^3, QQ^1)                       |
|                                                  |
|o6 = | 7/10 |                                     |
|     | 1/2  |                                     |
|     | 7/10 |                                     |
|                                                  |
|              3        1                          |
|o6 : Matrix QQ  <--- QQ                           |
+--------------------------------------------------+
|i7 : D == realPartMatrix D                        |
|                                                  |
|o7 = true                                         |
+--------------------------------------------------+

If the matrix is over a polynomial ring, but has entries defined over the base
field (e.g., when taking coefficients (Macaulay2Doc)), then
it is necessary to substitute (Macaulay2Doc), into the base
field first:

+-----------------------------------------------------------------------------+
|i8 : R = CC[x,y]                                                             |
|                                                                             |
|o8 = R                                                                       |
|                                                                             |
|o8 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i9 : f = random(2,R)                                                         |
|-- warning: experimental computation over inexact field begun                |
|--          results not reliable (one warning given per session)             |
|                                                                             |
|                             2                                               |
|o9 = (.0410167 + .951912*ii)x  + (.752574 + .424521*ii)x*y + (.641878 +      |
|     ------------------------------------------------------------------------|
|                 2                                                           |
|     .267055*ii)y                                                            |
|                                                                             |
|o9 : R                                                                       |
+-----------------------------------------------------------------------------+
|i10 : C = last coefficients f                                                |
|                                                                             |
|o10 = {2} | .0410167+.951912ii |                                             |
|      {2} | .752574+.424521ii  |                                             |
|      {2} | .641878+.267055ii  |                                             |
|                                                                             |
|              3       1                                                      |
|o10 : Matrix R  <--- R                                                       |
+-----------------------------------------------------------------------------+
|i11 : realPartMatrix sub(C, coefficientRing R)                               |
|                                                                             |
|o11 = | .0410167 |                                                           |
|      | .752574  |                                                           |
|      | .641878  |                                                           |
|                                                                             |
|                 3          1                                                |
|o11 : Matrix RR    <--- RR                                                   |
|               53         53                                                 |
+-----------------------------------------------------------------------------+

See also
========

  * roundMatrix -- lifts matrix over RR to matrix over QQ

Ways to use realPartMatrix :
============================

  * "realPartMatrix(Matrix)"

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

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

roundMatrix -- lifts matrix over RR to matrix over QQ
*****************************************************

Synopsis
========

  * Usage:
        roundMatrix(n, A)
  * Inputs:
      * A, a matrix (Macaulay2Doc), with real entries
      * n, an integer (Macaulay2Doc), a threshold for rounding digits
  * Outputs:
      * a matrix (Macaulay2Doc), a matrix over QQ, obtained by
        rounding entries of A

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

This method converts a real matrix to a rational matrix, by rounding each
entry. The input $n$ specifies the number of (decimal) digits used for
rounding.

+-------------------------------------------------------+
|i1 : A = matrix{{1, 2.5, -13/17}, {2*pi, 4.7, sqrt(2)}}|
|                                                       |
|o1 = | 1       2.5 -.764706 |                          |
|     | 6.28319 4.7 1.41421  |                          |
|                                                       |
|                2          3                           |
|o1 : Matrix RR    <--- RR                              |
|              53         53                            |
+-------------------------------------------------------+
|i2 : roundMatrix(5, A)                                 |
|                                                       |
|o2 = | 1             5/2   -76471/100000 |             |
|     | 628319/100000 47/10 141421/100000 |             |
|                                                       |
|              2        3                               |
|o2 : Matrix QQ  <--- QQ                                |
+-------------------------------------------------------+

See also
========

  * realPartMatrix -- real part of a matrix over CC

Ways to use roundMatrix :
=========================

  * "roundMatrix(ZZ,Matrix)"

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

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