MueLu/HHG: document edge-based splitting scheme

packages/muelu/research/mmayr/composite_to_regions/doc/doc.tex

@@ -367,6 +367,55 @@ \section{DOFs vs. GIDs for region problems}
 by another processor (that also owns my one region).
 
 \section{Algorithmic building blocks and implementation}
+
+\subsection{Splitting of the composite matrix into region matrices}
+
+To enable a non-invasive solver that exploits the partial structure of the grid
+we start from the composite matrix, i.e. a matrix that has been fully assembled
+by the application code. However, decomposing this matrix into region submatrices
+that correspond to the structured portions of the grid is not a unique operation.
+We'd like to design a software interface that 
+\begin{itemize}
+\item provides generic decomposition strategies
+\item allows the user to provide additional information and strategies
+\end{itemize}
+
+\subsubsection{A generic splitting scheme: edge-based splitting}
+
+We utilize two interpretations of matrix entries:
+\begin{itemize}
+\item off-diagonal entries~$a_{ij}$ for~$i \neq j$: 
+A matrix contribution~$a_{ij}$ for~$i \neq j$ can be viewed as an edge between node~$i$ and node~$j$. 
+Though, $a_{ij}$ really comes about as a sum of element contributions from neighboring elements, 
+our hope is that we don't have to worry about element information and so this simple edge view is sufficient.
+\item diagonal entries~$a_{ii}$: 
+A matrix contribution at~$a_{ii}$ should \emph{not} be viewed as an edge between node~$i$ and node~$i$. 
+Instead, the value of~$a_{ii}$ is really some kind of sum of contributions from all the $(i,j)$ edges 
+and, thus, this is how it should be treated in any splitting code. We aim at choosing the diagonal values 
+such that the nullspace of each region submatrix is preserved in comparison to the composite matrix.
+\end{itemize}
+We process off-diagonal entries and diagonal entries differently.
+
+For and edge, it is known, to which regions its nodes~$i$ and~$j$ belong to, namely:
+\begin{itemize}
+\item If nodes~$i$ and~$j$ belong to one and the same region, this is an interior edge.
+\item If nodes~$i$ and~$j$ belong to the same two regions, this is an interface edge.
+\end{itemize}
+
+The generic edge-based splitting algorithm consists of two steps:
+\begin{enumerate}
+\item Process off-diagonals: Interior edges don't need to be changed. 
+Interface edges are shared by two regions and, thus, need to be splitted (divided by $2$).
+\item Process diagonal entries: Diagonal entries need to be chosen to preserve
+nullspace properties for region matrices. We take the $k$th region matrix~$A^{(k)}$ 
+and multiply it with its portion of the global nullspace vector, i.e. $z^{(k)} = A^{(k)}v^{(k)}$. 
+The result~$z^{(k)}$ now contains the correction for the diagonal entries, i.e. $diag{(A^{(k)})} := diag{(A^{(k)})} - z^{(k)}$.
+\end{enumerate}
+
+Note: Rows of Dirichlet nodes have only a diagonal element. Processing edges~$a_{ij}$ does not affect these rows. 
+The nullspace constraint doesn't affect them either. However, they require splitting of the~$a_{ii} = 1$ diagonal element 
+into two entries~$a_{ii}^{(k_1)} = 0.5$ and~$a_{ii}^{(k_2)} = 0.5$. This is done in a separate step.
+
 \subsection{Groups}
 The notion of a group is introduced primarily to handle the case when
 processors are assigned multiple regions (and so no region spans