v1.0

Author: fabiandenner

README.md

@@ -34,7 +34,7 @@ Getting started with APECSS is easy. After downloading APECSS in the directory `
 - ````APECSS_DIR```` to the directory in which APECSS is located. Using bash, for instance, simply execute the command ````export APECSS_DIR=<path to APECSS>```` or, even better, add this command to your bash profile.
 - ````USRLIB_DIR```` to the directory in which libm.a or libm.dylib (the standard _math_ library) is located. This may, for instance, be ````/usr/lib64/```` on Linux systems or ````/usr/lib/```` on MacOS systems.
 
-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 succesfully compiled APECSS!
+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!
 
 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```` directory. Each directory contains the following:
 - A ````README.md```` file explaining the purpose and specificities of this/these example(s).

documentation/APECSS-Documentation.pdf

@@ -86,11 +86,11 @@ \section{The gas}
 & {\tt PolytropicExponent <float>} & Polytropic exponent $\Gamma_\text{g}$.\\
 & {\tt ReferencePressure <float>} & Reference pressure $p_\text{g,ref}$.\\
 & {\tt ReferenceDensity <float>} & Reference density $\rho_\text{g,ref}$.\\
-& {\tt HardcoreRadius <float>} & Hardcore radius $r_\text{hc}$.\\
 & {\tt CoVolume <float>} & Co-volume $b_\text{g}$.\\
 & {\tt TaitPressureConst <float>} & Pressure constant $B_\text{g}$.\\
-& {\tt MolecularWeight <float>} & Molecular weight $\mathcal{M}_{\text{g}}$ of the gas. \\
-& {\tt MolecularDiameter <float>} & Molecular kinematic diameter $\mathcal{D}_{\text{g}}$ of the gas. \\
+& {\tt MolecularWeight <float>} & Molecular weight $\mathcal{M}_{\text{g}}$ of the gas.\\
+& {\tt MolecularDiameter <float>} & Molecular kinematic diameter $\mathcal{D}_{\text{g}}$ of the gas.\\
+{\tt BUBBLE} & {\tt HardcoreRadius <float>} & Hardcore radius $r_\text{hc}$.\\
  \hline
 \end{tabular} \vspace{1em}
 

documentation/chapters/bubble.tex

@@ -192,38 +192,70 @@ \subsection{Structures}
 
 \subsection{Important functions}
 
-Here we briefly outline how to use some of the key functions of APECSS. 
-
 Whenever using APECSS, at least one {\tt APECSS\_Bubble} structure has to be available and, if multiple bubbles are part of a simulation, each bubble has to be represented by a separate {\tt APECSS\_Bubble} structure. A single {\tt APECSS\_Bubble} structure is allocated and initialized as follows:
-\begin{lstlisting}[style=CStyle]
+\begin{lstlisting}[style=CStyle,numbers=none]
   struct APECSS_Bubble *Bubble = (struct APECSS_Bubble *) malloc(sizeof(struct APECSS_Bubble));
   apecss_bubble_initializestruct(Bubble);
 \end{lstlisting}\vspace{-0.75em}
 The function {\tt apecss\_bubble\_initializestruct()} ensures that all pointers (to arrays, other structures and functions) that are part of the {\tt APECSS\_Bubble} structure are initialized to {\tt NULL}. This is important because the processing of options and any checks for allocation depend on {\tt NULL} to indicate that a given pointer in not yet allocated or not in use.
-
-Once a {\tt APECSS\_Bubble} structure is allocated and initialize, default values ought to be set, the {\tt *.apecss} options file is to be read and the chosen options have to be processed. In the standalone examples found in {\tt \$APECSS\_DIR/examples} this is done with the falling function calls:
-\begin{lstlisting}[style=CStyle]
-  apecss_options_setdefault(Bubble);
-  char OptionsDir[APECSS_STRINGLENGTH];
-  sprintf(OptionsDir, "./run.apecss"); // Relative path to the options file.
-  apecss_options_readfile(Bubble, OptionsDir);
-  apecss_options_process(Bubble);
+Then, we wish to set default values for the bubble parameters and read the relevant options from the options file:
+\begin{lstlisting}[style=CStyle,numbers=none]
+  apecss_bubble_setdefaultoptions(Bubble);
+  apecss_bubble_readoptions(Bubble, OptionsDir);
+\end{lstlisting}\vspace{-0.75em}
+While setting default values is strongly advised, it is optional. The relative path to the options file may be set as
+\begin{lstlisting}[style=CStyle,numbers=none]
+char OptionsDir[APECSS_STRINGLENGTH];
+sprintf(OptionsDir, "./run.apecss"); // Relative path to the options file.
+\end{lstlisting}
+
+In general, the properties of a gas ({\tt struct APECSS\_Gas}), a liquid ({\tt struct APECSS\_Liquid}) and a gas-liquid interface ({\tt struct APECSS\_Interface}), as well as the parameters for the ODE solver ({\tt struct APECSS\_NumericsODE}), have to be associated with a bubble, through the structure pointers {\tt *Gas}, {\tt *Liquid}, {\tt *Interface} and {\tt *NumericsODE} readily available in the {\tt APECSS\_Bubble} structure. In a single-bubble simulation this is obviously straightforward, we have one gas, one liquid and one interface that are associated with the bubble. In addition we have one set of solver parameters. In a multi-bubble simulation, however, we likely also have, for instance, only a single liquid (i.e.~all bubbles are situated in the same body of liquid), to which, in this case, all bubbles are associated to. Generally, the user is free in defining as many gases, liquids, interfaces and sets of solver parameters as deemed necessary, the only rule is that each bubble has to be associated with a gas, a liquid, an interface and a single set of solver parameters. Once these structures holding the fluid properties and the solver parameters are allocated, default values ought to be set, the user-defined options are read from file and the bubble(s) is/are successfully associated with its/their desired fluid properties and solver parameters. For a single-bubble simulation, this may look in a general form like:
+\begin{lstlisting}[style=CStyle,numbers=none]
+  struct APECSS_Gas *Gas = (struct APECSS_Gas *) malloc(sizeof(struct APECSS_Gas));
+  struct APECSS_Liquid *Liquid = (struct APECSS_Liquid *) malloc(sizeof(struct APECSS_Liquid));
+  struct APECSS_Interface *Interface = (struct APECSS_Interface *) malloc(sizeof(struct APECSS_Interface));
+  struct APECSS_NumericsODE *NumericsODE = (struct APECSS_NumericsODE *) malloc(sizeof(struct APECSS_NumericsODE));
+
+  apecss_gas_setdefaultoptions(Gas);
+  apecss_liquid_setdefaultoptions(Liquid);
+  apecss_interface_setdefaultoptions(Interface);
+  apecss_odesolver_setdefaultoptions(NumericsODE);
+
+  apecss_gas_readoptions(Gas, OptionsDir);
+  apecss_liquid_readoptions(Liquid, OptionsDir);
+  apecss_interface_readoptions(Interface, OptionsDir);
+  apecss_odesolver_readoptions(NumericsODE, OptionsDir);
+
+  Bubble->Gas = Gas;
+  Bubble->Liquid = Liquid;
+  Bubble->Interface = Interface;
+  Bubble->NumericsODE = NumericsODE;
+\end{lstlisting}\vspace{-0.75em}
+Note that opening and reading the options file from disk is a relatively expensive (we are talking about a few microseconds). For some of the single-bubble examples in {\tt \$APECSS\_DIR/examples} reading the options file is the most expensive operation by some margin. Therefore, if performance is of the essence, it might be worth hard coding the options instead of reading the options file.
+
+After reading the options file, the {\tt apecss\_*\_processoptions()} functions are called to process options and make the relevant modeling choices:
+\begin{lstlisting}[style=CStyle,numbers=none]
+  apecss_gas_processoptions(Gas);
+  apecss_liquid_processoptions(Liquid);
+  apecss_interface_processoptions(Interface);
+  apecss_odesolver_processoptions(NumericsODE);
+  apecss_bubble_processoptions(Bubble);
 \end{lstlisting}\vspace{-0.75em}
-While setting default values is advised, for instance using the function {\tt apecss\_options\_setdefault()}, it is optional. Processing the given options correctly, however, is critical to the working of APECSS and the using the function {\tt apecss\_options\_process()} is strongly encouraged.
+Processing the given options correctly is critical to the working of APECSS.
 
-Now that all options have been read and processed, the bubble has to be initialized based on the given options. This includes, for instance, computing the initial gas density and, if applicable hardcore radius or co-volume.
-\begin{lstlisting}[style=CStyle]
+Now that all options have been read and processed, the bubble has to be initialized based on the given options. This includes, for instance, computing the initial gas pressure inside the bubble (if it is not specified by the user) or, if applicable, the hardcore radius of the bubble.
+\begin{lstlisting}[style=CStyle,numbers=none]
   apecss_bubble_initialize(Bubble);
-\end{lstlisting}%\vspace{-0.75em}
+\end{lstlisting}
 
 The heart of APECSS is, of course, the solver. The solver is split into three separate functions that (i) initialize the solver, (ii) run the solver and (iii) wrap up (i.e.~finalize) the solver:
-\begin{lstlisting}[style=CStyle]
+\begin{lstlisting}[style=CStyle,numbers=none]
   apecss_bubble_solver_initialize(Bubble);
   apecss_bubble_solver_run(tend, Bubble);
   apecss_bubble_solver_finalize(Bubble);
 \end{lstlisting}\vspace{-0.75em}
 The initialization of the solver with {\tt apecss\_bubble\_solver\_initialize()} makes sure all counters, the solution error variable and, if applicable, result variables are initialized correctly. The function {\tt apecss\_bubble\_solver\_run()} contains the time-stepping procedure that executes the solver until a specified end time {\tt tend}, given as the first argument of the function call. In the examples found in {\tt \$APECSS\_DIR/examples}, the function {\tt apecss\_bubble\_solver\_run()} is only called once with {\tt tend = Bubble->tEnd}, i.e.~the end of the simulation. However, the user is free to call the function {\tt apecss\_bubble\_solver\_run()} an \underline{arbitrary number of times}, with any meaningful end time. This facilitates coupling APECSS to other numerical software frameworks, where {\tt tend} then could for instance be the end of the next time-step of a fluid dynamics solver. As an example simply chopping the simulation up into five equal-sized parts would look like:
-\begin{lstlisting}[style=CStyle]
+\begin{lstlisting}[style=CStyle,numbers=none]
   apecss_bubble_solver_initialize(Bubble);
   apecss_bubble_solver_run(0.2 * tend, Bubble);
   apecss_bubble_solver_run(0.4 * tend, Bubble);

documentation/chapters/using.tex

@@ -37,4 +37,4 @@ END
 ODESOLVER
 tolerance 1.0e-13
 maxtimestep 1.0e-6
-END
+END

examples/gastemperature/run.apecss

@@ -78,29 +78,46 @@ int main(int argc, char **args)
   struct APECSS_Bubble *Bubble = (struct APECSS_Bubble *) malloc(sizeof(struct APECSS_Bubble));
   apecss_bubble_initializestruct(Bubble);
 
-  /* Allocate and set the default options for the fluids */
-  Bubble->Gas = (struct APECSS_Gas *) malloc(sizeof(struct APECSS_Gas));
-  apecss_gas_setdefaultoptions(Bubble->Gas);
-  Bubble->Liquid = (struct APECSS_Liquid *) malloc(sizeof(struct APECSS_Liquid));
-  apecss_liquid_setdefaultoptions(Bubble->Liquid);
-  Bubble->Interface = (struct APECSS_Interface *) malloc(sizeof(struct APECSS_Interface));
-  apecss_interface_setdefaultoptions(Bubble->Interface);
-
-  /* Set default options for the bubble and the fluids */
+  /* Set default options and read the options for the bubble */
   apecss_bubble_setdefaultoptions(Bubble);
-
-  /* Read the options file */
-  apecss_options_readfile(Bubble, OptionsDir);
+  apecss_bubble_readoptions(Bubble, OptionsDir);
+
+  /* Allocate the structures for the fluid properties and ODE solver parameters */
+  struct APECSS_Gas *Gas = (struct APECSS_Gas *) malloc(sizeof(struct APECSS_Gas));
+  struct APECSS_Liquid *Liquid = (struct APECSS_Liquid *) malloc(sizeof(struct APECSS_Liquid));
+  struct APECSS_Interface *Interface = (struct APECSS_Interface *) malloc(sizeof(struct APECSS_Interface));
+  struct APECSS_NumericsODE *NumericsODE = (struct APECSS_NumericsODE *) malloc(sizeof(struct APECSS_NumericsODE));
+
+  /* Set the default options for the fluid properties and solver parameters  */
+  apecss_gas_setdefaultoptions(Gas);
+  apecss_liquid_setdefaultoptions(Liquid);
+  apecss_interface_setdefaultoptions(Interface);
+  apecss_odesolver_setdefaultoptions(NumericsODE);
+
+  /* Read the options file for the fluid properties and solver parameters  */
+  apecss_gas_readoptions(Gas, OptionsDir);
+  apecss_liquid_readoptions(Liquid, OptionsDir);
+  apecss_interface_readoptions(Interface, OptionsDir);
+  apecss_odesolver_readoptions(NumericsODE, OptionsDir);
+
+  /* Associate the bubble with the relevant fluid properties and solver parameters */
+  Bubble->Gas = Gas;
+  Bubble->Liquid = Liquid;
+  Bubble->Interface = Interface;
+  Bubble->NumericsODE = NumericsODE;
 
   // >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   // Set the case-dependent simulation parameters
   Bubble->tStart = 0.0;
   Bubble->tEnd = (APECSS_FLOAT) tEnd;
   Bubble->dt = APECSS_MIN(1.0e-7, Bubble->tEnd - Bubble->tStart);  // Initial time-step
-  Bubble->Excitation = (struct APECSS_Excitation *) malloc(sizeof(struct APECSS_Excitation));
-  Bubble->Excitation->type = APECSS_EXCITATION_SIN;
-  Bubble->Excitation->f = (APECSS_FLOAT) fa;
-  Bubble->Excitation->dp = (APECSS_FLOAT) pa;
+
+  struct APECSS_Excitation *Excitation = (struct APECSS_Excitation *) malloc(sizeof(struct APECSS_Excitation));
+  Excitation->type = APECSS_EXCITATION_SIN;
+  Excitation->f = (APECSS_FLOAT) fa;
+  Excitation->dp = (APECSS_FLOAT) pa;
+
+  Bubble->Excitation = Excitation;
 
   // Set the parameters and functions for the gas energy model
   _cv_ = 720.0;  // Isochoric heat capacity of the gas
@@ -132,9 +149,10 @@ int main(int argc, char **args)
   // <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 
   /* Process all options */
-  apecss_gas_processoptions(Bubble->Gas);
-  apecss_interface_processoptions(Bubble->Interface);
-  apecss_liquid_processoptions(Bubble->Liquid);
+  apecss_gas_processoptions(Gas);
+  apecss_liquid_processoptions(Liquid);
+  apecss_interface_processoptions(Interface);
+  apecss_odesolver_processoptions(NumericsODE);
   apecss_bubble_processoptions(Bubble);
 
   /* Initialize the bubble based on the selected options */
@@ -167,6 +185,13 @@ int main(int argc, char **args)
   /* Make sure all allocated memory is freed */
   apecss_bubble_freestruct(Bubble);
 
+  free(Bubble);
+  free(Gas);
+  free(Liquid);
+  free(Interface);
+  free(NumericsODE);
+  free(Excitation);
+
   return (0);
 }
 

examples/gastemperature/src/gastemperature_apecss.c

@@ -58,19 +58,33 @@ int main(int argc, char **args)
   struct APECSS_Bubble *Bubble = (struct APECSS_Bubble *) malloc(sizeof(struct APECSS_Bubble));
   apecss_bubble_initializestruct(Bubble);
 
-  /* Allocate and set the default options for the fluids */
-  Bubble->Gas = (struct APECSS_Gas *) malloc(sizeof(struct APECSS_Gas));
-  apecss_gas_setdefaultoptions(Bubble->Gas);
-  Bubble->Liquid = (struct APECSS_Liquid *) malloc(sizeof(struct APECSS_Liquid));
-  apecss_liquid_setdefaultoptions(Bubble->Liquid);
-  Bubble->Interface = (struct APECSS_Interface *) malloc(sizeof(struct APECSS_Interface));
-  apecss_interface_setdefaultoptions(Bubble->Interface);
-
-  /* Set default options for the bubble and the fluids */
+  /* Set default options and read the options for the bubble */
   apecss_bubble_setdefaultoptions(Bubble);
-
-  /* Read the options file */
-  apecss_options_readfile(Bubble, OptionsDir);
+  apecss_bubble_readoptions(Bubble, OptionsDir);
+
+  /* Allocate the structures for the fluid properties and ODE solver parameters */
+  struct APECSS_Gas *Gas = (struct APECSS_Gas *) malloc(sizeof(struct APECSS_Gas));
+  struct APECSS_Liquid *Liquid = (struct APECSS_Liquid *) malloc(sizeof(struct APECSS_Liquid));
+  struct APECSS_Interface *Interface = (struct APECSS_Interface *) malloc(sizeof(struct APECSS_Interface));
+  struct APECSS_NumericsODE *NumericsODE = (struct APECSS_NumericsODE *) malloc(sizeof(struct APECSS_NumericsODE));
+
+  /* Set the default options for the fluid properties and solver parameters  */
+  apecss_gas_setdefaultoptions(Gas);
+  apecss_liquid_setdefaultoptions(Liquid);
+  apecss_interface_setdefaultoptions(Interface);
+  apecss_odesolver_setdefaultoptions(NumericsODE);
+
+  /* Read the options file for the fluid properties and solver parameters  */
+  apecss_gas_readoptions(Gas, OptionsDir);
+  apecss_liquid_readoptions(Liquid, OptionsDir);
+  apecss_interface_readoptions(Interface, OptionsDir);
+  apecss_odesolver_readoptions(NumericsODE, OptionsDir);
+
+  /* Associate the bubble with the relevant fluid properties and solver parameters */
+  Bubble->Gas = Gas;
+  Bubble->Liquid = Liquid;
+  Bubble->Interface = Interface;
+  Bubble->NumericsODE = NumericsODE;
 
   // >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   // Set the case-dependent simulation parameters
@@ -80,9 +94,10 @@ int main(int argc, char **args)
   // <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 
   /* Process all options */
-  apecss_gas_processoptions(Bubble->Gas);
-  apecss_interface_processoptions(Bubble->Interface);
-  apecss_liquid_processoptions(Bubble->Liquid);
+  apecss_gas_processoptions(Gas);
+  apecss_liquid_processoptions(Liquid);
+  apecss_interface_processoptions(Interface);
+  apecss_odesolver_processoptions(NumericsODE);
   apecss_bubble_processoptions(Bubble);
 
   /* Initialize the bubble based on the selected options */
@@ -105,5 +120,11 @@ int main(int argc, char **args)
   /* Make sure all allocated memory is freed */
   apecss_bubble_freestruct(Bubble);
 
+  free(Bubble);
+  free(Gas);
+  free(Liquid);
+  free(Interface);
+  free(NumericsODE);
+
   return (0);
 }

examples/rayleighcollapse/src/rayleighcollapse_apecss.c

@@ -46,4 +46,4 @@ END
 
 ODESOLVER
 Tolerance 1.0e-12
-END
+END