Tutorial-IllinoisGRMHD: eigen.C¶

Authors: Leo Werneck & Zach Etienne¶

This module is currently under development

This tutorial module demonstrates how to obtain the eigenvalues of a $3\times3$ matrix.¶

Note: This module will likely be absorbed by another one once we finish documenting the code.¶

Required and recommended citations:¶

• (Required) Etienne, Z. B., Paschalidis, V., Haas R., Mösta P., and Shapiro, S. L. IllinoisGRMHD: an open-source, user-friendly GRMHD code for dynamical spacetimes. Class. Quantum Grav. 32 (2015) 175009. (arxiv:1501.07276).
• (Required) Noble, S. C., Gammie, C. F., McKinney, J. C., Del Zanna, L. Primitive Variable Solvers for Conservative General Relativistic Magnetohydrodynamics. Astrophysical Journal, 641, 626 (2006) (astro-ph/0512420).
• (Recommended) Del Zanna, L., Bucciantini N., Londrillo, P. An efficient shock-capturing central-type scheme for multidimensional relativistic flows - II. Magnetohydrodynamics. A&A 400 (2) 397-413 (2003). DOI: 10.1051/0004-6361:20021641 (astro-ph/0210618).

Table of Contents¶

$$\label{toc}$$

This module is organized as follows

0. Step 0: Source directory creation
1. Step 1: Introduction
2. Step 2: eigen.C
   1. Step 2.a: The variables used in eigen.C
   2. Step 2.b: Determining $\phi$
   3. Step 2.c: The eigenvalues of a $3\times3$ symmetric matrix
3. Step 3: Code validation
4. Step 4: Output this notebook to $\LaTeX$-formatted PDF file

Step 0: Source directory creation [Back to top]¶

$$\label{src_dir}$$

We will now use the cmdline_helper.py NRPy+ module to create the source directory within the IllinoisGRMHD NRPy+ directory, if it does not exist yet.

Step 1: Introduction [Back to top]¶

$$\label{introduction}$$

In this tutorial notebook we will implement an algorithm to evaluate the eigenvalues of a $3\times3$ symmetric matrix. Our method will be analytical and will follow closely this discussion.

Let $\mathcal{M}$ be a $3\times3$ symmetric matrix,

$$\mathcal{M} = \begin{pmatrix} M_{11} & M_{12} & M_{13}\\ M_{12} & M_{22} & M_{23}\\ M_{13} & M_{23} & M_{33} \end{pmatrix}\ .$$

To obtain the eigenvalues of $\mathcal{M}$, we must solve the characteristic equation

$$\det\left(\lambda I_{3\times3} - \mathcal{M}\right) = 0\ ,$$

where $\lambda$ represents the eigenvalues of $\mathcal{M}$ and $I_{3\times3} = {\rm diag}\left(1,1,1\right)$ is the $3\times3$ identity matrix. For this particular case, the characteristic equation of $\mathcal{M}$ is then given by

$$\lambda^{3} - {\rm tr}\left(\mathcal{M}\right)\lambda^{2} + \left[\frac{{\rm tr}\left(\mathcal{M}^{2}\right) - {\rm tr}\left(\mathcal{M}\right)^{2}}{2}\right]\lambda - \det\left(\mathcal{M}\right) = 0\ .$$

Now let $\mathcal{M} = n\mathcal{N} + mI_{3\times3}$, so that the matrices $\mathcal{M}$ and $\mathcal{N}$ have the same eigenvectors. Then, $\kappa$ is an eigenvalue of $\mathcal{N}$ if, and only if, $\lambda = n\kappa + m$ is an eigenvalue of $\mathcal{M}$. Now, let us look at the following identities:

$$\mathcal{N} = \frac{1}{n}\left(\mathcal{M} - mI_{3\times3}\right)\ .$$

Choosing $m \equiv \frac{1}{3}{\rm tr}\left(\mathcal{M}\right)$, we get

$${\rm tr}\left(\mathcal{N}\right) = \frac{1}{n}\left(\mathcal{M} - 3m\right)=0\ .$$

Also,

$${\rm tr}\left(\mathcal{N}^{2}\right) = \frac{1}{n^{2}}\left[N_{11}^{2}+N_{22}^{2}+N_{33}^{2}+2\left(N_{12}^{2}+N_{13}^{2}+N_{23}^{2}\right)\right]\ ,$$

so that if we choose $n\equiv\sqrt{\frac{N_{11}^{2}+N_{22}^{2}+N_{33}^{2}+2\left(N_{12}^{2}+N_{13}^{2}+N_{23}^{2}\right)}{6}}$ we get

$${\rm tr}\left(\mathcal{N}^{2}\right) = 6\ .$$

Then, if we look at the characteristic equation for the matrix $\mathcal{N}$,

$$\kappa^{3} - {\rm tr}\left(\mathcal{N}\right)\kappa^{2} + \left[\frac{{\rm tr}\left(\mathcal{N}^{2}\right) - {\rm tr}\left(\mathcal{N}\right)^{2}}{2}\right]\kappa - \det\left(\mathcal{N}\right) = 0\ ,$$

we see that it can be greatly simplified with our choices of $m$ and $n$,

$$\kappa^{3} - 3\kappa - \det\left(\mathcal{N}\right) = 0\ .$$

Further simplification of this characteristic equation can be obtained by using

$$\begin{align} \kappa &\equiv 2\cos\phi\ ,\\ \cos\left(3\phi\right) &= 4\cos^{3}\phi - 3\cos\phi\ , \end{align}$$

so that

$$\begin{align} 0 &= 8\cos^{3}\phi - 6\cos\phi - \det\left(\mathcal{N}\right)\\ &= 2\cos\left(3\phi\right) - \det\left(\mathcal{N}\right)\\ \implies \phi &= \frac{1}{3}\arccos\frac{\det\left(\mathcal{N}\right)}{2} + \frac{2k\pi}{3}\ ,\ k=0,1,2\ , \end{align}$$

which, finally, yields

$$\boxed{\kappa\left(k\right) = 2\cos\left(\frac{1}{3}\arccos\frac{\det\left(\mathcal{N}\right)}{2}+\frac{2k\pi}{3}\right)}\ .$$

Once we have $\kappa$, we can find the eigenvectors of $\mathcal{M}$ doing

$$\boxed{ \begin{align} \lambda_{1} &= m + 2n\kappa(0)\\ \lambda_{2} &= m + 2n\kappa(1)\\ \lambda_{3} &= 3m - \lambda_{1} - \lambda_{2} \end{align} }\ ,$$

where we have used the fact that ${\rm tr}\left(\mathcal{M}\right)=\lambda_{1}+\lambda_{2}+\lambda_{3}$ to compute $\lambda_{3}$.

Step 2: eigen.C [Back to top]¶

$$\label{eigen__c}$$

Step 2.a: The variables used in eigen.C [Back to top]¶

$$\label{eigen__c__variables}$$

In the algorithm below, we define the following quantities

$$\boxed{ \begin{align} \mathcal{K} &= \mathcal{M} - mI_{3\times3}\\ m &= \frac{{\rm tr}\left(\mathcal{M}\right)}{3}\\ q &= \frac{\det\left(\mathcal{K}\right)}{2}\\ p &= n^{2} = \frac{{\rm tr}\left(\mathcal{K}^{2}\right)}{6} \end{align} }\ .$$

We these definitions, we have the following quantities to be implemented:

$$\boxed{ m = \frac{\left(M_{11} + M_{22} + M_{33}\right)}{3} }\ .$$

The matrix $\mathcal{K}$ is simply

$$\boxed{ \mathcal{K} = \begin{pmatrix} M_{11}-m & M_{12} & M_{13}\\ M_{12} & M_{22}-m & M_{23}\\ M_{13} & M_{23} & M_{33}-m \end{pmatrix} }\ .$$

Straightforwardly, we have

$$\boxed{q = \frac{K_{11}K_{22}K_{33} + K_{12}K_{23}K_{13} + K_{13}K_{12}K_{23} - K_{13}K_{22}K_{13} - K_{12}K_{12}K_{33} - K_{11}K_{23}K_{23} }{2} }\ .$$

Since $\mathcal{K}$ is symmetric as well, we have

$$\boxed{p = \frac{K_{11}^{2} + K_{22}^{2} + K_{33}^{2} + 2\left(K_{12}^{2} + K_{13}^{2} + K_{23}^{2}\right)}{6}}\ .$$

Step 2.b: Determining $\phi$ [Back to top]¶

$$\label{eigen__c__phi}$$

We then employ the following criterion to determine $\phi$:

$$\phi = \left\{ \begin{matrix} 0 &,\ {\rm if}\ \left|q\right| \geq p^{3/2}\ ,\\ \arccos\left(\frac{q}{p^{3/2}}\right) &,\ {\rm otherwise}\ . \end{matrix} \right.$$

Step 2.c: The eigenvalues of a $3\times3$ symmetric matrix [Back to top]¶

$$\label{eigen__c__eigenvalues}$$

Finally, the eigenvalues are computed using

$$\boxed{ \begin{align} \lambda_{1} &= m + 2\sqrt{p}\cos\phi\\ \lambda_{2} &= m - \sqrt{p}\cos\phi - \sqrt{3p}\sin\phi\\ \lambda_{3} &= m - \sqrt{p}\cos\phi + \sqrt{3p}\sin\phi \end{align} }\ .$$

Step 3: Code validation [Back to top]¶

$$\label{code_validation}$$

First we download the original IllinoisGRMHD source code and then compare it to the source code generated by this tutorial notebook.

Step 4: Output this notebook to $\LaTeX$-formatted PDF file [Back to top]¶

$$\label{latex_pdf_output}$$

The following code cell converts this Jupyter notebook into a proper, clickable $\LaTeX$-formatted PDF file. After the cell is successfully run, the generated PDF may be found in the root NRPy+ tutorial directory, with filename Tutorial-IllinoisGRMHD__eigen.pdf (Note that clicking on this link may not work; you may need to open the PDF file through another means).