Added documentation for the minimal SPH implementation such that it can be...

Added documentation for the minimal SPH implementation such that it can be used as a template for new versions of SPH.

src/hydro/Minimal/hydro.h

 /*******************************************************************************
  * This file is part of SWIFT.
- * Coypright (c) 2015 Matthieu Schaller (matthieu.schaller@durham.ac.uk)
+ * Copyright (c) 2016 Matthieu Schaller (matthieu.schaller@durham.ac.uk)
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU Lesser General Public License as published
@@ -22,6 +22,9 @@
 /**
  * @brief Computes the hydro time-step of a given particle
  *
+ * This function returns the time-step of a particle given its hydro-dynamical
+ * state. A typical time-step calculation would be the use of the CFL condition.
+ *
  * @param p Pointer to the particle data
  * @param xp Pointer to the extended particle data
  *
@@ -39,7 +42,8 @@ __attribute__((always_inline)) INLINE static float hydro_compute_timestep(
  * @brief Initialises the particles for the first time
  *
  * This function is called only once just after the ICs have been
- * read in to do some conversions.
+ * read in to do some conversions or assignments between the particle
+ * and extended particle fields.
  *
  * @param p The particle to act upon
  * @param xp The extended particle data to act upon
@@ -54,7 +58,8 @@ __attribute__((always_inline))
  * @brief Prepares a particle for the density calculation.
  *
  * Zeroes all the relevant arrays in preparation for the sums taking place in
- * the variaous density tasks
+ * the various density loop over neighbours. Typically, all fields of the
+ * density sub-structure of a particle get zeroed in here.
  *
  * @param p The particle to act upon
  */
@@ -71,6 +76,9 @@ __attribute__((always_inline))
  *
  * Multiplies the density and number of neighbours by the appropiate constants
  * and add the self-contribution term.
+ * Additional quantities such as velocity gradients will also get the final
+ *terms
+ * added to them here.
  *
  * @param p The particle to act upon
  * @param time The current time
@@ -99,7 +107,12 @@ __attribute__((always_inline))
 /**
  * @brief Prepare a particle for the force calculation.
  *
- * Computes viscosity term, conduction term and smoothing length gradient terms.
+ * This function is called in the ghost task to convert some quantities coming
+ * from the density loop over neighbours into quantities ready to be used in the
+ * force loop over neighbours. Quantities are typically read from the density
+ * sub-structure and written to the force sub-structure.
+ * Examples of calculations done here include the calculation of viscosity term
+ * constants, thermal conduction terms, hydro conversions, etc.
  *
  * @param p The particle to act upon
  * @param xp The extended particle data to act upon
@@ -115,7 +128,7 @@ __attribute__((always_inline)) INLINE static void hydro_prepare_force(
  * @brief Reset acceleration fields of a particle
  *
  * Resets all hydro acceleration and time derivative fields in preparation
- * for the sums taking place in the variaous force tasks
+ * for the sums taking  place in the various force tasks.
  *
  * @param p The particle to act upon
  */
@@ -136,6 +149,9 @@ __attribute__((always_inline))
 /**
  * @brief Predict additional particle fields forward in time when drifting
  *
+ * Additional hydrodynamic quantites are drifted forward in time here. These
+ * include thermal quantities (thermal energy or total energy or entropy, ...).
+ *
  * @param p The particle
  * @param xp The extended data of the particle
  * @param t0 The time at the start of the drift
@@ -160,7 +176,9 @@ __attribute__((always_inline)) INLINE static void hydro_predict_extra(
 /**
  * @brief Finishes the force calculation.
  *
- * Multiplies the forces and accelerationsby the appropiate constants
+ * Multiplies the force and accelerations by the appropiate constants
+ * and add the self-contribution term. In most cases, there is nothing
+ * to do here.
  *
  * @param p The particle to act upon
  */
@@ -170,6 +188,9 @@ __attribute__((always_inline))
 /**
  * @brief Kick the additional variables
  *
+ * Additional hydrodynamic quantites are kicked forward in time here. These
+ * include thermal quantities (thermal energy or total energy or entropy, ...).
+ *
  * @param p The particle to act upon
  * @param xp The particle extended data to act upon
  * @param dt The time-step for this kick
@@ -186,9 +207,12 @@ __attribute__((always_inline)) INLINE static void hydro_kick_extra(
 }
 
 /**
- * @brief Converts hydro quantity of a particle
+ * @brief Converts hydro quantity of a particle at the start of a run
  *
- * Requires the density to be known
+ * This function is called once at the end of the engine_init_particle()
+ * routine (at the start of a calculation) after the densities of
+ * particles have been computed.
+ * This can be used to convert internal energy into entropy for instance.
  *
  * @param p The particle to act upon
  */

src/hydro/Minimal/hydro_iact.h

 /*******************************************************************************
  * This file is part of SWIFT.
- * Copyright (c) 2012 Pedro Gonnet (pedro.gonnet@durham.ac.uk)
- *                    Matthieu Schaller (matthieu.schaller@durham.ac.uk)
+ * Copyright (c) 2016 Matthieu Schaller (matthieu.schaller@durham.ac.uk)
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU Lesser General Public License as published
@@ -27,24 +26,15 @@
 #include "vector.h"
 
 /**
- * @brief SPH interaction functions following the Gadget-2 version of SPH.
+ * @brief Minimal conservative implementation of SPH
  *
- * The interactions computed here are the ones presented in the Gadget-2 paper
- *and use the same
- * numerical coefficients as the Gadget-2 code. When used with the Spline-3
- *kernel, the results
- * should be equivalent to the ones obtained with Gadget-2 up to the rounding
- *errors and interactions
- * missed by the Gadget-2 tree-code neighbours search.
- *
- * The code uses internal energy instead of entropy as a thermodynamical
- *variable.
+ * The thermal variable is the internal energy (u). No viscosity nor 
+ * thermal conduction terms are implemented. 
  */
 
 /**
  * @brief Density loop
  */
-
 __attribute__((always_inline)) INLINE static void runner_iact_density(
     float r2, float *dx, float hi, float hj, struct part *pi, struct part *pj) {
 

src/hydro/Minimal/hydro_part.h

 /*******************************************************************************
  * This file is part of SWIFT.
- * Copyright (c) 2012 Pedro Gonnet (pedro.gonnet@durham.ac.uk)
+ * Copyright (c) 2016 Matthieu Schaller (matthieu.schaller@durham.ac.uk)
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU Lesser General Public License as published
@@ -17,88 +17,92 @@
  *
  ******************************************************************************/
 
-/* Extra particle data not needed during the SPH loops over neighbours. */
+/**
+ * @brief Particle fields not needed during the SPH loops over neighbours.
+ *
+ * This structure contains the particle fields that are not used in the
+ * density or force loops. Quantities should be used in the kick, drift and
+ * potentially ghost tasks only.
+ */
 struct xpart {
 
-  /* Old position, at last tree rebuild. */
-  double x_old[3];
+  double x_old[3]; /*!< Old position, at last tree rebuild. */
 
-  /* Velocity at the last full step. */
-  float v_full[3];
+  float v_full[3]; /*!< Velocity at the last full step. */
 
-  /* Thermal energy at the last full step. */
-  float u_full;
+  float u_full; /*!< Thermal energy at the last full step. */
 
 } __attribute__((aligned(xpart_align)));
 
-/* Data of a single particle. */
+/**
+ * @brief Particle fields for the SPH particles
+ *
+ * The density and force substructures are used to contain variables only used
+ * within the density and force loops over neighbours. All more permanent
+ * variables should be declared in the main part of the part structure,
+ */
 struct part {
 
-  /* Particle position. */
-  double x[3];
+  double x[3]; /*!< Particle position. */
 
-  /* Particle predicted velocity. */
-  float v[3];
+  float v[3]; /*!< Particle predicted velocity. */
 
-  /* Particle acceleration. */
-  float a_hydro[3];
+  float a_hydro[3]; /*!< Particle acceleration. */
 
-  /* Particle mass. */
-  float mass;
+  float mass; /*!< Particle mass. */
 
-  /* Particle cutoff radius. */
-  float h;
+  float h; /*!< Particle smoothing length. */
 
-  /* Change in smoothing length over time. */
-  float h_dt;
+  float h_dt; /*!< Time derivative of smoothing length  */
 
-  /* Particle time of beginning of time-step. */
-  float t_begin;
+  float t_begin; /*!< Time at the beginning of time-step. */
 
-  /* Particle time of end of time-step. */
-  float t_end;
+  float t_end; /*!< Time at the end of time-step. */
 
-  /* Particle internal energy. */
-  float u;
+  float u; /*!< Particle internal energy. */
 
-  /* Thermal energy time derivative */
-  float u_dt;
+  float u_dt; /*!< Time derivative of the internal energy. */
 
-  /* Particle density. */
-  float rho;
+  float rho; /*!< Particle density. */
 
-  /* Derivative of the density with respect to this particle's smoothing length.
-   */
-  float rho_dh;
+  float rho_dh; /*!< Derivative of density with respect to h */
 
   /* Store density/force specific stuff. */
   union {
 
+    /**
+     * @brief Structure for the variables only used in the density loop over
+     * neighbours.
+     *
+     * Quantities in this sub-structure should only be accessed in the density
+     * loop over neighbours and the ghost task.
+     */
     struct {
 
-      /* Particle number density. */
-      float wcount;
-
-      /* Derivative of particle number density. */
-      float wcount_dh;
+      float wcount; /*!< Neighbour number count. */
 
+      float wcount_dh; /*!< Derivative of the neighbour number with respect to
+                          h. */
     } density;
 
+    /**
+     * @brief Structure for the variables only used in the force loop over
+     * neighbours.
+     *
+     * Quantities in this sub-structure should only be accessed in the force
+     * loop over neighbours and the ghost and kick tasks.
+     */
     struct {
 
-      /* Pressure */
-      float pressure;
+      float pressure; /*!< Particle pressure. */
 
-      /* Signal velocity */
-      float v_sig;
+      float v_sig; /*!< Particle signal velocity */
 
     } force;
   };
 
-  /* Particle ID. */
-  unsigned long long id;
+  unsigned long long id; /*!< Particle unique ID. */
 
-  /* Pointer to corresponding gravity part. */
-  struct gpart* gpart;
+  struct gpart* gpart; /*!< Pointer to corresponding gravity part. */
 
 } __attribute__((aligned(part_align)));