doc

git-svn-id: svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk@4406 2fb0f335-1f38-0410-981e-8018bf24f1b0

dumux/boxmodels/2p2c/2p2cfluidstate.hh

@@ -18,8 +18,8 @@
 /*!
  * \file
  *
- * \brief Calcultes the phase state from the primary variables in the
- *        2pNc model.
+ * \brief Calculates the phase state from the primary variables in the
+ *        2p2c model.
  */
 #ifndef DUMUX_2P2C_PHASE_STATE_HH
 #define DUMUX_2P2C_PHASE_STATE_HH
@@ -32,8 +32,8 @@
 namespace Dumux
 {
 /*!
- * \brief Calcultes the phase state from the primary variables in the
- *        2pNc model.
+ * \brief Calculates the phase state from the primary variables in the
+ *        2p2c model.
  */
 template <class TypeTag>
 class TwoPTwoCFluidState : public FluidState<typename GET_PROP_TYPE(TypeTag, PTAG(Scalar)),
@@ -83,6 +83,11 @@ public:
 
     /*!
      * \brief Update the phase state from the primary variables.
+     *
+     * \param primaryVars The primary variables
+     * \param pcParams The parameters for the material law
+     * \param temperature The temperature
+     * \param phasePresence Stands either for nonwetting phase, wetting phase or both phases
      */
     void update(const PrimaryVariables &primaryVars,
                 const MaterialLawParams &pcParams,
@@ -217,6 +222,9 @@ public:
      * \brief Retrieves the phase composition and pressure from a
      *        phase composition class.
      *
+     * \param phaseIdx The phase index
+     * \param compo The index of the component
+     *
      * This method is called by the fluid system's
      * computeEquilibrium()
      */
@@ -233,6 +241,8 @@ public:
 
     /*!
      * \brief Returns the saturation of a phase.
+     *
+     * \param phaseIdx The phase index
      */
     Scalar saturation(int phaseIdx) const
     {
@@ -243,7 +253,10 @@ public:
     };
 
     /*!
-     * \brief Returns the molar fraction of a component in a fluid phase.
+     * \brief Returns the mole fraction of a component in a fluid phase.
+     *
+     * \param phaseIdx The phase index
+     * \param compIdx The index of the component
      */
     Scalar moleFrac(int phaseIdx, int compIdx) const
     {
@@ -253,21 +266,31 @@ public:
     }
 
     /*!
-     * \brief Returns the total concentration of a phase [mol / m^3].
+     * \brief Returns the molar density of a phase [mol / m^3].
      *
-     * This is equivalent to the sum of all component concentrations.
+     * \param phaseIdx The phase index
+     *
+     * This is equivalent to the sum of all molar component concentrations.
      */
     Scalar phaseConcentration(int phaseIdx) const
     { return phaseConcentration_[phaseIdx]; };
 
     /*!
-     * \brief Returns the concentration of a component in a phase [mol / m^3].
+     * \brief Returns the molar concentration of a component in a phase [mol / m^3].
+     *
+     * \param phaseIdx The phase index
+     * \param compIdx The index of the component
+     *
      */
     Scalar concentration(int phaseIdx, int compIdx) const
     { return concentration_[phaseIdx][compIdx]; };
 
     /*!
      * \brief Returns the mass fraction of a component in a phase.
+     *
+     * \param phaseIdx The phase index
+     * \param compIdx The index of the component
+     *
      */
     Scalar massFrac(int phaseIdx, int compIdx) const
     {
@@ -277,7 +300,9 @@ public:
     }
 
     /*!
-     * \brief Returns the density of a phase [kg / m^3].
+     * \brief Returns the mass density of a phase [kg / m^3].
+     *
+     * \param phaseIdx The phase index
      */
     Scalar density(int phaseIdx) const
     { return phaseConcentration_[phaseIdx]*avgMolarMass_[phaseIdx]; }
@@ -285,6 +310,8 @@ public:
     /*!
      * \brief Returns mean molar mass of a phase [kg / mol].
      *
+     * \param phaseIdx The phase index
+     *
      * This is equivalent to the sum of all component molar masses
      * weighted by their respective mole fraction.
      */
@@ -293,12 +320,16 @@ public:
 
     /*!
      * \brief Returns the pressure of a fluid phase [Pa].
+     *
+     * \param phaseIdx The phase index
      */
     Scalar phasePressure(int phaseIdx) const
     { return phasePressure_[phaseIdx]; }
 
     /*!
      * \brief Return the fugacity of a component [Pa].
+     *
+     * \param compIdx The index of the component
      */
     Scalar fugacity(int compIdx) const
     { return moleFrac(gPhaseIdx, compIdx)*phasePressure(gPhaseIdx); };

dumux/boxmodels/2p2c/2p2cfluxvariables.hh

@@ -18,12 +18,12 @@
 /*!
  * \file
  *
+ * \brief   This file contains the data which is required to calculate
+ *          all fluxes of components over a face of a finite volume for
+ *          the two-phase, two-component model.
+ */
+/*!
  * \ingroup TwoPTwoCModel
- * \brief This file contains the data which is required to calculate
- *        all fluxes of components over a face of a finite volume.
- *
- * This means pressure, concentration and temperature gradients, phase
- * densities, etc. at the integration points of the control volume
  */
 #ifndef DUMUX_2P2C_FLUX_VARIABLES_HH
 #define DUMUX_2P2C_FLUX_VARIABLES_HH
@@ -40,7 +40,7 @@ namespace Dumux
  *        volume for the two-phase, two-component model.
  *
  * This means pressure and concentration gradients, phase densities at
- * the intergration point, etc.
+ * the integration point, etc.
  */
 template <class TypeTag>
 class TwoPTwoCFluxVariables

dumux/boxmodels/2p2c/2p2cindices.hh

@@ -42,6 +42,7 @@ struct TwoPTwoCFormulation
 /*!
  * \brief The indices for the isothermal TwoPTwoC model.
  *
+ * \tparam formulation The formulation, either pwSn or pnSw.
  * \tparam PVOffset The first index in a primary variable vector.
  */
 template <class TypeTag,

dumux/boxmodels/2p2c/2p2clocalresidual.hh

@@ -15,6 +15,13 @@
  *                                                                           *
  *   This program is distributed WITHOUT ANY WARRANTY.                       *
  *****************************************************************************/
+/*!
+ * \file
+ *
+ * \brief Element-wise calculation of the Jacobian matrix for problems
+ *        using the two-phase two-component box model.
+ */
+
 #ifndef DUMUX_NEW_2P2C_LOCAL_RESIDUAL_BASE_HH
 #define DUMUX_NEW_2P2C_LOCAL_RESIDUAL_BASE_HH
 
@@ -38,8 +45,8 @@ namespace Dumux
 {
 /*!
  * \ingroup TwoPTwoCModel
- * \brief 2P-2C specific details needed to approximately calculate
- *        the local jacobian in the BOX scheme.
+ * \brief Element-wise calculation of the Jacobian matrix for problems
+ *        using the two-phase two-component box model.
  *
  * This class is used to fill the gaps in BoxLocalResidual for the 2P-2C flow.
  */
@@ -117,6 +124,9 @@ public:
     /*!
      * \brief Evaluate the storage term of the current solution in a
      *        single phase.
+     *
+     * \param element The element
+     * \param phaseIdx The index of the fluid phase
      */
     void evalPhaseStorage(const Element &element, int phaseIdx)
     {
@@ -139,11 +149,15 @@ public:
     }
     
     /*!
-     * \brief Evaluate the amount all conservation quantites
+     * \brief Evaluate the amount all conservation quantities
      *        (e.g. phase mass) within a sub-control volume.
      *
      * The result should be averaged over the volume (e.g. phase mass
      * inside a sub control volume divided by the volume)
+     *
+     *  \param result The mass of the component within the sub-control volume
+     *  \param scvIdx The SCV (sub-control-volume) index
+     *  \param usePrevSol Evaluate function with solution of current or previous time step
      */
     void computeStorage(PrimaryVariables &result, int scvIdx, bool usePrevSol) const
     {
@@ -173,7 +187,10 @@ public:
 
     /*!
      * \brief Evaluates the total flux of all conservation quantities
-     *        over a face of a subcontrol volume.
+     *        over a face of a sub-control volume.
+     *
+     * \param flux The flux over the SCV (sub-control-volume) face for each component
+     * \param faceIdx The index of the SCV face
      */
     void computeFlux(PrimaryVariables &flux, int faceIdx) const
     {
@@ -195,6 +212,9 @@ public:
     /*!
      * \brief Evaluates the advective mass flux of all components over
      *        a face of a subcontrol volume.
+     *
+     * \param flux The advective flux over the sub-control-volume face for each component
+     * \param fluxVars The flux variables at the current SCV
      */
     void computeAdvectiveFlux(PrimaryVariables &flux, const FluxVariables &vars) const
     {
@@ -234,6 +254,9 @@ public:
     /*!
      * \brief Adds the diffusive mass flux of all components over
      *        a face of a subcontrol volume.
+     *
+     * \param flux The diffusive flux over the sub-control-volume face for each component
+     * \param fluxData The flux variables at the current SCV
      */
     void computeDiffusiveFlux(PrimaryVariables &flux, const FluxVariables &vars) const
     {
@@ -256,6 +279,9 @@ public:
 
     /*!
      * \brief Calculate the source term of the equation
+     *
+     * \param q The source/sink in the SCV for each component
+     * \param localVertexIdx The index of the SCV
      */
     void computeSource(PrimaryVariables &q, int localVertexIdx)
     {

dumux/boxmodels/2p2c/2p2cmodel.hh

@@ -13,6 +13,13 @@
  *                                                                           *
  *   This program is distributed WITHOUT ANY WARRANTY.                       *
  *****************************************************************************/
+
+/*!
+* \file
+*
+* \brief Adaption of the BOX scheme to the two-phase two-component flow model.
+*/
+
 #ifndef DUMUX_2P2C_MODEL_HH
 #define DUMUX_2P2C_MODEL_HH
 
@@ -148,6 +155,8 @@ class TwoPTwoCModel: public BoxModel<TypeTag>
 public:
     /*!
      * \brief Initialize the static data with the initial solution.
+     *
+     * \param problem The problem to be solved
      */
     void init(Problem &problem)
     {
@@ -178,6 +187,9 @@ public:
     /*!
      * \brief Compute the total storage inside one phase of all
      *        conservation quantities.
+     *
+     * \param dest Contains the storage of each component for one phase
+     * \param phaseIdx The phase index
      */
     void globalPhaseStorage(PrimaryVariables &dest, int phaseIdx)
     {
@@ -213,6 +225,9 @@ public:
     /*!
      * \brief Returns the relative weight of a primary variable for
      *        calculating relative errors.
+     *
+     * \param globalVertexIdx The global vertex index
+     * \param pvIdx The primary variable index
      */
     Scalar primaryVarWeight(int globalVertexIdx, int pvIdx) const
     {
@@ -222,11 +237,11 @@ public:
     }
 
     /*!
-     * \brief Called by the problem if a timeintegration was
+     * \brief Called by the problem if a time integration was
      *        successful, post processing of the solution is done and the 
      *        result has been written to disk. 
      *
-     * This should perpare the model for the next time integration.
+     * This should prepare the model for the next time integration.
      */
     void advanceTimeLevel()
     {
@@ -248,6 +263,9 @@ public:
 
     /*!
      * \brief Returns the phase presence of the current or the old solution of a vertex.
+     *
+     * \param globalVertexIdx The global vertex index
+     * \param oldSol Evaluate function with solution of current or previous time step
      */
     int phasePresence(int globalVertexIdx, bool oldSol) const
     {
@@ -259,6 +277,9 @@ public:
      * \brief Append all quantities of interest which can be derived
      *        from the solution of the current time step to the VTK
      *        writer.
+     *
+     * \param sol The solution vector
+     * \param writer The writer for multi-file VTK datasets
      */
     template<class MultiWriter>
     void addOutputVtkFields(const SolutionVector &sol,
@@ -461,6 +482,9 @@ public:
 
     /*!
      * \brief Write the current solution to a restart file.
+     *
+     * \param outStream The output stream of one vertex for the restart file
+     * \param vert The vertex
      */
     void serializeEntity(std::ostream &outStream, const Vertex &vert)
     {
@@ -477,6 +501,9 @@ public:
     /*!
      * \brief Reads the current solution for a vertex from a restart
      *        file.
+     *
+     * \param inStream The input stream of one vertex from the restart file
+     * \param vert The vertex
      */
     void deserializeEntity(std::istream &inStream, const Vertex &vert)
     {
@@ -497,6 +524,9 @@ public:
 
     /*!
      * \brief Update the static data of all vertices in the grid.
+     *
+     * \param curGlobalSol The current global solution
+     * \param oldGlobalSol The previous global solution
      */
     void updateStaticData(SolutionVector &curGlobalSol,
                           SolutionVector &oldGlobalSol)

dumux/boxmodels/2p2c/2p2cnewtoncontroller.hh

@@ -65,8 +65,16 @@ public:
         this->setMaxSteps(18);
     };
 
-    //! Suggest a new time stepsize based either on the number of newton
-    //! iterations required or on the variable switch
+
+    /*!
+     * \brief
+     * Suggest a new time step size based either on the number of newton
+     * iterations required or on the variable switch
+     *
+     * \param u The current global solution vector
+     * \param uOld The previous global solution vector
+     *
+     */
     void newtonEndStep(SolutionVector &u, SolutionVector &uOld)
     {
         // call the method of the base class
@@ -74,6 +82,21 @@ public:
         ParentType::newtonEndStep(u, uOld);
     }
 
+    /*!
+     * \brief Update the current solution function with a delta vector.
+     *
+     * The error estimates required for the newtonConverged() and
+     * newtonProceed() methods should be updated here.
+     *
+     * Different update strategies, such as line search and chopped
+     * updates can be implemented. The default behaviour is just to
+     * subtract deltaU from uOld.
+     *
+     * \param deltaU The delta as calculated from solving the linear
+     *               system of equations. This parameter also stores
+     *               the updated solution.
+     * \param uOld   The solution of the last iteration
+     */
     void newtonUpdate(SolutionVector &deltaU, const SolutionVector &uOld)
     {
         this->writeConvergence_(uOld, deltaU);
@@ -89,8 +112,11 @@ public:
     }
 
 
-    //! Returns true iff the current solution can be considered to
-    //! be acurate enough
+    /*!
+     * \brief
+     * Returns true if the current solution can be considered to
+     * be accurate enough
+     */
     bool newtonConverged()
     {
         if (this->method().model().switched())

dumux/boxmodels/2p2c/2p2cproblem.hh

@@ -30,7 +30,6 @@ namespace Dumux
  * \ingroup TwoPTwoCProblems
  * \brief Base class for all problems which use the two-phase, two-component box model
  *
- * \todo Please doc me more!
  */
 template<class TypeTag>
 class TwoPTwoCProblem : public BoxProblem<TypeTag>
@@ -54,6 +53,12 @@ class TwoPTwoCProblem : public BoxProblem<TypeTag>
     typedef Dune::FieldVector<Scalar, dimWorld> GlobalPosition;
 
 public:
+    /*!
+     * \brief The constructor
+     *
+     * \param timeManager The time mananager
+     * \param gridView The grid view
+     */
     TwoPTwoCProblem(TimeManager &timeManager, const GridView &gridView)
         : ParentType(timeManager, gridView),
           gravity_(0),

dumux/boxmodels/2p2c/2p2cvolumevariables.hh

@@ -77,6 +77,13 @@ class TwoPTwoCVolumeVariables : public BoxVolumeVariables<TypeTag>
 public:
     /*!
      * \brief Update all quantities for a given control volume.
+     *
+     * \param priVars The primary variables
+     * \param problem The problem
+     * \param element The element
+     * \param elemGeom Evaluate function with solution of current or previous time step
+     * \param scvIdx The local index of the SCV (sub-control volume)
+     * \param isOldSol Evaluate function with solution of current or previous time step
      */
     void update(const PrimaryVariables &priVars,
                 const Problem &problem,
@@ -149,15 +156,6 @@ public:
         Valgrind::CheckDefined(porosity_);
    }
 
-    void updateTemperature_(const PrimaryVariables &priVars,
-                            const Element &element,
-                            const FVElementGeometry &elemGeom,
-                            int scvIdx,
-                            const Problem &problem)
-    {
-        temperature_ = problem.temperature(element, elemGeom, scvIdx);
-    }
-
     /*!
      * \brief Returns the phase state for the control-volume.
      */
@@ -167,6 +165,8 @@ public:
     /*!
      * \brief Returns the effective saturation of a given phase within
      *        the control volume.
+     *
+     * \param phaseIdx The phase index
      */
     Scalar saturation(int phaseIdx) const
     { return fluidState_.saturation(phaseIdx); }
@@ -174,6 +174,8 @@ public:
     /*!
      * \brief Returns the mass density of a given phase within the
      *        control volume.
+     *
+     * \param phaseIdx The phase index
      */
     Scalar density(int phaseIdx) const
     { return fluidState_.density(phaseIdx); }
@@ -181,6 +183,8 @@ public:
     /*!
      * \brief Returns the mass density of a given phase within the
      *        control volume.
+     *
+     * \param phaseIdx The phase index
      */
     Scalar molarDensity(int phaseIdx) const
     { return fluidState_.density(phaseIdx) / fluidState_.averageMolarMass(phaseIdx); }
@@ -188,6 +192,8 @@ public:
     /*!
      * \brief Returns the effective pressure of a given phase within
      *        the control volume.
+     *
+     * \param phaseIdx The phase index
      */
     Scalar pressure(int phaseIdx) const
     { return fluidState_.phasePressure(phaseIdx); }
@@ -205,6 +211,8 @@ public:
     /*!
      * \brief Returns the effective mobility of a given phase within
      *        the control volume.
+     *
+     * \param phaseIdx The phase index
      */
     Scalar mobility(int phaseIdx) const
     {
@@ -231,6 +239,16 @@ public:
 
 
 protected:
+
+    void updateTemperature_(const PrimaryVariables &priVars,
+                            const Element &element,
+                            const FVElementGeometry &elemGeom,
+                            int scvIdx,
+                            const Problem &problem)
+    {
+        temperature_ = problem.temperature(element, elemGeom, scvIdx);
+    }
+
     Scalar temperature_;     //!< Temperature within the control volume
     Scalar porosity_;        //!< Effective porosity within the control volume
     Scalar mobility_[numPhases];  //!< Effective mobility within the control volume