diff --git a/src/hydro/Minimal/hydro.h b/src/hydro/Minimal/hydro.h
index ba3b6071f0e81d4fbfb78dc411b0da6d020c6522..b73114b437713d8045492f6db30afa7dbf8f82a8 100644
--- a/src/hydro/Minimal/hydro.h
+++ b/src/hydro/Minimal/hydro.h
@@ -1,6 +1,6 @@
/*******************************************************************************
* 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
*/
diff --git a/src/hydro/Minimal/hydro_iact.h b/src/hydro/Minimal/hydro_iact.h
index 652734a080f9d2cc7e71aea2a6c0294295a04468..b8a21b4bb0720a5889a8f8dabbb42714bf285327 100644
--- a/src/hydro/Minimal/hydro_iact.h
+++ b/src/hydro/Minimal/hydro_iact.h
@@ -1,7 +1,6 @@
/*******************************************************************************
* 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) {
diff --git a/src/hydro/Minimal/hydro_part.h b/src/hydro/Minimal/hydro_part.h
index 35a29d6610f5532c3c1f3adaccd25bcf00d1c96b..b89cc249a42032e05bd35498c5c6435f3ebc4f4b 100644
--- a/src/hydro/Minimal/hydro_part.h
+++ b/src/hydro/Minimal/hydro_part.h
@@ -1,6 +1,6 @@
/*******************************************************************************
* 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)));