From 005cda508ceaabe6eda22c8b85e77e16ace37b9e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Atgeirr=20Fl=C3=B8=20Rasmussen?= <atgeirr@sintef.no>
Date: Wed, 13 Jun 2012 15:55:23 +0200
Subject: [PATCH] Improved docs.

---
 opm/polymer/TransportModelPolymer.hpp | 42 ++++++++++++++++++++++-----
 1 file changed, 35 insertions(+), 7 deletions(-)

diff --git a/opm/polymer/TransportModelPolymer.hpp b/opm/polymer/TransportModelPolymer.hpp
index 9681af3fe..e3c8b3f98 100644
--- a/opm/polymer/TransportModelPolymer.hpp
+++ b/opm/polymer/TransportModelPolymer.hpp
@@ -32,8 +32,8 @@ namespace Opm
 
     class IncompPropertiesInterface;
 
-    /// A transport model for two-phase flow with polymer in the
-    /// water phase.
+    /// Implements a reordering transport solver for incompressible two-phase flow
+    /// with polymer in the water phase.
     /// \TODO Include permeability reduction effect.
     class TransportModelPolymer : public TransportModelInterface
     {
@@ -42,7 +42,16 @@ namespace Opm
 	enum SingleCellMethod { Bracketing, Newton };
         enum GradientMethod { Analytic, FinDif }; // Analytic is chosen (hard-coded)
 
-	/// \TODO document me, especially method.
+	/// Construct solver.
+	/// \param[in] grid       A 2d or 3d grid.
+	/// \param[in] props      Rock and fluid properties.
+	/// \param[in] polyprops  Polymer properties.
+	/// \param[in] method     Bracketing: solve for c in outer loop, s in inner loop,
+        ///                                   each solve being bracketed for robustness.
+	///                       Newton: solve simultaneously for c and s with Newton's method.
+        ///                               (using gradient variant and bracketing as fallbacks).
+	/// \param[in] tol        Tolerance used in the solver.
+	/// \param[in] maxit      Maximum number of non-linear iterations used.
 	TransportModelPolymer(const UnstructuredGrid& grid,
 			      const IncompPropertiesInterface& props,
 			      const PolymerProperties& polyprops,
@@ -50,12 +59,19 @@ namespace Opm
 			      const double tol,
 			      const int maxit);
 
-	/// \TODO document me.
+	/// Set the preferred method, Bracketing or Newton.
         void setPreferredMethod(SingleCellMethod method);
 
-	/// Solve transport eqn with implicit Euler scheme, reordered.
-	/// \TODO Now saturation is expected to be one sw value per cell,
-	/// change to [sw so] per cell.
+	/// Solve for saturation, concentration and cmax at next timestep.
+	/// Using implicit Euler scheme, reordered.
+	/// \param[in] darcyflux           Array of signed face fluxes.
+	/// \param[in] porevolume          Array of pore volumes.
+	/// \param[in] source              Transport source term.
+	/// \param[in] dt                  Time step.
+	/// \param[in] inflow_c            Time step.
+	/// \param[in, out] saturation     Phase saturations.
+	/// \param[in, out] concentration  Polymer concentration.
+	/// \param[in, out] cmax           Highest concentration that has occured in a given cell.
 	void solve(const double* darcyflux,
                    const double* porevolume,
 		   const double* source,
@@ -65,12 +81,24 @@ namespace Opm
                    std::vector<double>& concentration,
                    std::vector<double>& cmax);
 
+        /// Solve for gravity segregation.
+        /// This uses a column-wise nonlinear Gauss-Seidel approach.
+        /// It assumes that the input columns contain cells in a single
+        /// vertical stack, that do not interact with other columns (for
+        /// gravity segregation.
+	/// \param[in] columns             Vector of cell-columns.
+	/// \param[in] porevolume          Array of pore volumes.
+	/// \param[in] dt                  Time step.
+	/// \param[in, out] saturation     Phase saturations.
+	/// \param[in, out] concentration  Polymer concentration.
+	/// \param[in, out] cmax           Highest concentration that has occured in a given cell.
         void solveGravity(const std::vector<std::vector<int> >& columns,
                           const double* porevolume,
                           const double dt,
                           std::vector<double>& saturation,
                           std::vector<double>& concentration,
                           std::vector<double>& cmax);
+
     public: // But should be made private...
 	virtual void solveSingleCell(const int cell);
 	virtual void solveMultiCell(const int num_cells, const int* cells);