- added documentation for position based fluids

Author: janbender

Changelog.txt

@@ -1,3 +1,5 @@
+	- added documentation for position based fluids
+
 1.3.0
 	- added some documentation
 	- cleaned up project 

PositionBasedDynamics/PositionBasedFluids.h

@@ -11,6 +11,30 @@ namespace PBD
 	public:
 		// -------------- Position Based Fluids  -----------------------------------------------------
 
+		/** Perform an SPH computation of the density of a fluid particle: 
+		* \f{equation*}{
+		* \rho_i = \sum_j m_j W(\mathbf{x}_i-\mathbf{x}_j).		
+		* \f}
+		* An additional term is added for neighboring boundary particles 
+		* according to \cite Akinci:2012 in order to perform boundary handling.\n\n
+		* Remark: A neighboring particle with an index >= numberOfParticles is
+		* handled as boundary particle.\n\n
+		*
+		* More information can be found in the following papers: \cite Macklin:2013:PBF, \cite BMOTM2014, \cite BMM2015
+		*
+		* @param particleIndex	index of current fluid particle
+		* @param numberOfParticles	number of fluid particles
+		* @param x	array of all particle positions
+		* @param mass array of all particle masses
+		* @param boundaryX array of all boundary particles
+		* @param boundaryPsi array of all boundary psi values (see \cite Akinci:2012)
+		* @param numNeighbors number of neighbors
+		* @param neighbors array with indices of all neighbors (indices larger than numberOfParticles are boundary particles)
+		* @param density0 rest density
+		* @param boundaryHandling perform boundary handling (see \cite Akinci:2012)
+		* @param density_err returns the clamped density error (can be used for enforcing a maximal global density error)
+		* @param density return the density
+		*/	
 		static bool computePBFDensity(
 			const unsigned int particleIndex,				// current fluid particle	
 			const unsigned int numberOfParticles,			// number of fluid particles 
@@ -25,6 +49,40 @@ namespace PBD
 			float &density_err,								// returns the clamped density error (can be used for enforcing a maximal global density error)
 			float &density);								// return the density
 
+		/**
+		 * Compute Lagrange multiplier \f$\lambda_i\f$ for a fluid particle which is required by
+		 * the solver step:
+		 * \f{equation*}{
+		 * \lambda_i = -\frac{C_i(\mathbf{x}_1,...,\mathbf{x}_n)}{\sum_k \|\nabla_{\mathbf{x}_k} C_i\|^2 + \varepsilon}
+		 * \f}
+		 * with the constraint gradient:
+		 * \f{equation*}{
+		 * \nabla_{\mathbf{x}_k}C_i = \frac{m_j}{\rho_0}
+		 * \begin{cases}
+		 * \sum\limits_j \nabla_{\mathbf{x}_k} W(\mathbf{x}_i-\mathbf{x}_j, h) & \text{if }  k = i \\
+		 * -\nabla_{\mathbf{x}_k} W(\mathbf{x}_i-\mathbf{x}_j, h)  & \text{if } k = j.
+		 * \end{cases}
+		 * \f}
+		 * \n
+		 * Remark: The computation of the gradient is extended for neighboring boundary particles
+		 * according to \cite Akinci:2012 to perform a boundary handling. A neighboring 
+		 * particle with an index >= numberOfParticles is handled as boundary particle.\n\n
+		 *
+		 * More information can be found in the following papers: \cite Macklin:2013:PBF, \cite BMOTM2014, \cite BMM2015
+		 *
+		 * @param particleIndex	index of current fluid particle
+		 * @param numberOfParticles	number of fluid particles
+		 * @param x	array of all particle positions
+		 * @param mass array of all particle masses
+		 * @param boundaryX array of all boundary particles
+		 * @param boundaryPsi array of all boundary psi values (see \cite Akinci:2012)
+		 * @param density density of current fluid particle
+		 * @param numNeighbors number of neighbors
+		 * @param neighbors array with indices of all neighbors (indices larger than numberOfParticles are boundary particles)
+		 * @param density0 rest density
+		 * @param boundaryHandling perform boundary handling (see \cite Akinci:2012)
+		 * @param lambda returns the Lagrange multiplier
+		 */		
 		static bool computePBFLagrangeMultiplier(
 			const unsigned int particleIndex,				// current fluid particle	
 			const unsigned int numberOfParticles,			// number of fluid particles 
@@ -39,6 +97,32 @@ namespace PBD
 			const bool boundaryHandling,					// perform boundary handling (Akinci2012)
 			float &lambda);									// returns the Lagrange multiplier
 
+		/** Perform a solver step for a fluid particle:
+		*
+		* \f{equation*}{
+		* \Delta\mathbf{x}_{i} = \frac{m_j}{\rho_0}\sum\limits_j{\left(\lambda_i + \lambda_j\right)\nabla W(\mathbf{x}_i-\mathbf{x}_j, h)},
+		* \f}
+		* where \f$h\f$ is the smoothing length of the kernel function \f$W\f$.\n
+		*\n
+		* Remark: The computation of the position correction is extended for neighboring boundary particles
+		* according to \cite Akinci:2012 to perform a boundary handling. A neighboring
+		* particle with an index >= numberOfParticles is handled as boundary particle.\n\n
+		*
+		* More information can be found in the following papers: \cite Macklin:2013:PBF, \cite BMOTM2014, \cite BMM2015
+		*
+		* @param particleIndex	index of current fluid particle
+		* @param numberOfParticles	number of fluid particles
+		* @param x	array of all particle positions
+		* @param mass array of all particle masses
+		* @param boundaryX array of all boundary particles
+		* @param boundaryPsi array of all boundary psi values (see \cite Akinci:2012)
+		* @param numNeighbors number of neighbors
+		* @param neighbors array with indices of all neighbors (indices larger than numberOfParticles are boundary particles)
+		* @param density0 rest density
+		* @param boundaryHandling perform boundary handling (see \cite Akinci:2012)
+		* @param lambda Lagrange multipliers
+		* @param corr returns the position correction for the current fluid particle
+		*/
 		static bool solveDensityConstraint(
 			const unsigned int particleIndex,				// current fluid particle	
 			const unsigned int numberOfParticles,			// number of fluid particles 

PositionBasedDynamics/PositionBasedRigidBodyDynamics.h

@@ -167,7 +167,7 @@ namespace PBD
 		* @param x1 center of mass of second body
 		* @param inertiaInverseW1 inverse inertia tensor in world coordinates of second body
 		* @param q1 rotation of second body
-		* @param ballJointInfo Ball joint information which is required by the solver. This
+		* @param jointInfo Ball joint information which is required by the solver. This
 		* information must be generated in the beginning by calling initRigidBodyBallJointInfo()
 		* and updated each time the bodies change their state by updateRigidBodyBallJointInfo().
 		* @param corr_x0 position correction of center of mass of first body
@@ -187,8 +187,7 @@ namespace PBD
 			const Eigen::Matrix<float, 3, 10> &jointInfo,	// precomputed joint info
 			Eigen::Vector3f &corr_x0, Eigen::Quaternionf &corr_q0,
 			Eigen::Vector3f &corr_x1, Eigen::Quaternionf &corr_q1);
-
-
+			
 		/** Initialize hinge joint and return info which is required by the solver step.
 		*
 		* @param x0 center of mass of first body

doc/bibliography.bib

@@ -52,7 +52,7 @@ @ARTICLE{Bender2013
   url = {http://www.sciencedirect.com/science/article/pii/S0097849313001283}
 }
 
-@article{Macklin:2013:PBF:2461912.2461984,
+@article{Macklin:2013:PBF,
  author = {Macklin, Miles and M\"{u}ller, Matthias},
  title = {Position based fluids},
  journal = {ACM Trans. Graph.},
@@ -134,4 +134,25 @@ @inproceedings{BMM2015
   booktitle =  "EUROGRAPHICS 2015 Tutorials",
   publisher =  "Eurographics Association",
   location =   "Zurich, Switzerland"
-}
+}
+
+@article{Akinci:2012,
+ author = {Akinci, Nadir and Ihmsen, Markus and Akinci, Gizem and Solenthaler, Barbara and Teschner, Matthias},
+ title = {Versatile Rigid-fluid Coupling for Incompressible SPH},
+ journal = {ACM Trans. Graph.},
+ issue_date = {July 2012},
+ volume = {31},
+ number = {4},
+ month = jul,
+ year = {2012},
+ issn = {0730-0301},
+ pages = {62:1--62:8},
+ articleno = {62},
+ numpages = {8},
+ url = {http://doi.acm.org/10.1145/2185520.2185558},
+ doi = {10.1145/2185520.2185558},
+ acmid = {2185558},
+ publisher = {ACM},
+ address = {New York, NY, USA},
+ keywords = {fluid simulation, fluid-solid coupling, physically-based animation, smoothed particle hydrodynamics},
+}