Update docs

docs_Adding_docs.html

@@ -189,7 +189,12 @@ <h1><a class="anchor" id="docs_Adding_docs__Mathematical_notation_in_documentati
 Mathematical notation in documentation</h1>
 <p>Mathematical notation can be used in Doxygen output.</p>
 <p>In Markdown files it should be blocked with <code>$</code> commands. E.g: </p><div class="fragment"><div class="line">$a \ne b$</div>
-</div><!-- fragment --><p>An equation can also be printed on its own line using <code>$$</code> commands.</p>
+</div><!-- fragment --><p> However if the equation includes characters which are used for markdown highlighting it is safer to use the following syntax: </p><div class="fragment"><div class="line">$`a \ne b`$</div>
+</div><!-- fragment --><p>An equation can also be printed on its own line using <code>$$</code> commands. The syntax must be one of the following: </p><div class="fragment"><div class="line">$$a \ne b$$</div>
+</div><!-- fragment --><p> or </p><div class="fragment"><div class="line">$$</div>
+<div class="line">a \ne b</div>
+<div class="line">$$</div>
+</div><!-- fragment --><p> The first syntax can be used when the expression fits in one line and doesn't use markdown special characters. The second syntax can be used in all contexts.</p>
 <p>In C++ header files it should be blocked with Doxagen syntax, i.e. <code>@f$</code> instead of <code>$</code>, and <code>@f[</code> and <code>@f]</code> instead of <code>$$</code>. </p>
 </div></div><!-- contents -->
 </div><!-- PageDoc -->

index.html

@@ -117,9 +117,9 @@ <h1><a class="anchor" id="__Compilation"></a>
 Execution</h1>
 <p>to run the tests: </p><div class="fragment"><div class="line">ctest --output-on-failure</div>
 </div><!-- fragment --><p>Then, just have a look at <code>tests/landau/growthrate_t0.0to45.0.png</code>:</p>
-<p><img src="https://gitlab.maisondelasimulation.fr/gysela-developpers/gyselalibxx/-/jobs/artifacts/main/raw/build/tests/landau/fft/growthrate_t0.0to45.0.png?job=cmake_tests_Release" alt="tests/landau/fft/growthrate_t0.0to45.0.png" title="Landau damping rate" class="inline"/></p>
+<p><img src="https://gitlab.maisondelasimulation.fr/gysela-developpers/gyselalibxx/-/jobs/artifacts/main/raw/build/tests/landau/fft/growthrate_t0.0to45.0.png?job=cmake_tests_Release" alt="tests/landau/fft/growthrate\_t0.0to45.0.png" title="Landau damping rate" class="inline"/></p>
 <p>and <code>tests/landau/frequency_t0.0to45.0.png</code>:</p>
-<p><img src="https://gitlab.maisondelasimulation.fr/gysela-developpers/gyselalibxx/-/jobs/artifacts/main/raw/build/tests/landau/fft/frequency_t0.0to45.0.png?job=cmake_tests_Release" alt="tests/landau/fft/frequency_t0.0to45.0.png" title="Landau damping frequency" class="inline"/></p>
+<p><img src="https://gitlab.maisondelasimulation.fr/gysela-developpers/gyselalibxx/-/jobs/artifacts/main/raw/build/tests/landau/fft/frequency_t0.0to45.0.png?job=cmake_tests_Release" alt="tests/landau/fft/frequency\_t0.0to45.0.png" title="Landau damping frequency" class="inline"/></p>
 <h1><a class="anchor" id="__Dependencies"></a>
 Dependencies</h1>
 <p>To install dependencies through spack, first follow the the 3 first steps of <a href="https://github.com/pdidev/spack">https://github.com/pdidev/spack</a></p>

simulations_geometryXVx_sheath.html

@@ -120,10 +120,15 @@ <h1><a class="anchor" id="simulations_geometryXVx_sheath__Recommended_parameters
 </ul>
 <h1><a class="anchor" id="simulations_geometryXVx_sheath__Verification_of_the_simulation"></a>
 Verification of the simulation</h1>
-<p>The accuracy of the physical results from a sheath simulation can be verified as follows. The simulation should be run with the parameters given in <code>sheath.yaml.hpp</code> file. Then, any conservation diagnostic can be used to test the accuracy of the results. For instance, a post-process script that breaks down the terms present in the equation of energy conservation is <code>post-process/PythonScripts/geometryXVx/sheath/plot_conservation_energy</code>. This script can be run as an executable in the folder containing the simulation results. In the simple XVx geometry The equation of energy conservation is written as</p>
-<p>\(\partial_t \Pi_a + 1/\sqrt{A_a}\, \partial_x Q_a - 2\Gamma_a q_a E/\sqrt{A_a} = S_{e}\) <br  />
+<p>The accuracy of the physical results from a sheath simulation can be verified as follows. The simulation should be run with the parameters given in <code>sheath.yaml.hpp</code> file. Then, any conservation diagnostic can be used to test the accuracy of the results. For instance, a post-process script that breaks down the terms present in the equation of energy conservation is <code>post-process/PythonScripts/geometryXVx/sheath/plot_conservation_energy</code>. This script can be run as an executable in the folder containing the simulation results. In the simple XVx geometry The equation of energy conservation is written as:</p>
+<p class="formulaDsp">
+\[\partial_t \Pi_a + 1/\sqrt{A_a}\, \partial_x Q_a - 2\Gamma_a q_a E/\sqrt{A_a} = S_{e}\]
 </p>
-<p>Where \(\Gamma_a\), \(\Pi_a\) and \(Q_a\) stand for the particle flux, momentum flux and energy flux of species \(a\) (typically ions or electrons) respectively. These quantity are computed by the script using the distribution function of each species which is an output of the code. \(A_a = m_e/m_a\) is the mass ratio of species \(a\), and \(q_a\) represents its charge ( \(+e\) for ions, \(-e\) for electrons with \(e\) the elementary charge). \(E\) is the electric field, and \(S_{e}\) the energy source term. The script plots all of the terms that appear in the energy conservation equation, along with the error (denoted as <code>lhs-rhs</code>) defined as being the left-hand-side term minus the right-hand-side terms, i.e. \(lhs-rhs = \partial_t \Pi_a + 1/\sqrt{A_a}\, \partial_x Q_a - 2\Gamma_a q_a E/\sqrt{A_a} - S_{e}\). This error term is plotted as well, and thus a simulation can be verified by ensuring that this error remains small as compared to the other terms. It is recommended to look at the conservation equation for electrons first, since as the lightest species, the numerical error is larger. The script also produces a 2D map of the error as a function of time and space. One shall note that in order to compute the time derivative term \(\partial_t \Pi_a\), it is important to save all of the timesteps of the simulations, i.e. the parameters <code>time_diag</code> and <code>deltat</code> should be equal, as in the <code>sheath.yaml.hpp</code> file. Lastly, if one wishes to test a simulation that is faster, the number of iterations can be reduced to 10 for instance. The folder <code>conservation_plots</code> contains the graphs of the conservation equations computed using a simulation with the parameters of the <code>sheath.yaml.hpp</code> file.</p>
+<p>Where \(\Gamma_a\), \(\Pi_a\) and \(Q_a\) stand for the particle flux, momentum flux and energy flux of species \(a\) (typically ions or electrons) respectively. These quantity are computed by the script using the distribution function of each species which is an output of the code. \(A_a = m_e/m_a\) is the mass ratio of species \(a\), and \(q_a\) represents its charge ( \(+e\) for ions, \(-e\) for electrons with \(e\) the elementary charge). \(E\) is the electric field, and \(S_{e}\) the energy source term. The script plots all of the terms that appear in the energy conservation equation, along with the error (denoted as <code>lhs-rhs</code>) defined as being the left-hand-side term minus the right-hand-side terms, i.e.</p>
+<p class="formulaDsp">
+\[lhs-rhs = \partial_t \Pi_a + 1/\sqrt{A_a}\, \partial_x Q_a - 2\Gamma_a q_a E/\sqrt{A_a} - S_{e}.\]
+</p>
+<p>This error term is plotted as well, and thus a simulation can be verified by ensuring that this error remains small as compared to the other terms. It is recommended to look at the conservation equation for electrons first, since as the lightest species, the numerical error is larger. The script also produces a 2D map of the error as a function of time and space. One shall note that in order to compute the time derivative term \(\partial_t \Pi_a\), it is important to save all of the timesteps of the simulations, i.e. the parameters <code>time_diag</code> and <code>deltat</code> should be equal, as in the <code>sheath.yaml.hpp</code> file. Lastly, if one wishes to test a simulation that is faster, the number of iterations can be reduced to 10 for instance. The folder <code>conservation_plots</code> contains the graphs of the conservation equations computed using a simulation with the parameters of the <code>sheath.yaml.hpp</code> file.</p>
 <h1><a class="anchor" id="simulations_geometryXVx_sheath__References"></a>
 References</h1>
 <ul>

src_geometryRTheta_advection.html

@@ -108,22 +108,19 @@
 <h3><a class="anchor" id="autotoc_md20"></a>
 Studied equation</h3>
 <p>The studied equation is the following 2D transport equation type : </p><p class="formulaDsp">
-\[\partial_t f(t,x,y) + A(t,x,y)\cdot\nabla f(t,x,y) = 0,\]
+\[\partial_t f(t,x,y) + A(t,x,y)\cdot\nabla f(t,x,y) = 0, \]
 </p>
-<p>with \(f(0,x,y) = f_0(x,y)\) and \(A\) the advection field.</p>
+<p> with \(f(0,x,y) = f_0(x,y)\) and \(A\) the advection field.</p>
 <p><b>We want to solve it on a polar grid.</b></p>
 <h3><a class="anchor" id="autotoc_md21"></a>
 Backward Semi-Lagrangian method</h3>
 <p>The method used to solve the equation is a Backward Semi-Lagrangian method (BSL). It uses the conservation along the characteristics property: </p><p class="formulaDsp">
-\[ \forall t, \quad f(t, x, y) = f(s, X(t; s, x, y), Y(t; s, x, y)) \]
+\[\forall t, \quad f(t, x, y) = f(s, X(t; s, x, y), Y(t; s, x, y)) \]
 </p>
-<p>with</p><ul>
-<li>\(\partial_t X (t; s, x, y) = A_x(t,X(t; s, x, y),Y(t; s, x, y))\),</li>
-<li>\(\partial_t Y (t; s, x, y) = A_y(t,X(t; s, x, y),Y(t; s, x, y))\),</li>
-<li>\(X(s; s, x, y) = x\),</li>
-<li>\(Y(s; s, x, y) = y\).</li>
-</ul>
-<p>So to compute the advected function at the next time step,</p><ul>
+<p> with: </p><p class="formulaDsp">
+\[\partial_t X (t; s, x, y) = A_x(t,X(t; s, x, y),Y(t; s, x, y)),\\ \partial_t Y (t; s, x, y) = A_y(t,X(t; s, x, y),Y(t; s, x, y)),\\ X(s; s, x, y) = x,\\ Y(s; s, x, y) = y. \]
+</p>
+<p> So to compute the advected function at the next time step,</p><ul>
 <li>we compute the characteristic feet \(X(t^n; t^{n+1}, x_i, y_j)\) and \(Y(t^n; t^{n+1}, x_i, y_j)\) for each mesh points \((x_i, y_j)\) with a time integration method ;</li>
 <li>we interpolate the function \(f(t = t^n)\) on the characteristic feet. The proprety ensures that the interpolation gives the function at the next time step \(f(t = t^{n+1})\).</li>
 </ul>
@@ -187,7 +184,7 @@ <h3><a class="anchor" id="autotoc_md27"></a>
 <p>It seems logical to use the <b>physical domain</b>, where the studied equation is given, as the advection domain.</p>
 <p>However, we want to solve this equation on a polar grid. So before advecting, we have to compute the mesh points in the physical domain using a mapping function \(\mathcal{F}\):</p>
 <p class="formulaDsp">
-\[ \mathcal{F} : (r,\theta)_{i,j} \mapsto (x,y)_{i,j}. \]
+\[\mathcal{F} : (r,\theta)_{i,j} \mapsto (x,y)_{i,j}. \]
 </p>
 <p>This adds some steps to the advection operator, we now have to compute</p><ul>
 <li>the mesh points in the physical domain using \(\mathcal{F}\);</li>
@@ -200,7 +197,7 @@ <h3><a class="anchor" id="autotoc_md27"></a>
 <p class="formulaDsp">
 \[ \mathcal{G} : (r,\theta)_{i,j} \mapsto (x,y)_{i,j} = (r\cos(\theta), r\sin(\theta))_{i,j}. \]
 </p>
-<p>Then the four previous steps become</p><ul>
+<p> Then the four previous steps become</p><ul>
 <li>calculate the mesh points in the pseudo-Cartesian domain using \(\mathcal{G}\);</li>
 <li>calculate the advection field \(A\) in the pseudo-Cartesian domain using the Jacobian matrix of \((\mathcal{F}\circ\mathcal{G}^{-1})^{-1}\);</li>
 <li>calculate the characteristic feet in the pseudo_Cartesian domain;</li>

src_geometryRTheta_poisson.html

@@ -109,17 +109,17 @@
 in the 5D GYSELA Code". December 2022.)</p>
 <p>The equation we are solving here is</p>
 <p class="formulaDsp">
-\[L\phi = - \nabla \cdot (\alpha \nabla \phi) + \beta \phi = \rho\]
+\[L\phi = - \nabla \cdot (\alpha \nabla \phi) + \beta \phi = \rho \]
 </p>
-<p>with the boundary condition \(\phi = 0\), on \(\partial \Omega\).</p>
+<p> with the boundary condition \(\phi = 0\), on \(\partial \Omega\).</p>
 <p>To solve this equation, the <a class="el" href="classPolarSplineFEMPoissonSolver.html" title="Define a polar Poisson solver.">PolarSplineFEMPoissonSolver</a> uses a finite element method on the B-splines.</p>
 <h3><a class="anchor" id="autotoc_md28"></a>
 B-splines FEM</h3>
 <h4><a class="anchor" id="autotoc_md29"></a>
 The B-splines</h4>
 <p>We introduce a basis of B-splines \(\{B_l\}_l\), cross-product of two 1D B-splines basis:</p>
 <p class="formulaDsp">
-\[\{B_l\}_l = \{b_{i,r} b_{j,\theta}\}_{i n_{n,\theta} +j}.\]
+\[\{B_l\}_l = \{b_{i,r} b_{j,\theta}\}_{i n_{n,\theta} +j}. \]
 </p>
 <h4><a class="anchor" id="autotoc_md30"></a>
 Treatment of the O-point</h4>
@@ -131,14 +131,14 @@ <h4><a class="anchor" id="autotoc_md31"></a>
 Weak formulation</h4>
 <p>The Poisson equation is solved by solving its weak form:</p>
 <p class="formulaDsp">
-\[\int_{\Omega} \lbrack \beta(r) \phi(r,\theta) \hat{B}_l(r,\theta) + \alpha(r) \nabla \phi(r,\theta) \cdot \nabla \hat{B}_l(r,\theta) \rbrack |det(J_{\mathcal{F}}(r,\theta))| dr d\theta = \int_{\Omega} \rho(r,\theta) \hat{B}_l(r,\theta) |det(J_{\mathcal{F}}(r,\theta))| dr d\theta\]
+\[\int_{\Omega} \lbrack \beta(r) \phi(r,\theta) \hat{B}_l(r,\theta) + \alpha(r) \nabla \phi(r,\theta) \cdot \nabla \hat{B}_l(r,\theta) \rbrack |det(J_{\mathcal{F}}(r,\theta))| dr d\theta = \int_{\Omega} \rho(r,\theta) \hat{B}_l(r,\theta) |det(J_{\mathcal{F}}(r,\theta))| dr d\theta \]
 </p>
-<p>with \(\{\hat{B}_l\}_l\) the B-splines basis.</p>
+<p> with \(\{\hat{B}_l\}_l\) the B-splines basis.</p>
 <p>Written as matrix form, it gives</p>
 <p class="formulaDsp">
-\[(M + S) \hat{\phi} = M \hat{\rho},\]
+\[(M + S) \hat{\phi} = M \hat{\rho}, \]
 </p>
-<p>with</p><ul>
+<p> with</p><ul>
 <li>the mass matrix, \(M_{i,j} = \int_{\Omega} \beta(r,\theta) \hat{B}_i(r,\theta)\hat{B}_j(r,\theta) |det(J_{\mathcal{F}}(r,\theta))| dr d\theta\),</li>
 <li>the stiffness matrix, \(S_{i,j} = \int_{\Omega} \alpha(r) \left[\sum_{\xi_1\in[r,\theta]} \sum_{\xi_2\in[r,\theta]} \partial_{\xi_1}\hat{B}_i(r,\theta) \partial_{\xi_2}\hat{B}_j(r,\theta) g^{\xi_1, \xi_2}\right] |det(J_{\mathcal{F}}(r,\theta))| dr d\theta\)<ul>
 <li>with \(g^{\xi_1, \xi_2}\), the scalar product between the unit vector in \(\xi_1\) and the unit vector in \(\xi_2\).</li>
@@ -154,22 +154,19 @@ <h1><a class="anchor" id="src_geometryRTheta_poisson__Evaluation_of_electric_fie
 <p>(See for more details, Edoardo Zoni's article, <a href="https://doi.org/10.1016/j.jcp.2019.108889">https://doi.org/10.1016/j.jcp.2019.108889</a> .)</p>
 <p>We write in this section \(\nabla_{r,\theta}\) the gradient in the logical coordinates \((r, \theta)\) and \(\nabla_{x,y}\) the gradient in the physical coordinates \((x, y)\).</p>
 <p>Coupled with the Vlasov equation </p><p class="formulaDsp">
-\[\partial_t \rho - E_y \partial_x \rho + E_x \partial_y\rho = 0,\]
+\[\partial_t \rho - E_y \partial_x \rho + E_x \partial_y\rho = 0, \]
 </p>
-<p>the <a class="el" href="classVlasovPoissonSolver.html" title="Solve the Poisson equation and return the electric field for the coupled Vlasov equation.">VlasovPoissonSolver</a> also computes the electric field \(E\) in the physical domain from the solution of <a class="el" href="classPolarSplineFEMPoissonSolver.html" title="Define a polar Poisson solver.">PolarSplineFEMPoissonSolver</a>.</p>
+<p> the <a class="el" href="classVlasovPoissonSolver.html" title="Solve the Poisson equation and return the electric field for the coupled Vlasov equation.">VlasovPoissonSolver</a> also computes the electric field \(E\) in the physical domain from the solution of <a class="el" href="classPolarSplineFEMPoissonSolver.html" title="Define a polar Poisson solver.">PolarSplineFEMPoissonSolver</a>.</p>
 <p>The electric field is given by \(E = -\nabla \phi\). The solution of the Poisson solver is defined on the logical domain, so we can easily compute \(\nabla_{r,\theta} \phi\). From that, we use the Jacobian matrix of the mapping \(\mathcal{F}\):</p>
 <p class="formulaDsp">
-\[ E_r e_r + E_\theta e_\theta = -\nabla_{r,\theta} \phi, \]
+\[E_r e_r + E_\theta e_\theta = -\nabla_{r,\theta} \phi,\\ E_x e_x + E_y e_y = J_{\mathcal{F}}(r,\theta)) (E_r e_r + E_\theta e_\theta), \]
 </p>
-<p class="formulaDsp">
-\[ E_x e_x + E_y e_y = J_{\mathcal{F}}(r,\theta)) (E_r e_r + E_\theta e_\theta), \]
-</p>
-<p>with \(e_i = \partial_{x_i}x\) the unnormalized local contravariant base.</p>
+<p> with \(e_i = \partial_{x_i}x\) the unnormalized local contravariant base.</p>
 <p>However the inverse Jacobian matrix \(J_{\mathcal{F}}\) can be ill-defined at the O-point. In Edoardo Zoni's article, they suggest to linearize around the O-point:</p>
 <p>for \(r &lt; \varepsilon\), </p><p class="formulaDsp">
-\[E(r, \theta) = \left( 1 - \frac{r}{\varepsilon} \right) E(0, \theta) + \frac{r}{\varepsilon} E(\varepsilon, \theta)\]
+\[E(r, \theta) = \left( 1 - \frac{r}{\varepsilon} \right) E(0, \theta) + \frac{r}{\varepsilon} E(\varepsilon, \theta) \]
 </p>
-<p>with \(E(0, \theta)\) computed thanks to</p><ul>
+<p> with \(E(0, \theta)\) computed thanks to</p><ul>
 <li>\(\partial_r \phi (0, \theta_1) = \left[\partial_r x \partial_x \phi + \partial_r y \partial_y \phi \right] (0, \theta_1)\), and</li>
 <li>\(\partial_r \phi (0, \theta_2) = \left[\partial_r x \partial_x \phi + \partial_r y \partial_y \phi \right] (0, \theta_2)\),</li>
 <li>where \(\theta_1\) and \(\theta_2\) correspond to linearly independent directions.</li>

src_utils.html

@@ -112,8 +112,8 @@
 <h1><a class="anchor" id="src_utils__Utility_tools"></a>
 Utility tools</h1>
 <p>The <a class="el" href="utils__tools_8hpp.html" title="File Describing useful functions.">utils_tools.hpp</a> file contains functions computing the infinity norm. For now, it computes the infinity norm of</p><ul>
-<li>a double: \( \Vert x \Vert_{\infty} = x \);</li>
-<li>a coordinate: \( \Vert x \Vert_{\infty} = \max_{i} (|x_i|) \). </li>
+<li>a double: \(\Vert x \Vert_{\infty} = x\);</li>
+<li>a coordinate: \(\Vert x \Vert_{\infty} = \max_{i} (|x_i|)\). </li>
 </ul>
 </div></div><!-- contents -->
 </div><!-- PageDoc -->