add docstrings for 1D ideal multicomponent glm-mhd equations (#2642)

* add docstrings for 1D ideal multicomponent glm-mhd equations

* Apply suggestions from code review

* small addition

* added docstrings for 2D ideal glm-mhd multicomponent equations

---------

Co-authored-by: Daniel Doehring <[email protected]>
Co-authored-by: Hendrik Ranocha <[email protected]>

Author: 3 people

src/equations/ideal_glm_mhd_multicomponent_1d.jl

@@ -8,7 +8,45 @@
 @doc raw"""
     IdealGlmMhdMulticomponentEquations1D
 
-The ideal compressible multicomponent GLM-MHD equations in one space dimension.
+The ideal compressible multicomponent GLM-MHD equations
+```math
+\frac{\partial}{\partial t}
+\begin{pmatrix}
+\rho v_1 \\ \rho v_2 \\ \rho v_3 \\ \rho e \\ B_1 \\ B_2 \\ B_3 \\ \rho_1 \\ \vdots \\ \rho_{n}
+\end{pmatrix}
++
+\frac{\partial}{\partial x}
+\begin{pmatrix}
+\rho v_1^2 + p + \frac{1}{2} \Vert \mathbf{B} \Vert_2 ^2 - B_1^2 \\ \rho v_1 v_2 - B_1 B_2 \\ \rho v_1 v_3 - B_1 B_3
+\\ (\frac{1}{2} \rho \Vert \mathbf{v} \Vert_2 ^2 + \frac{\gamma p}{\gamma - 1} + \Vert \mathbf{B} \Vert_2 ^2) v_1 - B_1 (\mathbf{v} \cdot \mathbf{B})
+\\ 0 \\ v_1 B_2 - v_2 B_1 \\ v_1 B_3 - v_3 B_1 \\ \rho_1 v_1 \\ \vdots \\ \rho_{n} v_1
+\end{pmatrix}
+=
+\begin{pmatrix}
+0 \\ 0 \\ 0 \\ 0 \\ 0 \\ 0 \\ 0 \\ 0 \\ \vdots \\ 0
+\end{pmatrix}
+```
+for calorically perfect gases in one space dimension.
+Here, ``\rho_i`` is the density of component ``i``, ``\rho=\sum_{i=1}^n\rho_i`` the sum of the individual ``\rho_i``,
+``\mathbf{v}`` the velocity, ``\mathbf{B}`` the magnetic field, ``e`` the specific total energy **rather than** specific internal energy, and
+```math
+p = (\gamma - 1) \left( \rho e - \frac{1}{2} \rho \Vert \mathbf{v} \Vert_2 ^2 - \frac{1}{2} \Vert \mathbf{B} \Vert_2 ^2 \right)
+```
+the pressure,
+```math
+\gamma=\frac{\sum_{i=1}^n\rho_i C_{v,i}\gamma_i}{\sum_{i=1}^n\rho_i C_{v,i}}
+```
+total heat capacity ratio, ``\gamma_i`` heat capacity ratio of component ``i``,
+```math
+C_{v,i}=\frac{R_i}{\gamma_i-1}
+```
+specific heat capacity at constant volume of component ``i``.
+
+In case of more than one component, the specific heat ratios `gammas` and the gas constants
+`gas_constants` should be passed as tuples, e.g., `gammas = (1.4, 1.667)`.
+
+The remaining variables like the specific heats at constant volume `cv` or the specific heats at
+constant pressure `cp` are then calculated considering a calorically perfect gas.
 """
 struct IdealGlmMhdMulticomponentEquations1D{NVARS, NCOMP, RealT <: Real} <:
        AbstractIdealGlmMhdMulticomponentEquations{1, NVARS, NCOMP}

src/equations/ideal_glm_mhd_multicomponent_2d.jl

@@ -8,7 +8,58 @@
 @doc raw"""
     IdealGlmMhdMulticomponentEquations2D
 
-The ideal compressible multicomponent GLM-MHD equations in two space dimensions.
+The ideal compressible multicomponent GLM-MHD equations
+```math
+\frac{\partial}{\partial t}
+\begin{pmatrix}
+\rho \mathbf{v} \\ \rho e \\ \mathbf{B} \\ \psi \\ \rho_1 \\ \vdots \\ \rho_{n}
+\end{pmatrix}
++
+\nabla \cdot
+\begin{pmatrix}
+\rho (\mathbf{v} \otimes \mathbf{v}) + (p + \frac{1}{2} \Vert \mathbf{B} \Vert_2 ^2) \underline{I} - \mathbf{B} \otimes \mathbf{B} \\
+\mathbf{v} (\frac{1}{2} \rho \Vert \mathbf{v} \Vert_2 ^2 + \frac{\gamma p}{\gamma - 1} + \Vert \mathbf{B} \Vert_2 ^2) - \mathbf{B} (\mathbf{v} \cdot \mathbf{B}) + c_h \psi \mathbf{B} \\
+\mathbf{v} \otimes \mathbf{B} - \mathbf{B} \otimes \mathbf{v} + c_h \psi \underline{I} \\
+c_h \mathbf{B} \\ \rho_1 \mathbf{v} \\ \vdots \\ \rho_{n} \mathbf{v}
+\end{pmatrix}
++
+(\nabla \cdot \mathbf{B})
+\begin{pmatrix}
+\mathbf{B} \\ \mathbf{v} \cdot \mathbf{B} \\ \mathbf{v} \\ 0 \\ 0 \\ \vdots \\ 0
+\end{pmatrix}
++
+(\nabla \psi) \cdot
+\begin{pmatrix}
+0 \\ \mathbf{v} \cdot \psi \\ 0 \\ \mathbf{v} \\ \mathbf{0} \\ \vdots \\ \mathbf{0}
+\end{pmatrix}
+=
+\begin{pmatrix}
+\mathbf{0} \\ 0 \\ \mathbf{0} \\ 0 \\ 0 \\ \vdots \\ 0
+\end{pmatrix}
+```
+for calorically perfect gases in two space dimensions.
+Here, ``\rho_i`` is the density of component ``i``, ``\rho=\sum_{i=1}^n\rho_i`` the sum of the individual ``\rho_i``,
+``\mathbf{v}`` the velocity, ``\mathbf{B}`` the magnetic field, ``c_h`` the hyperbolic divergence cleaning speed,
+``\psi`` the generalized Lagrangian Multiplier (GLM),
+``e`` the specific total energy **rather than** specific internal energy, and
+```math
+p = (\gamma - 1) \left( \rho e - \frac{1}{2} \rho \Vert \mathbf{v} \Vert_2 ^2 - \frac{1}{2} \Vert \mathbf{B} \Vert_2 ^2 - \frac{1}{2} \psi^2 \right)
+```
+the pressure,
+```math
+\gamma=\frac{\sum_{i=1}^n\rho_i C_{v,i}\gamma_i}{\sum_{i=1}^n\rho_i C_{v,i}}
+```
+total heat capacity ratio, ``\gamma_i`` heat capacity ratio of component ``i``,
+```math
+C_{v,i}=\frac{R_i}{\gamma_i-1}
+```
+specific heat capacity at constant volume of component ``i`` and ``\underline{I}`` the ``2\times 2`` identity matrix.
+
+In case of more than one component, the specific heat ratios `gammas` and the gas constants
+`gas_constants` should be passed as tuples, e.g., `gammas = (1.4, 1.667)`.
+
+The remaining variables like the specific heats at constant volume `cv` or the specific heats at
+constant pressure `cp` are then calculated considering a calorically perfect gas.
 """
 struct IdealGlmMhdMulticomponentEquations2D{NVARS, NCOMP, RealT <: Real} <:
        AbstractIdealGlmMhdMulticomponentEquations{2, NVARS, NCOMP}