Refine application documentation for clarity and consistency across multiple sections, including updates to the framework, specifications, and demonstrators. Enhance descriptions of methodologies, benchmarks, and I/O operations to improve readability and understanding.

Author: prudhomm

chapters/applications/framework.tex

@@ -7,8 +7,7 @@ \section{Application Frameworks \& Best Practices}
 High‑performance Exa‑MA applications—mini‑apps through demonstrators—follow a unified framework to ensure reproducibility, portability, and maintainability, with minimal templates and CI hooks to apply the same conventions everywhere.
 
 \subsection{Repository Layout}
-A common structure makes code, tests, and artifacts predictable across projects and easy to navigate.
-All repositories conform to:
+A common structure makes code, tests, and artifacts predictable; repositories conform to:
 \begin{verbatim}
 src/                 % core code
 tests/               % unit, regression, convergence tests
@@ -27,15 +26,15 @@ \subsection{Environment Management}
 \end{itemize}
 
 \subsection{CI/CD Pipelines}
-Automated workflows standardize building, testing, and benchmarking, and leverage shared actions across repositories.
+Automated workflows standardize build, test, and benchmark; shared actions keep repositories consistent.
 \begin{itemize}
   \item Define workflows for \texttt{build}, \texttt{test}, \texttt{benchmark}, \texttt{lint}.
   \item Reuse WP7 shared actions via \texttt{uses: numpex/wp7-actions/...}.
-  \item On merge to \texttt{develop} and nightly, run full benchmark suite and push metrics to Grafana.
+  \item On merges and nightly runs, execute the full benchmark suite and push metrics to Grafana.
 \end{itemize}
 
 \subsection{Containerization \& Packaging}
-Container images and versioning conventions provide reproducible execution on laptops and supercomputers alike.
+Container images and versioning conventions ensure reproducible execution locally and on supercomputers.
 \begin{itemize}
   \item Multi-stage Dockerfiles / Apptainer recipes in \texttt{containers/}.
   \item Base images tagged \texttt{<proj>-v<semver>-<date>}.
@@ -57,4 +56,4 @@ \subsection{Best Practices}
   \item Automate benchmarks on PRs (smoke) and nightly (full).
   \item Tag releases via GitHub Releases, include PDF report and container digests.
   \item Link all artifacts (code, containers, datasets) via DOIs for traceability.
-\end{itemize}
+\end{itemize}

chapters/applications/intro.tex

@@ -6,22 +6,21 @@ \section{Introduction \& Scope}
 
 Work Package 7 (WP7) provides the “glue” for Exa-MA, delivering the CI/CD framework, containerized environments, packaging standards, benchmarking suite, training materials, and automated deployment pipelines that bind together the methodological developments from WP1-WP6 into reproducible, high-performance demonstrators on supercomputers.
 
-This section defines the types of applications within Exa-MA and lays out their purpose, goals, and a classification scheme that keeps mini‑apps, extended mini‑apps, demonstrators, and proxy‑apps consistent and tied to measurable outcomes under WP7’s shared framework and CI.
+This section defines application categories and their role within WP7’s shared framework and CI, keeping mini‑apps, extended mini‑apps, demonstrators, and proxy‑apps consistent and tied to measurable outcomes.
 
 \subsection{Purpose \& Goals}
-We align expectations across WPs by clarifying objectives, shared metrics, and delivery milestones for specifications, prototypes, and benchmarks.
+We align expectations across WPs by clarifying objectives, shared metrics, and delivery milestones:
 \begin{itemize}
-  \item Align application research scope for WP1-WP6 with project KPIs.
+  \item Align scope across WP1–WP6 with project KPIs.
   \item Agree on key performance metrics and measurement methods.
-  \item Confirm timelines for specification delivery, prototype runs, and benchmarking in D7.1 v2.
+  \item Confirm timelines for specs, prototypes, and D7.1 v2 benchmarking.
 \end{itemize}
 
 \subsection{Types of Applications}
-Each category comes with a clear scope, intended level of realism, and role in benchmarking and integration across the project.
-To ensure coherence across use-cases and scalability targets, Exa-MA classifies applications into four categories:
+We classify applications into four categories to align scope with benchmarking and integration across the project:
 \begin{description}
   \item[Mini-App:] A focused test of a single method or kernel (e.g., FEEL++ mesh operation).
   \item[Extended Mini-App:] Mini-App plus supporting scripts (I/O stress tests, data generation).
   \item[Demonstrator:] Integrated workflow spanning multiple WPs to showcase a real-world scientific scenario.
   \item[Proxy-App:] Representative workload combining three or more WPs to emulate full-stack exascale behavior.
-\end{description}
+\end{description}

chapters/applications/specs.tex

@@ -24,7 +24,7 @@ \subsection{Scientific Purpose \& Methods}
 \end{itemize}
 
 \subsection{Technical Metadata}
-The software and parallel stack document portability and scaling characteristics.
+The software and parallel stack capture portability and scaling characteristics.
 \begin{itemize}
   \item \texttt{framework}: Software framework (FEEL++, MFEM, PyTorch…).  
   \item \texttt{parallel\_framework}: MPI, OpenMP, CUDA, Kokkos.  
@@ -107,4 +107,4 @@ \subsection{Planning \& Documentation}
   \item \texttt{spec\_due}, \texttt{proto\_due}: Dates for spec and prototype.  
   \item \texttt{repo\_url}, \texttt{tex\_url}: Links to code and docs.  
   \item \texttt{notes}: Coordination remarks.
-\end{itemize}
+\end{itemize}

chapters/applications/specs/app-feelpp-discr-1.tex

@@ -3,8 +3,7 @@
 \section{Demonstrator: Elliptic linear PDE: CG}
 \label{sec:app:specs:app-feelpp-discr-1}
 
-We present here the demonstrator to numerically solve elliptic linear PDE using continuous Galerkin approach.
-Precisely, we solve here the heat transfer equation.
+This demonstrator solves an elliptic linear PDE (heat equation) using a continuous Galerkin approach.
 
 \Cref{tab:app-feelpp-discr-1} describes the specifications of the application.
 
@@ -60,10 +59,9 @@ \subsection{Description of the benchmark}
 The standard is intended to ensure that thermal bridges' simulation are accurately computed.
 It provides reference values and tolerance on heat temperature and heat flux at several locations of the geometry.
 
-At the mathematical level, this application requires finding the numerical
-solution of an elliptic linear PDE, namely the heat equation.
-We employ a finite element method based on continuous Lagrange Finite Element of order 1,2 and 3 (denoted by $\mathP_1$, $\mathP_2$, $\mathP_3$),
-and we analyze the execution time of the main components of the simulation.
+At the mathematical level, we solve an elliptic linear PDE (the heat equation).
+We employ continuous Lagrange finite elements of order 1, 2, and 3 ($\mathP_1$, $\mathP_2$, $\mathP_3$)
+and analyze the execution time of the main components of the simulation.
 
 \Cref{fig:spec:app-feelpp-discr-1:thermal_bridges:geometry} represents the geometry
 of this benchmark and the domain decomposition by material.% the 3D temperature field solution, and an example of mesh partitioning.
@@ -421,4 +419,3 @@ \subsubsection{Scalability on I/O}
 \end{itemize}
 
 These I/O characteristics are typical for large-scale finite element simulations and inform best practices for configuring output frequencies in production simulations.
-

chapters/applications/specs/app-feelpp-discr-2.tex

@@ -3,7 +3,7 @@
 \section{Demonstrator: FDA nozzle (incompressible Navier--Stokes)}
 \label{sec:app:specs:app-feelpp-discr-2}
 
-We present here the demonstrator to numerically solve the incompressible Navier--Stokes equations using stabilized finite element methods for the \emph{FDA medical device nozzle benchmark}. This benchmark, proposed by the US Food and Drug Administration, is widely used to assess stability, accuracy, and robustness of CFD solvers for biomedical applications \cite{hariharan_multilaboratory_2011,stewart_assessment_2012}. The specifications follow a similar structure to the elliptic PDE demonstrator in \Cref{sec:app:specs:app-feelpp-discr-1}, adapted to fluid dynamics. We use the \Feelpp fluid toolbox.
+This demonstrator solves the incompressible Navier--Stokes equations for the \emph{FDA medical device nozzle} using stabilized finite element methods (PSPG/SUPG). The benchmark, proposed by the US Food and Drug Administration, is widely used to assess stability, accuracy, and robustness of CFD solvers \cite{hariharan_multilaboratory_2011,stewart_assessment_2012}. The specifications mirror the elliptic PDE demonstrator in \Cref{sec:app:specs:app-feelpp-discr-1}, adapted to fluid dynamics, and use the \Feelpp fluid toolbox.
 
 \Cref{tab:app-feelpp-discr-2} describes the specifications of the application.
 
@@ -51,7 +51,7 @@ \subsection{Description of the benchmark}
 
 The benchmark presented here, denoted by \emph{FDA nozzle benchmark}, was proposed by the US Food and Drug Administration (FDA) in \cite{hariharan_multilaboratory_2011} to assess the stability, accuracy and robustness of computational fluid dynamics methods for biomedical device applications. The benchmark has become a standard validation case for incompressible flow solvers.
 
-The geometry consists of an idealized medical device nozzle with a sudden contraction followed by a gradual expansion, as shown in \Cref{fig:spec:app-feelpp-discr-2:fda:geometry}. The benchmark tests the solver's ability to capture:
+The geometry consists of an idealized medical device nozzle with a sudden contraction followed by a gradual expansion (\Cref{fig:spec:app-feelpp-discr-2:fda:geometry}). The benchmark tests the solver's ability to capture:
 \begin{itemize}
 \item Laminar to transitional flow regimes (Reynolds numbers from 500 to 6500)
 \item Flow acceleration through the nozzle throat
@@ -103,7 +103,8 @@ \subsection{Input/Output Dataset Description}
 
 \subsubsection{Input Data:}
   \begin{itemize}
-  \item \textbf{Meshes:} We have generated three levels of mesh refinement called \texttt{M1}, \texttt{M2}, and \texttt{M3} for the FDA nozzle geometry. These meshes are stored in GMSH format. The statistics are presented in \Cref{tab:spec:app-feelpp-discr-2:fda:discr_stat}. Pre-partitioned meshes are also available in the \Feelpp in-house format (JSON+HDF5) for parallel simulations. All meshes are available in the \Feelpp Girder database.
+  \item \textbf{Meshes:} We  generat three levels of mesh refinement called \texttt{M1}, \texttt{M2}, \texttt{M3} and possibly more for the FDA nozzle geometry. 
+  These meshes are stored in GMSH format. The statistics are presented in \Cref{tab:spec:app-feelpp-discr-2:fda:discr_stat}. Pre-partitioned meshes are also available in the \Feelpp in-house format (JSON+HDF5) for parallel simulations. All meshes are available in the \Feelpp Girder database.
 
   \item \textbf{Flow parameters:} The benchmark is run for multiple Reynolds numbers: Re = 500 (steady laminar), Re = 2000 (steady transitional), Re = 3500 (transitional), and Re = 6500 (transitional/turbulent). Fluid properties: density $\rho = 1056$ kg/m³ (blood analog), dynamic viscosity $\mu = 0.00345$ Pa·s.
 
@@ -153,81 +154,8 @@ \subsubsection{Output Data:}
 \end{itemize}
 
 
+\textbf{Status:} \texttt{benchmark-ready} - validated and ready for systematic HPC benchmarking.
 
 
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\subsection{Results summary}
-
-The FDA nozzle benchmark has been executed on high-performance computing systems for the three mesh refinement levels and multiple Reynolds numbers. The results demonstrate the accuracy of the stabilized finite element method for incompressible flow and the scalability of the parallel implementation.
-
-\subsubsection{Numerical solution}
-
-The computed flow fields exhibit the expected physics of flow through a sudden contraction-expansion geometry. Key flow features captured by the simulation include:
-
-\begin{itemize}
-\item \textbf{Jet formation:} As the flow accelerates through the throat, a high-velocity jet forms with peak velocities reaching 2-3 times the mean inlet velocity for higher Reynolds numbers.
-
-\item \textbf{Recirculation zones:} In the expansion region, flow separation creates recirculation zones along the walls. The size and intensity of these zones increase with Reynolds number, consistent with experimental observations.
-
-\item \textbf{Jet breakdown:} For Re $\geq$ 3500, the central jet becomes unstable and breaks down into smaller-scale structures downstream. The breakdown location moves upstream as Reynolds number increases.
-
-\item \textbf{Pressure recovery:} The pressure distribution shows the expected drop through the contraction followed by gradual recovery in the expansion region. The pressure gradient drives the recirculating flow near the walls.
-\end{itemize}
-
-Visualization of the velocity magnitude and streamlines reveals the complex 3D flow structure, including asymmetric features that emerge at higher Reynolds numbers. The mesh partitioning strategy ensures good load balancing across processors for efficient parallel computation.
-
-\subsubsection{Validation against FDA reference data}
-
-Quantitative comparison with FDA experimental measurements demonstrates good agreement:
-
-\begin{itemize}
-\item \textbf{Axial velocity profiles:} The computed centerline and cross-sectional velocity profiles match the experimental data within measurement uncertainty for all Reynolds numbers. The jet width and peak velocity location are accurately captured.
-
-\item \textbf{Pressure drop:} The total pressure drop from inlet to outlet agrees with measurements to within 5\% for laminar cases (Re = 500, 2000) and within 10\% for transitional cases (Re = 3500, 6500).
-
-\item \textbf{Recirculation metrics:} The length of the primary recirculation zone and reattachment point location match experimental observations. Secondary recirculation zones observed in experiments are also captured by the simulations.
-
-\item \textbf{Mesh convergence:} Refinement from M1 to M3 demonstrates mesh convergence for all validation metrics. The differences between M2 and M3 results are less than 2\%, indicating mesh-independent solutions are achieved.
-\end{itemize}
-
-The \texttt{benchmark-verification} metric follows the FDA assessment criteria and reporting conventions \cite{stewart_assessment_2012}.
-
-\subsection{Performance analysis}
-
-\subsubsection{Execution time breakdown}
-
-The performance analysis reveals the computational cost distribution for the Navier-Stokes solver:
-
-\begin{itemize}
-\item \textbf{Initialization (5-10\%):} Mesh loading and finite element space construction scale well with processor count. The initialization cost is amortized over the simulation time for transient cases.
-
-\item \textbf{Assembly (20-30\%):} The non-linear assembly of the Navier-Stokes residual and Jacobian dominates for low Reynolds numbers where Newton convergence is rapid. The stabilization terms (PSPG/SUPG) add modest overhead.
-
-\item \textbf{Linear solve (50-70\%):} The preconditioned GMRES iterations consume the majority of time, especially at high Reynolds numbers where more linear iterations are required per Newton step. Block preconditioners for the velocity-pressure coupling are essential for performance.
-
-\item \textbf{Post-processing (5-10\%):} Export and validation measure computation time grows with mesh size but remains a small fraction of total cost.
-\end{itemize}
-
-\subsubsection{Strong scalability}
-
-Strong scaling tests with fixed problem size (M2 and M3 meshes) demonstrate:
-\begin{itemize}
-\item Near-ideal speedup up to 64-96 processors for all Reynolds numbers
-\item Parallel efficiency above 80\% for processor counts up to 128
-\item Communication overhead becomes significant beyond 256 processors for M2 mesh (diminishing returns)
-\item Linear solver shows good scaling due to effective domain decomposition preconditioning
-\end{itemize}
-
-\subsubsection{Weak scalability}
-
-Weak scaling tests with proportional mesh refinement show:
-\begin{itemize}
-\item Constant execution time per processor up to 512 processors
-\item Slightly increasing time for larger processor counts due to increased surface-to-volume ratio in domain decomposition
-\item Assembly phase maintains excellent weak scaling throughout the range
-\item Linear solver shows more sensitivity to processor count, typical of iterative methods
-\end{itemize}
-
-The \texttt{strong-scalability} and \texttt{weak-scalability} metrics confirm that the parallel implementation is suitable for large-scale CFD simulations on modern HPC systems.
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%