NCConvexityRegion[afunction,alistOfVars,opts]

Aliases: None.

Description: NCConvexityRegion[afunction,alistOfVars,opts] computes the "region" on which afunction is matrix convex with respect to alistOfVars. It performs three main operations. First it computes the Hessian with respect to alistOfVars (see NCHessian). Then, using NCMatrixOfQuadratic, the Hessian is factored into the form $v^tMv$. Finally, depending on the option AllPermutation, either NCAllPermutationLDU or NCLDUDecomposition is called to compute the $L D U$ factorization of $M$, the default being AllPermutation $\rightarrow$ NCLDUDecomposition. If $D$ ends up being diagonal, then a list of the diagonal elements of $D$ is returned. If $D$ ends up being block diagonal with $2\times 2$ blocks, then a message is printed out and the list: $\{\{diagonal entries\}, \{subdiagonal entries\},\{-subdiagonal entries\}\}$ is returned. The region of convexity of afunction with respect to alistOfVars equals the closure, in a certain sense, of the set of matrices which makes all diagonal entries positive. If there are non-zero subdiagonal entries, then afunction is typically not matrix convex on any open set. Options permit the user to select a range of different permutation matrices, thereby producing several possibly distinct diagonal matrices $D$.
EXAMPLE: NCConvexityRegion $[x**y + y**x,\{x,y\}]$ gives:
L**D**tp[L] gave non-trivial blocks, so the output list is:
{{diagonal},{subdiagonal},{-subdiagonal}}
$\{\{\{0, 0\}, \{2\}, \{-2\}\}\}$
While, NCConvexityRegion $[x**y + y**x,\{x,y\}, AllPermutation \rightarrow True ]$ gives:
Middle matrix is size 2 X 2
At most 2 permutations possible.
$\{1\}$
L**D**tp[L] gave non-trivial blocks, so the output list is:
{{diagonal},{subdiagonal},{-subdiagonal}}
$\{\{\{0, 0\}, \{2\}, \{-2\}\}\}$
In both cases, NCHessian $[x**y+y**x,\{x,h\},\{y,k\}]$ gives
${2 h**k + 2 k**h}$,
NCMatrixOfQuadratic $[2 h**k + 2 k**h,\{h,k\}]$ gives
$\{\{\{h, k\}\}, \{\{0, 2\}, \{2, 0\}\},\{\{h\}, \{k\}\}\}$,
and depending on if AllPermutation is set to True or False you have that either NCLDUDecomposition $[ \{\{0, 2\}, \{2, 0\}\}]$ gives
$\{\{\{1, 0\}, \{0, 1\}\}, \{\{0, 2\}, \{2, 0\}\}, \{\{1, 0\}, \{0, 1\}\}, \{\{1, 0\}, \{0, 1\}\}\}$
or NCAllPermutationLDU $[ \{\{0, 2\}, \{2, 0\}\}]$ gives
$\{\{\{\{1, 0\}, \{0, 1\}\}, \{\{0, 2\}, \{2, 0\}\}, \{\{1, 0\}, \{0, 1\}\}, \{\{1, 0\}, \{0, 1\}\}\},$
$\{\{\{1, 0\}, \{0, 1\}\}, \{\{0, 2\}, \{2, 0\}\}, \{\{1, 0\}, \{0, 1\}\}, \{\{1, 0\}, \{0, 1\}\}\}\}$

Arguments: $afunction$ is a function whose variables are listed in $alistOfVars$, where $alistOfVars$ should be of the form $\{x_1,x_2,\ldots,x_n \}.$
The default options for NCConvexityRegion are:
NCSimplifyDiagonal $\rightarrow$False
DiagonalSelection $\rightarrow$ False
ReturnPermutation $\rightarrow$ False
ReturnBorderVector $\rightarrow$ False
AllPermutation $\rightarrow$ False
NCSimplifyDiagonal is an option geared toward a similar option used in
NCLDUDecomposition. This will make sure that the pivots (or diagonal entries) are all first simplified with NCSimplifyRational before they are used to check that the pivots are all nonzero. Simplifying the pivots using NCSimplifyRational can be quite time consuming, so by default we commute everything and then use Mathematica simplification commmands. We do this only to convince ourselves that the pivot is nonzero. If all the pivots are zero using CommuteEverything we then revert to using NCSimplifyRational to verify our suspicions. Setting NCSimplifyDiagonal $\rightarrow$ True will bypass the commute everything step. (Note: Either way, the unsimplified form of the pivot is returned unless it is equal to zero.)
The option AllPermutation tells NCConvexityRegion which of
NCLDUDecomposition or NCAllPermutationLDU to use. Setting AllPermutation to True will use
NCAllPermutationLDU,while False uses NCLDUDecomposition. The default value is AllPermutation $\rightarrow$ False. The following pertains to the case where AllPermutation is set to True. If you decide to do this, then you should also set DiagonalSelection to the permutations you would like NCAllPermutationLDU to use. Since different permutations return different diagonals, some diagonals are simpler to work with than others. On the other hand, if AllPermutation is set to False, which it defaults to, then NCConvexityRegion calls NCLDUDecomposition and what follows does not apply as no permutations are used. Different permutations return different diagonals. Some diagonals are simpler to work with than others. Because of this, we allow the user to select a sampling of different permutations. The total number of permutations will not be known until $M$ is computed. After $M$ is computed, the total number of possible permutations will be printed on the screen. DiagonalSelection $\rightarrow$ {$n$} returns the diagonals resulting from the first $n$ permutations. DiagonalSelection $\rightarrow$ {$k$,$n$} returns the diagonals resulting from the $k^{th}$ through $n^{th}$ permutations. Since the total number of permutations is assumed to be unknown by the user, if $n$ is too high, then $n$ is replaced by the total number of permutations. Also, not all of the permutations are permissible. Because of this, NCLDUDecomposition automatically pivots if an invalid permutation is used for a particular step. This means it is possible that not all the diagonals returned result from different permutations. For this reason there is the option ReturnPermutation which if entered as True returns the permutations used for each resulting factorization. Finally, the user may wish to analyze the border vectors and may do so by setting ReturnBorderVector to True. This will cause NCConvexityRegion to return the border vectors $v$ from the $v^tMv$ factorization of the hessian. Now $v^t$ will have the form

$$\begin{matrix} L_{11}H_1, L_{12}H_1, \cdots, L_{1k_1}H_1, \cdots L_{n1}H_n, L_{n2}H_n, \cdots, L_{nk_n}H_n \end{matrix}$$

So what will actually be returned is a list of the form

$$\{\{ L_{11},\ldots,L_{1k_1} \} ,...,\{L_{n1},\ldots,L_{nk_n} \} \}.$$

This vector will be formed using a call to NCBorderVectorGather. Also, a call will be made to NCIndependenceCheck to determine, if possible, whether or not the elements of the above list are independent. The results of this check will be printed to the screen.

Comments / Limitations: None.