Corrections and improvements to the documentation

README.md

@@ -23,7 +23,7 @@ Key features of APECSS are:
 - Prediction of the formation and attenuation of shock fronts emitted by the bubble.
 - Viscoelastic media (Kelvin-Voigt, Zener, Oldroyd-B).
 - Lipid monolayer coating of the bubble as used for ultrasound contrast agents.
-- APECSS has no external dependencies, aside from the standard _math_ library and some common C headers (math.h, stdio.h, stdlib.h, string.h).
+- APECSS has, aside from the C standard library, no external dependencies.
 
 For more information, please consult the [JOSS paper](https://doi.org/10.21105/joss.05435) discussing the features of APECSS as well as the [PoF paper](https://doi.org/10.1063/5.0131930) introducing the theoretical foundation.
 
@@ -50,7 +50,7 @@ Getting started with APECSS using a Unix operating system, e.g. Linux or MacOS,
 Now, navigate into the folder ````$APECSS_DIR/lib```` and execute ````./compile_lib.sh````. This shell script will compile the APECSS library using _cmake_ with the ````CMakeLists.txt```` file provided in this folder. By default, APECSS is compiled with double precision and in _Release_ mode, meaning all optimization flags are enabled. That's it, you've successfully compiled APECSS!
 
 ### **Installation on Windows 11**
-Installing APECSS on Windows is possible, but a little more involved than the installation on Unix. A step-by-step installation guide on Windows 11, kindly provided by **Maxime Montois**, can be found in the [pdf-documentation](/documentation/APECSS-Documentation.pdf) (see Section 2.2.2). The installation uses `MinGW`, `MSYS2` and `Git Bash` and the instructions also detail small changes to the compile and cmake scripts, as well as the source code, that are required to make APECSS work smoothly on Windows.
+Installing APECSS on Windows is possible, but a little more involved than the installation on Unix. A step-by-step installation guide on Windows 11, kindly provided by Maxime Montois, can be found in the [pdf-documentation](/documentation/APECSS-Documentation.pdf) (see Section 2.2.2). The installation uses `MinGW`, `MSYS2` and `Git Bash` and the instructions also detail small changes to the compile and cmake scripts, as well as the source code, that are required to make APECSS work smoothly on Windows.
 
 ### **Examples**
 There are several ways in which you can use the APECSS library. You can either incorporate selected features of APECSS into your own software or you can program an interface to use APECSS as a standalone program. Some representative examples are given in the [````$APECSS_DIR/examples````](/examples/) directory. Each directory contains the following:

documentation/chapters/about.tex

@@ -10,7 +10,7 @@ \chapter{About APECSS}
 \item Viscoelastic media (Kelvin-Voigt, Zener, Oldroyd-B).
 \item Lipid monolayer coating of the bubble as used for ultrasound contrast agents.
 \item All ODEs are solved with in-built fourth- and fifth-order Runge-Kutta scheme with adaptive time stepping.
-\item APECSS has no external dependencies, aside from the standard {\it math} library and some common {\tt C} headers (math.h, stdio.h, stdlib.h, string.h).
+\item APECSS has, aside from the C standard library, no external dependencies.
 \end{itemize}
 
 The APECSS repository is located at \href{https://github.com/polycfd/apecss}{\texttt{https://github.com/polycfd/apecss}} and structured as:\vspace{-1em}

documentation/chapters/bubble.tex

@@ -2,7 +2,7 @@ \chapter{Bubble dynamics}
 \label{chap:bubble}
 The dynamic behaviour of the bubble is modelled with a Rayleigh-Plesset-type (RP) model, assuming spherical symmetry. This requires to choose a suitable RP-type model (Section \ref{sec:rpmodels}) and define appropriate conditions for the gas  (Section \ref{sec:gas}), the liquid (Section \ref{sec:liquid}), the interface (Section \ref{sec:interface}), as well as at infinity (Section \ref{sec:infinity}). The results that APECSS can write out based on the RP model are explained in Section \ref{sec:bubble_results}.
 
-APECSS solves all ordinary differential equations (ODEs) associated with the bubble dynamics using the embedded RK5(4) scheme of \citet{Dormand1980}, whereby a fifth-order Runge-Kutta scheme is used to solve the ODEs and the corresponding fourth-order Runge-Kutta scheme is used to estimate the solution error. Based on this solution error, the time step $\Delta t$ used to advance the solution of the ODEs is adapted. If the solution error of a newly computed solution in a time step does not satisfy the error tolerance, the solution is rewound and recomputed with a smaller $\Delta t$ (cf. sub-iteration), adapted based on the solution error of the previous attempt. 
+APECSS solves all ordinary differential equations (ODEs) associated with the bubble dynamics using the embedded RK5(4) scheme of \citet{Dormand1980}, whereby a fifth-order Runge-Kutta scheme is used to solve the ODEs and the corresponding fourth-order Runge-Kutta scheme is used to estimate the solution error. Based on this solution error, the time step $\Updelta t$ used to advance the solution of the ODEs is adapted. If the solution error of a newly computed solution in a time step does not satisfy the error tolerance, the solution is rewound and recomputed with a smaller $\Updelta t$ (cf. sub-iteration), adapted based on the solution error of the previous attempt. 
 
 \vspace{0.8em}
 
@@ -19,8 +19,8 @@ \chapter{Bubble dynamics}
 {\tt ODESOLVER} & {\tt RK 7M} & Minimum truncation (7M) coefficients of the RK5(4) scheme of \citet{Dormand1980}. This is the default.\\ 
 & {\tt RK 7S} & Stability optimized (7S) coefficients of the RK5(4) scheme of \citet{Dormand1980}.\\ 
 & {\tt Tolerance <float>} & The desired solution tolerance.\\ 
-& {\tt MinTimeStep <float>} & Minimum time step $\Delta t$.\\ 
-& {\tt MaxTimeStep <float>} & Maximum time step $\Delta t$.\\ 
+& {\tt MinTimeStep <float>} & Minimum time step $\Updelta t$.\\ 
+& {\tt MaxTimeStep <float>} & Maximum time step $\Updelta t$.\\ 
 & {\tt MaxSubIterations <float>} & Maximum number of sub-iterations in a given time step.\\ 
  \hline
 \end{tabular} \vspace{1em}
@@ -66,15 +66,15 @@ \section{Rayleigh-Plesset models}
 \end{equation}
 where $c_{\ell,\mathrm{ref}}$ is the speed of sound of the liquid. Both $\rho_{\ell,\mathrm{ref}}$ and $c_{\ell,\mathrm{ref}}$ are assumed to be constant, limiting the Keller-Miksis model to moderate liquid pressures ($p_\mathrm{L} \lesssim 10^8 \, \mathrm{Pa}$).
 
-Based on the Kirkwood-Bethe hypothesis \citep{Kirkwood1942,Cole1948}, \citet{Gilmore1952} derived a second-order ordinary differential equation describing the radial dynamics of a bubble in a compressible liquid, %given as
+Based on the Kirkwood-Bethe hypothesis \citep{Kirkwood1942,Denner2024a}, \citet{Gilmore1952} derived a second-order ordinary differential equation describing the radial dynamics of a bubble in a compressible liquid, %given as
 \begin{equation}
   \left( 1 - \frac{\dot{R}}{c_\text{L}} \right) R \ddot{R} + \frac{3}{2} \left( 1 - \frac{\dot{R}}{3 c_\text{L}} \right) \dot{R}^2  = \left( 1 + \frac{\dot{R}}{c_\text{L}} \right) H + \left( 1- \frac{\dot{R}}{c_\text{L}} \right) \frac{R \dot{H}}{c_\text{L}}, \label{eq:gilmore}
 \end{equation} 
 where $c_\mathrm{L}$ is the speed of sound of the liquid at the bubble wall, $H = h_\text{L} - h_\infty$ is the enthalpy difference between the bubble wall and infinity, and $\dot{H} = \dot{h}_\text{L} - \dot{h}_\infty$ is the derivative of $H$. The enthalpy $h$ and the speed of sound $c$ are defined by an appropriate equation of state as a function of pressure, with $h_\text{L} = h(p_\text{L})$, $h_\infty = h(p_\infty)$ and $c_\text{L} = c(p_\text{L})$, as detailed in \ref{sec:liquid}. The Gilmore model is also available in a more general formulation,
 \begin{equation}
     \left( 1 - \frac{\dot{R}}{c_{\mathrm{L}}} \right) R \ddot{R} + \frac{3}{4} \alpha \left( 1 - \frac{\dot{R}}{3 c_{\mathrm{L}}} \right) \dot{R}^2 = \frac{\alpha}{2} \left( 1 + \frac{\dot{R}}{c_{\mathrm{L}}} \right) H + \left( 1- \frac{\dot{R}}{c_{\mathrm{L}}} \right) \frac{R \dot{H}}{c_{\mathrm{L}}}, \label{eq:gilmore_general}
 \end{equation}  
-that is applicable to planar ($\alpha=0$), cylindrical ($\alpha=1$) and spherical ($\alpha=2$) bubbles.
+that is applicable to planar ($\alpha=0$), cylindrical ($\alpha=1$) and spherical ($\alpha=2$) bubbles \citep{Denner2024a}.
 
 \section{The gas}
 \label{sec:gas}
@@ -262,19 +262,19 @@ \subsubsection{Zener model}
 
 The question is now how to solve the ODEs for $\varsigma$ and $\tau_{rr}$ in such a way that we always obtain a meaningful result, even if $\lambda_\ell=0$. In order for a customary ODE solver to handle this correctly, we rearrange Eqs.~\eqref{eq:ode_varsigma} and \eqref{eq:ode_tau}. Under the discrete assumption
 \begin{equation}
-    \dot{\varsigma}  = \frac{\varsigma_{n+1}-\varsigma_n}{\Delta t},
+    \dot{\varsigma}  = \frac{\varsigma_{n+1}-\varsigma_n}{\Updelta t},
 \end{equation}
 Eq.~\eqref{eq:ode_varsigma} becomes
 \begin{equation}
-    \lambda_\ell \frac{\varsigma_{n+1}-\varsigma_n}{\Delta t} + \varsigma_{n+1} +\lambda_\ell \frac{\dot{R}}{R} {\tau}_{rr|R} = - \frac{S}{3}
+    \lambda_\ell \frac{\varsigma_{n+1}-\varsigma_n}{\Updelta t} + \varsigma_{n+1} +\lambda_\ell \frac{\dot{R}}{R} {\tau}_{rr|R} = - \frac{S}{3}
   \end{equation}
 so that, after some further manipulation,
 \begin{equation}
-    \varsigma_{n+1} =  \varsigma_n + \Delta t \frac{- \dfrac{S}{3} - \lambda_\ell  \dfrac{\dot{R}}{R} {\tau}_{rr|R,n} - \varsigma_n}{\lambda_\ell + \Delta t}. \label{eq:varsigma_reformulated}
+    \varsigma_{n+1} =  \varsigma_n + \Updelta t \frac{- \dfrac{S}{3} - \lambda_\ell  \dfrac{\dot{R}}{R} {\tau}_{rr|R,n} - \varsigma_n}{\lambda_\ell + \Updelta t}. \label{eq:varsigma_reformulated}
   \end{equation}
 Similarly, Eq.~\eqref{eq:ode_tau} follows as
 \begin{equation}
-   {\tau}_{rr|R,n+1} = {\tau}_{rr|R,n} + \Delta t \frac{-S-{\tau}_{rr|R,n}}{\lambda_\ell + \Delta t}.
+   {\tau}_{rr|R,n+1} = {\tau}_{rr|R,n} + \Updelta t \frac{-S-{\tau}_{rr|R,n}}{\lambda_\ell + \Updelta t}.
    \label{eq:tau_reformulated}
 \end{equation}
 Even in the limit $\lambda_\ell = 0$, we can now obtain a meaningful answer, that is Eq.~\eqref{eq:varsigma_reformulated} reduces to
@@ -298,8 +298,8 @@ \subsubsection{Oldroyd-B model}
 where $\eta_\ell$ is the polymer viscosity.
 These ODEs are reformulated in a similar manner as for the Zener model shown above, to yield
 \begin{align}
-    \mathcal{S}_{1,n+1} &= \mathcal{S}_{1,n} + \Delta t \frac{-\left(4 \lambda_\ell \dfrac{\dot{R}}{R}+1\right) \mathcal{S}_{1,n}- 2 \eta_\ell \dfrac{\dot{R}}{R}}{\lambda_\ell+\Delta t} \label{eq:ode_oldroydB1disc} \\
-    \mathcal{S}_{2,n+1} &= \mathcal{S}_{2,n} + \Delta t \frac{-\left(\lambda_\ell \dfrac{\dot{R}}{R}+1\right) \mathcal{S}_{2,n}- 2 \eta_\ell \dfrac{\dot{R}}{R}}{\lambda_\ell+\Delta t}.\label{eq:ode_oldroydB2disc}
+    \mathcal{S}_{1,n+1} &= \mathcal{S}_{1,n} + \Updelta t \frac{-\left(4 \lambda_\ell \dfrac{\dot{R}}{R}+1\right) \mathcal{S}_{1,n}- 2 \eta_\ell \dfrac{\dot{R}}{R}}{\lambda_\ell+\Updelta t} \label{eq:ode_oldroydB1disc} \\
+    \mathcal{S}_{2,n+1} &= \mathcal{S}_{2,n} + \Updelta t \frac{-\left(\lambda_\ell \dfrac{\dot{R}}{R}+1\right) \mathcal{S}_{2,n}- 2 \eta_\ell \dfrac{\dot{R}}{R}}{\lambda_\ell+\Updelta t}.\label{eq:ode_oldroydB2disc}
 \end{align}
 For $\lambda_\ell = 0$ Eqs.~\eqref{eq:ode_oldroydB1disc} and \eqref{eq:ode_oldroydB2disc} still give a meaningful result and reduce to a Newtonian fluid with $\mathcal{S} = - 4 \eta_\ell \dot{R}/R$.
 
@@ -409,7 +409,7 @@ \section{Results}
 \begin{itemize}[noitemsep]
   \item Time-step number.
   \item Time, $t$.
-  \item Time step, $\Delta t$.
+  \item Time step, $\Updelta t$.
   \item Bubble radius, $R$.
   \item Velocity of the bubble wall, $\dot{R}$.
   \item Pressure of the gas, $p_\mathrm{G}$.

documentation/chapters/emissions.tex

@@ -1,6 +1,6 @@
 \chapter{Acoustic emissions}
 
-Modeling the acoustic emissions is a core feature of APECSS. To this end, APECSS offers different models for the acoustic emissions, assuming an incompressible liquid, a weakly-compressible liquid or a fully compressible liquid. To account for a finite propagation speed, the information associated with an emitted acoustic wave is propagated along the radial coordinate axis using a Lagrangian wave tracking approach. Please refer to the work of \citet{Denner2023} for a detailed explanation and validation of the different emission models. Unless specifically told to do so, APECSS does not compute any acoustic emissions. 
+Modeling the acoustic emissions is a core feature of APECSS. To this end, APECSS offers different models for the acoustic emissions, assuming an incompressible liquid, a weakly-compressible liquid or a fully compressible liquid. To account for a finite propagation speed, the information associated with an emitted acoustic wave is propagated along the radial coordinate axis using a Lagrangian wave tracking approach. Please refer to the work of \citet{Denner2023} for a detailed explanation and validation of the different emission models, and the review of \citet{Denner2024a} for the methodology applied to treat shock waves. Unless specifically told to do so, APECSS does not compute any acoustic emissions. 
 
 \vspace{0.8em}
 
@@ -20,7 +20,7 @@ \chapter{Acoustic emissions}
  \hline
 \end{tabular} \vspace{0.2em}
 
-The floating-point value given as the final argument of the {\tt Emissions} command defines the cut-off distance beyond which the emissions are not computed. For the standard incompressible assumption this value has no meaning, but a value is required as a dummy to facilitate the correct reading of the options. In addition to the emissions of a spherical bubble, the emissions computed based on the Kirkwood-Bethe hypothesis can also be used for cylindrical bubbles and planar cavities. The description of the theory below, however, is limited to the spherical case.
+The floating-point value given as the final argument of the {\tt Emissions} command defines the cut-off distance beyond which the emissions are not computed. For the standard incompressible assumption this value has no meaning, but a value is required as a dummy to facilitate the correct reading of the options. In addition to the emissions of a spherical bubble, the emissions computed based on the Kirkwood-Bethe hypothesis can also be used for cylindrical bubbles and planar cavities \citep{Denner2024a}. The description of the theory below, however, is limited to the spherical case.
 
 \section{Lagrangian wave tracking}
 
@@ -129,7 +129,7 @@ \section{Emissions based on the Kirkwood-Bethe hypothesis}
 \end{eqnarray}
 Since the pressure $p(r,t)$ and the density $\rho(r,t)$ depend explicitly on each other in this formulation, Eq.~(\ref{eq:p_rt_NASG}) has to be solved iteratively. As a convergence criterion for the iterative approximation we use $|p_j(r,t) - p_{j-1}(r,t)| < \eta \, |p_j(r,t)|$, where $j$ denotes the iteration counter and $\eta$ is a predefined tolerance (see option {\tt KBIterTolerance}). Preliminary tests identified a tolerance of $\eta = 10^{-4}$ to be sufficiently small.
 
-Emission nodes with a higher pressure propagate faster than nodes with a lower pressure, which in turn leads to progressive steepening of the acoustic wave. As a result, an emission node may overtake the forerunning emission node, yielding an unphysical multivalued solution. In reality, such a multivalued solution is avoided by the formation of a shock front \citep{Fay1931}. While treating such multivalued solutions is often done in a post-processing step, APECSS deals with multivalued solutions at run time. An emission node that overtakes its forerunning neighbor is discarded, see Fig.~\ref{fig:lagrangiantrackingshock}, and the thermodynamic values of the forerunning neighbor are reevaluated by a simple averaging procedure. Thus, a unique and physically plausible solution is maintained.
+Emission nodes with a higher pressure propagate faster than nodes with a lower pressure, which in turn leads to progressive steepening of the acoustic wave. As a result, an emission node may overtake the forerunning emission node, yielding an unphysical multivalued solution. In reality, such a multivalued solution is avoided by the formation of a shock front \citep{Fay1931}. While treating such multivalued solutions is often done in a post-processing step, APECSS deals with multivalued solutions at run time. An emission node that overtakes its forerunning neighbor is discarded, see Fig.~\ref{fig:lagrangiantrackingshock}, and the thermodynamic values of the forerunning neighbor are reevaluated by a simple averaging procedure, as described in \citep{Denner2024a}. Thus, a unique and physically plausible solution is maintained.
 
 \begin{figure}
     \begin{center}