Merge pull request #2 from polycfd/v1.2

V1.2

Author: polycfd

documentation/APECSS-Documentation.pdf

@@ -106,8 +106,7 @@
 S\"oren Schenke
 \vfill
 
-\thedate\\
-Version 1.1
+\thedate
 
 \end{center}
 \end{titlepage}

documentation/APECSS-Documentation.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:bubbleresults}.
 
-APECSS solves all ordinary differential equations (ODEs) associated with the bubble dynamics sing 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. 
+APECSS solves all ordinary differential equations (ODEs) associated with the bubble dynamics sing 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. 
 
 \vspace{0.8em}
 
@@ -58,7 +58,7 @@ \section{Rayleigh-Plesset models}
 
 The Keller-Miksis model \citep{Keller1980, Prosperetti1986}, which incorporates the compressibility of the liquid to first order, is given as
 \begin{equation}
-\left(1 - \frac{\dot{R}}{c_{\ell,\mathrm{ref}}}\right) R \ddot{R} + \frac{3}{2} \left(1 - \frac{\dot{R}}{3\, c_{\ell,\mathrm{ref}}}\right) \dot{R}^2 =  \left(1 + \frac{\dot{R}}{c_{\ell,\mathrm{ref}}}\right) \frac{p_\text{L} - p_\infty}{\rho_{\ell,\mathrm{ref}}} + \frac{R \, \dot{p}_\text{L}}{\rho_{\ell,\mathrm{ref}} \, c_{\ell,\mathrm{ref}}} ,
+\left(1 - \frac{\dot{R}}{c_{\ell,\mathrm{ref}}}\right) R \ddot{R} + \frac{3}{2} \left(1 - \frac{\dot{R}}{3\, c_{\ell,\mathrm{ref}}}\right) \dot{R}^2 =  \left(1 + \frac{\dot{R}}{c_{\ell,\mathrm{ref}}}\right) \frac{p_\text{L} - p_\infty}{\rho_{\ell,\mathrm{ref}}} + R \, \frac{\dot{p}_\text{L} - \dot{p}_\infty}{\rho_{\ell,\mathrm{ref}} \, c_{\ell,\mathrm{ref}}} ,
 \label{eq:keller}
 \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}$).

documentation/chapters/bubble.tex

@@ -8,17 +8,19 @@ \chapter{Acoustic emissions}
 \begin{tabular}{p{0.1\textwidth} p{0.32\textwidth} p{0.5\textwidth}}
     \textbf{Section} &\textbf{Command} & \textbf{Description} 
 \vspace{1mm} \\ \hline
-{\tt BUBBLE} & {\tt Emissions Incompressible} & Computes the acoustic emissions under the common incompressible assumption.\\ 
-& {\tt Emissions FTI} & Computes the acoustic emissions under the assumption of an incompressible fluid but propagating the emissions with the speed of sound.\\ 
-& {\tt Emissions QA} & Computes the acoustic emissions using the quasi-acoustic model of \citet{Gilmore1952}.\\ 
-& {\tt Emissions EKB} & Computes the acoustic emissions using the explicit Kirkwood-Bethe model.\\ 
-& {\tt Emissions GFC} & Computes the acoustic emissions using the fully-compressible model of \citet{Gilmore1952}.\\ 
-& {\tt Emissions HPE} & Computes the acoustic emissions using the model of \citet{Hickling1963} and \citet{Ebeling1978}.\\ 
+{\tt BUBBLE} & {\tt Emissions IC <float>} & Computes the acoustic emissions under the common incompressible assumption.\\ 
+& {\tt Emissions FTIC <float>} & Computes the acoustic emissions under the assumption of an incompressible fluid but propagating the emissions with the speed of sound.\\ 
+& {\tt Emissions QA <float>} & Computes the acoustic emissions using the quasi-acoustic model of \citet{Gilmore1952}.\\ 
+& {\tt Emissions EV <float>} & Computes the acoustic emissions based on the Kirkwood-Bethe hypothesis, with the explicit expression for velocity.\\ 
+& {\tt Emissions SIV <float>} & Computes the acoustic emissions using the model of \citet{Gilmore1952} based on the Kirkwood-Bethe hypothesis, with the spatially-integrated velocity.\\ 
+& {\tt Emissions TIV <float>} & Computes the acoustic emissions using the model of \citet{Hickling1963} based on the Kirkwood-Bethe hypothesis, with the temporally-integrated velocity.\\ 
 & {\tt EmissionIntegration Euler} & Integrates the radial position and, if applicable, the velocity using an Euler scheme.\\
 & {\tt EmissionIntegration RK4} & Integrates the radial position and, if applicable, the velocity using a conventional fourth-order Runge-Kutta scheme. This is the default.\\
 & {\tt KBIterTolerance <float>} & Tolerance $\eta$ for the evaluation of the pressure using a model based on the Kirkwood-Bethe hypothesis in conjunction with the NASG EoS.\\
  \hline
-\end{tabular} \vspace{1em}
+\end{tabular} \vspace{0.2em}
+
+The floating-point value associated with the emissions defines the cut-off distance beyond which the emissions are not computed. For the incompressible assumption this value has no meaning, but a value is required as a dummy to facilitate the correct reading of the options.
 
 \section{Lagrangian wave tracking}
 
@@ -77,32 +79,30 @@ \section{Quasi-acoustic model}
 \section{Emissions based on the Kirkwood-Bethe hypothesis}
 \label{sec:emissionskb}
 
-Under the Kirkwood-Bethe hypothesis \citep{Kirkwood1942,Cole1948}, the propagation speed along the outgoing characteristic is given as $\mathcal{C}(r,t) = c(r,t) + u(r,t)$. The ODE describing 
-the radial position is, thus, defined as 
+Under the Kirkwood-Bethe hypothesis \citep{Kirkwood1942,Cole1948}, the propagation speed along the outgoing characteristic is given as $\mathcal{C}(r,t) = c(r,t) + u(r,t)$. The ODE describing the radial position is, thus, defined as 
 \begin{equation}
     \frac{\mathrm{d}r(t)}{\mathrm{d}t} = c(r,t) + u(r,t). \label{eq:drdt}
 \end{equation}
-This ODE is numerically integrated using either an Euler scheme or a fourth-order Runge-Kutta (RK4) scheme, with initial condition $r(\tau) = R(\tau)$, where  $\tau$ is the time at which the acoustic information is emitted at the bubble wall. The time-step $\Delta t$ is taken to be the same as used for the integration of the model describing the bubble dynamics (see Section \ref{chap:bubble}).
+This ODE is numerically integrated using either an Euler scheme or a fourth-order Runge-Kutta (RK4) scheme, with initial condition $r(t) = R(\tau)$ for $t=\tau$, where $\tau$ is the time at which the acoustic information is emitted at the bubble wall. The time-step $\Delta t$ is taken to be the same as used for the integration of the model describing the bubble dynamics (see Section \ref{chap:bubble}).
 
-Three models to compute the velocity $u(r,t)$ at a given emission node are available in APECSS: (i) an explicit expression for $u(r,t)$, (ii) integrating the spatial derivative of the velocity, $\mathrm{d}u(r,t)/\mathrm{d}r$, along the outgoing characteristic, as proposed by \citet{Gilmore1952}, and (iii) integrating the temporal derivative of the velocity, $\mathrm{d}u(r,t)/\mathrm{d}t$, along the outgoing characteristic, as proposed by \citet{Hickling1963}.
-The assumptions used to derive these models for the acoustic emissions are consistent with the Gilmore model, Eq.~\eqref{eq:gilmore}.
+Three models to compute the velocity $u(r,t)$ at a given emission node are available in APECSS: (i) an explicit expression for $u(r,t)$, (ii) integrating the spatial derivative of the velocity, $\mathrm{d}u(r,t)/\mathrm{d}r$, along the outgoing characteristic, as proposed by \citet{Gilmore1952}, and (iii) integrating the temporal derivative of the velocity, $\mathrm{d}u(r,t)/\mathrm{d}t$, along the outgoing characteristic, as proposed by \citet{Hickling1963}. The assumptions used to derive these models for the acoustic emissions are consistent with the Gilmore model, Eq.~\eqref{eq:gilmore}.
 
-Following a similar derivation as for the quasi-acoustic model discussed in Section \ref{sec:emissionsqa}, but assuming a fully-compressible liquid described by a suitable equation of state, the velocity is given by the {\it explicit Kirkwood-Bethe (EKB)} model as
+Following a similar derivation as for the quasi-acoustic model discussed in Section \ref{sec:emissionsqa}, but assuming a fully-compressible liquid described by a suitable equation of state, the {\it explicit velocity (EV)} is given as
 \begin{equation}
     u(r,t) = \frac{f(\tau)}{r(t)^2} + \frac{g(\tau)}{r(t) \, [c(r,t) + u(r,t)]} . \label{eq:u_rt}
 \end{equation}
 For $t=\tau$ with $r(t)=R(\tau)$, this expression reduces to $u(R,\tau)=\dot{R}(\tau)$, thus satisfying the boundary conditions at the bubble wall.
-\citet{Gilmore1952} proposed instead to solve for the spatial derivative of the velocity along the outgoing characteristic, in APECSS referred to as {\it Gilmore's fully compressible (GFC)} model, with the velocity defined by 
+\citet{Gilmore1952} proposed instead to solve for the spatial derivative of the velocity along the outgoing characteristic, in APECSS referred to as {\it spatially-integrated velocity (SIV)}, defined as 
 \begin{equation}
     \frac{\mathrm{d}u(r,t)}{\mathrm{d}r} = - \frac{2 u(r,t)}{r(t)} \left[1+\frac{u(r,t)^2}{c(r,t)^2-u(r,t)^2} \right] + \frac{g(\tau)}{r(t)^2 [c(r,t)-u(r,t)]} \label{eq:dudr_rt}.
 \end{equation}
-Alternatively, \citet{Hickling1963} proposed to integrate the velocity with respect to time, in APECSS referred to as {\it Hickling-Plesset-Ebeling (HPE)} model, with the temporal derivative of the velocity along the outgoing characteristic given as
+Alternatively, \citet{Hickling1963} proposed to integrate the velocity with respect to time, in APECSS referred to as {\it temporally-integrated velocity (TIV)}, with the temporal derivative of the velocity along the outgoing characteristic given as
 \begin{equation}
     \frac{\mathrm{d}u(r,t)}{\mathrm{d}t} =  - \frac{2 c(r,t)^2 u(r,t)}{r(t) \, [c(r,t)-u(r,t)]} + \frac{g(\tau)}{r(t)^2} \, \frac{c(r,t)+u(r,t)}{c(r,t)-u(r,t)}. \label{eq:dudt_rt}
 \end{equation}
-If either Eq.~\eqref{eq:dudr_rt} or Eq.~\eqref{eq:dudt_rt} is chosen to determine the velocity, this differential equation for velocity is integrated together with the equation for ${\mathrm{d}r(t)/\mathrm{d}t}$, Eq.~\eqref{eq:drdt}, using the initial condition $u(R,\tau) = \dot{R}(\tau)$. Note that with $\mathrm{d}r(t)/\mathrm{t}$ defined by Eq.~\eqref{eq:drdt} and $g(\tau)$ given by Eq.~\eqref{eq:g_R}, Eqs.~\eqref{eq:dudr_rt} and \eqref{eq:dudt_rt} are interchangeable by the relation ${\mathrm{d}u/\mathrm{d}t} = ({\mathrm{d}u/\mathrm{d}r}) \, ({\mathrm{d}r/\mathrm{d}t})$. 
+If either Eq.~\eqref{eq:dudr_rt} or Eq.~\eqref{eq:dudt_rt} is chosen to determine the velocity, this differential equation for the velocity is integrated together with the equation for ${\mathrm{d}r(t)/\mathrm{d}t}$, Eq.~\eqref{eq:drdt}, using the initial condition $u(R,\tau) = \dot{R}(\tau)$. Note that with $\mathrm{d}r(t)/\mathrm{t}$ defined by Eq.~\eqref{eq:drdt} and $g(\tau)$ given by Eq.~\eqref{eq:g_R}, Eqs.~\eqref{eq:dudr_rt} and \eqref{eq:dudt_rt} are interchangeable by the relation ${\mathrm{d}u/\mathrm{d}t} = ({\mathrm{d}u/\mathrm{d}r}) \, ({\mathrm{d}r/\mathrm{d}t})$. 
 
-Regardless of the choice of velocity model, the invariants $f(\tau)$ and $g(\tau)$ are defined as
+Regardless of the choice of velocity model, $f(\tau)$ and $g(\tau)$ are defined as
 \begin{align}
     f(\tau) &= R(\tau)^2 \dot{R}(\tau) - \frac{R(\tau) \, g(\tau)}{c_\mathrm{L}(\tau) + \dot{R}(\tau)}   \label{eq:f_R} \\  
     g(\tau) &= R(\tau) \left[h_\mathrm{L}(\tau) - h_\infty(\tau) + \frac{\dot{R}(\tau)^2}{2} \right]
@@ -112,8 +112,7 @@ \section{Emissions based on the Kirkwood-Bethe hypothesis}
 \begin{equation}
     h(r,t) = h_\infty(t) + \frac{g(\tau)}{r(t)} - \frac{u(r,t)^2}{2}, \label{eq:h_rt}
 \end{equation}
-where $h_\infty$ is spatially invariant and only depends on time.
-For $t=\tau$ with $r(t)=R(\tau)$, this expression for enthalpy reduces to $h(R,\tau)=h_\mathrm{L}(\tau)$, satisfying the boundary conditions at the bubble wall. 
+where $h_\infty$ is spatially invariant and only depends on time. For $t=\tau$ with $r(t)=R(\tau)$, this expression for enthalpy reduces to $h(R,\tau)=h_\mathrm{L}(\tau)$, satisfying the boundary conditions at the bubble wall. 
 
 Using the Tait EoS, the pressure can be readily computed from the enthalpy defined in Eq.~(\ref{eq:h_rt}) by inserting Eq.~(\ref{eq:rho_Tait}) into Eq.~(\ref{eq:h_Tait}) and rearranging to yield
 \begin{equation}
@@ -125,7 +124,6 @@ \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 on-the-fly. \citet{Rudnick1952} postulated that the rate of attenuation of a stable shock front is independent of the dissipation process leading to the stable shock front. Exploiting Rudnick's argument, an emission node that overtakes its forerunning neighbor is simply discarded in APECSS, see Fig.~\ref{fig:lagrangiantrackingshock}, thus maintaining a physically plausible solution.
 
 \begin{figure}

documentation/chapters/emissions.tex

@@ -11,6 +11,16 @@ \section{Installation}
 
 Now, navigate into the folder {\tt \$APECSS\_DIR/lib} and execute {\tt ./compile\_lib.sh}. This shell script will compile the APECSS library using {\tt cmake} with the {\tt CMakeLists.txt} file provided in this folder. By default, APECSS is compiled with double precision and in \textit{Release} mode, meaning all optimization flags are enabled. That's it, you've successfully installed APECSS!
 
+If you wish to install APECSS with \textit{Debug} flags, simply change the line
+\begin{lstlisting}[style=CStyle,numbers=none]
+  cmake CMakeLists.txt -DCMAKE_BUILD_TYPE=Release
+\end{lstlisting}\vspace{-0.75em}
+to
+\begin{lstlisting}[style=CStyle,numbers=none]
+  cmake CMakeLists.txt -DCMAKE_BUILD_TYPE=Debug
+\end{lstlisting}\vspace{-0.75em}
+in the {\tt ./compile\_lib.sh} shell script and, if applicable, in the shell script that compiles the desired example.
+
 \section{Running APECSS}
 
 There are several ways in which you can use the APECSS library. You can either incorporate selected features of APECSS into your own software code or you can program an interface to use APECSS as a standalone software tool. 
@@ -163,9 +173,9 @@ \subsubsection{Flags for model options}
   \item {\tt APECSS\_EMISSION\_FINITE\_TIME\_INCOMPRESSIBLE}: Emissions are assumed to occur in an incompressible fluid, but the finite propagation speed given by the speed of sound is taken into account.
   \item {\tt APECSS\_EMISSION\_QUASIACOUSTIC}: Emissions are modelled under the quasi-acoustic assumption of \citet{Trilling1952} and \citet{Gilmore1952}.
   \item {\tt APECSS\_EMISSION\_KIRKWOODBETHE}: A model based on the Kirkwood-Bethe hypothesis (EKB, GFC, HPE) is used.
-  \item {\tt APECSS\_EMISSION\_EKB}: Emissions are modelled using the explicit Kirkwood-Bethe (EKB) model.
-  \item {\tt APECSS\_EMISSION\_GFC}: Emissions are modelled using the fully-compressible model of \citet{Gilmore1952} (GFC).
-  \item {\tt APECSS\_EMISSION\_HPE}: Emissions are modelled using the model of \citet{Hickling1963} and \citet{Ebeling1978} (HPE).
+  \item {\tt APECSS\_EMISSION\_EV}: Emissions are modelled using the explicit expression based on the Kirkwood-Bethe hypothesis.
+  \item {\tt APECSS\_EMISSION\_SIV}: Emissions are modelled using the spatially-integrated velocity, based on the Kirkwood-Bethe hypothesis, of \citet{Gilmore1952}.
+  \item {\tt APECSS\_EMISSION\_TIV}: Emissions are modelled using the temporally-integrated velocity, based on the Kirkwood-Bethe hypothesis, of \citet{Hickling1963}.
 \end{itemize}
 
 
@@ -269,6 +279,40 @@ \subsection{Important functions}
 \end{lstlisting}\vspace{-0.75em}
 A solver run is ended with the function {\tt apecss\_bubble\_solver\_finalize()} where, for instance, the arrays and linked list of the acoustic emissions are freed.
 
+\subsection{The void data pointer}
+
+Additional data associated with a bubble, an emission node, a gas, a liquid or an interface might be needed for more complex simulations, for instance neighbor information when multiple bubbles interact with each other or the thermal conductivity and heat capacity of the gas inside the bubble when heat transfer is considered. In APECSS, to retain flexibility and avoid unnecessary overhead, the structures {\tt struct APECSS\_Bubble}, {\tt struct APECSS\_EmissionNode}, {\tt struct APECSS\_Gas}, {\tt struct APECSS\_Liquid} and {\tt struct APECSS\_Interface} contain a \texttt{void} pointer called \texttt{user\_data} specifically for the purpose of associating additional data with those structures. This void pointer is not associated with a specific data type, but rather points to some memory location, i.e.~a memory address. 
+
+A typical use of this void pointer would be to generate a structure that contains all additional data and point the void pointer to the address of this structure. For instance, the void pointer of the bubble structure is used in such a way in the example {\tt \$APECSS\_DIR/examples/laserinducedcavitation}. The structure
+\begin{lstlisting}[style=CStyle,numbers=none]
+  struct LIC
+  {
+    APECSS_FLOAT tauL, Rnbd, Rnc1, Rnc2, tmax1, tmax2;
+  };
+\end{lstlisting}\vspace{-0.75em}
+is allocated
+\begin{lstlisting}[style=CStyle,numbers=none]
+  struct LIC *lic_data = (struct LIC *) malloc(sizeof(struct LIC));
+\end{lstlisting}\vspace{-0.75em}
+and associated with the void pointer
+\begin{lstlisting}[style=CStyle,numbers=none]
+  Bubble->user_data = lic_data;
+\end{lstlisting}\vspace{-0.75em}
+The data stored in this structure can then be used or read by again assigning the correct data type
+\begin{lstlisting}[style=CStyle,numbers=none]
+  struct LIC *lic_data = Bubble->user_data;
+\end{lstlisting}\vspace{-0.75em}
+and used as
+\begin{lstlisting}[style=CStyle,numbers=none]
+  tmax = lic_data->tmax1;
+\end{lstlisting}\vspace{-0.75em}
+At the end of the simulation, when the data is no longer needed, the memory occupied by the structure is freed
+\begin{lstlisting}[style=CStyle,numbers=none]
+  free(lic_data);
+\end{lstlisting}%\vspace{-0.75em}
+
+The example {\tt \$APECSS\_DIR/examples/gastemperature} uses both the void pointers associated with the bubble and the gas.
+
 \subsection{A word on function pointers}
 
 APECSS uses function pointers extensively. Function pointers are an elegant means in {\tt C} to add complexity and functionality yet still retain a slim code, avoid redundant code and, if nothing else, avoid a large number of costly conditional statements. However, function pointers can quickly make a code unreadable and obfuscate what is actually happening, if they are used without care. In order to keep the use of function pointers in APECSS transparent, the adopted convention is that \uline{all} function pointers are set in {\tt apecss\_*\_processoptions()} functions, e.g.~{\tt apecss\_gas\_processoptions()}.