This is a demo file for 
NCConvexityRegion[p,{x,y}].

\(\(\(
\)\(
\)\(\(Get["C:\NC\SetNCDir.m"];\)

    \(Get["NCAlgebra.m"\ ];\)\)\)\)

w =  y ** inv[1  - x ** y]

DirD[w, y, h]

h ** inv[1 - x ** y] + [y ** inv[1 - x ** y] ** x ** h ** 
          inv[1 - x ** y]

NCHessian[w, {y, h}]
NCMatrixOfQuadratic[%14, {h}]

(1) Let's start with a simple example first.  Lets test the convexity of p = x^2.

NCConvexityRegion[ x ** x,  {x} ]

Conclusions: We see that x^2 is matrix convex for all symmetric x, since the output diagonal elements {2} are positive.

(2) Now we will test the convexity of p = x^3.

NCConvexityRegion[ x ** x ** x,  {x} ]

Conclusions: We see that x^3 is not matrix convex for any symmetric x, since the output diagonal elements {2x, -2 inv[x]} cannot both be positive.

(3) What about p = x^2+y^2 ?

NCConvexityRegion[ x ** x + y ** y,  {x, y} ]

Conclusions: We see that x^2+y^2 is matrix convex for any symmetric x and y, since the output diagonal elements {2,2} are positive.

(4) What about p = x^4 ?

NCConvexityRegion[ x ** x ** x ** x,  {x} ]

Conclusions: We see that x^4 is not matrix convex for any symmetric x, since the eigenvalues of the D matrix include 2 and -2.  Note the different message and output here.  This is because D was not diagonal, but block diagonal. So, NCConvexityRegion gave back the diagonal, subdiagonal, and -subdiagonal.

(5) What about p = x^4+y^4 ?

NCConvexityRegion[ 
      x ** x ** x ** x + y ** y ** y ** y,  {x, y} ]

Conclusions: We see that x^4+y^4 is not matrix convex for any symmetric x and y, since the eigenvalues of the D matrix include 2 and -2.  Note again the different message and output here.  This is because D was not diagonal, but block diagonal.  So, NCConvexityRegion gave back the diagonal, subdiagonal, and -subdiagonal.

What is NCConvexityRegion doing?

Let's step through a couple of the above examples and do what NCConvexityRegion does to get a feeling for what is happening.

(6) Let's go through p = x^3.

hes  =  
      NCHessian[ x ** x ** x ** x,  {x, h}]
{lt, mq, rt} =  
      NCMatrixOfQuadratic[hes, {h}]
MatrixForm[mq]
{lf, d, rt, junk} = 
        NCLDUDecomposition[mq];
MatrixForm[d]

Conclusions: NCConvexityRegion returns the diagonal of d.  Look at example (2).

(7) Let's go through p = x^4.

hes  =  
      NCHessian[ x ** x ** x ** x,  {x, h}]
{lt, mq, rt} =  
      NCMatrixOfQuadratic[hes, {h}]
MatrixForm[mq]
{lf, d, rt, junk} = 
        NCLDUDecomposition[mq];
MatrixForm[d]

Conclusions: NCConvexityRegion returns the diagonal,offdiagonal, and -offdiagonal of d.  Note that this answer is consistent with example (4) above.

What kind of options can we use?

We can run NCConvexityRegion with AllPermutation -> True.  The default is false.  This will make NCConvexityRegion run NCAllPermutationLDU instead of NCLDUDecomposition.   When you do this you also want to set DiagonalSelection to the permutations you want to use.  The possible settings for DiagonalSelection are {n} or {k,n}.  {n} makes NCAllPermutationLDU use permutations 1 through n, while {k,n} makes NCAllPermutationLDU use permutations k through n.   Note that setting AllPermutation to True and selecting different permutations will give different answers.  But, they will all be consistent with regards to the matrix convexity of p.  When AllPermutation is set to true NCConvexityRegion only returns the shortest answer.  So although there are multiple answers depending on what permutations are selected, NCConvexityRegion looks through them and selects the shortest one to return.

(8) Lets run x^3.

hes  =  
        NCHessian[ x ** x ** x,  {x, h} ];
{lt, mq, rt} =  
        NCMatrixOfQuadratic[ hes, {h} ];
MatrixForm[mq]

We have a 2x2 matrix.  So the number of permutations is only 2.

NCConvexityRegion[ x ** x ** x,  {x}, AllPermutation -> True, 
      DiagonalSelection -> {1} ]

NCConvexityRegion[ x ** x ** x,  {x}, AllPermutation -> True, 
      DiagonalSelection -> {2, 2} ]

Conclusions: In this case we get the same answer even though we used different permutations.

(9) Lets run x^4.

hes  =  
        NCHessian[ 
          x ** x ** x ** x,  {x, h} ];
{lt, mq, rt} =  
        NCMatrixOfQuadratic[ hes, {h} ];
MatrixForm[mq]

We have a 3x3 matrix.  So the number of permutations is only 12.

NCConvexityRegion[ x ** x ** x ** x,  {x}, 
      AllPermutation -> True, 
      DiagonalSelection -> {1, 2} ]

NCConvexityRegion[ x ** x ** x ** x,  {x}, 
      AllPermutation -> True, 
      DiagonalSelection -> {1, 12} ]

Conclusions: When we tried using permutations 1 through 2 we got a different answer than when we used all the permutations.  But the answers in terms of convexity are the same.  x^4 is not matrix convex.

M 247A

f =  
      z   +  (y  - x)  **  
          inv[z  -  y  ** inv[x] ** y ]  ** (y - x)

NCConvexityRegion[ f,  {x, y, z}]

WARNINGS

The following example appears to give misinformation.

(10) Giving NCConvexityRegion polys that aren't symmetric.

NCConvexityRegion[1 + x ** y, {x, y}]

1+xy is not matrix convex everywhere.  What happened here?  We gave NCConvexityRegion a poly that isn't symmetric.  NCConvexityRegion only works with symmetric polys.  If we give it the symmetric version we get:

NCConvexityRegion[1 + x ** y + y ** x, {x, y}]

This is correct.  1+xy+yx is not matrix convex anywhere.

(11) NCConvexityRegion cannot handle commutative variables.

SetCommutative[A, B, F, G];
NCConvexityRegion[(A + B*x) ** inv[F + G*x] + 
        tp[ (A + B*x) ** inv[F + G*x] ], {x, y}]

NCConvexityRegion[A*x ** x ** x ** x ** x,  {x}]

In both of the above examples NCConvexityRegion had problems.  In the first we get symmetry errors, although the poly is symmetric.  In the second we get weird inverses.  So don't feed NCConvexityRegion commutative variables.

(12) Testing linear functions with NCConvexityRegion.

NCConvexityRegion[1 + x,  {x}]

A linear function is convex everywhere, but strictly convex nowhere.  This is reflected in the output 0.