Document public interface of compr_quant_general module

This is Doxygen-style reference documentation only.

opm/core/pressure/tpfa/compr_quant_general.h

@@ -22,23 +22,109 @@
 
 #include <stddef.h>
 
+/**
+ * \file
+ * Module defining derived fluid quantities needed to discretise compressible
+ * and miscible pressure (flow) problems.
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * Aggregate structure that represents an atomic view of the current fluid
+ * state.  These quantities are used directly in the cfs_tpfa_residual module to
+ * discretise a particular, linearised flow problem.
+ */
 struct compr_quantities_gen {
-    int     nphases;      /* Number of phases/components */
+    /**
+     * Number of fluid phases.  The pressure solvers also assume that the number
+     * of fluid components (at surface conditions) equals the number of fluid
+     * phases.
+     */
+    int nphases;
 
-    double *Ac;           /* RB^{-1} per cell */
-    double *dAc;          /* d/dp (RB^{-1}) per cell */
-    double *Af;           /* RB^{-1} per face */
-    double *phasemobf;    /* Phase mobility per face */
-    double *voldiscr;     /* Volume discrepancy per cell */
+    /**
+     * Pressure and mass-dependent fluid matrix that converts phase volumes at
+     * reservoir conditions into component volumes at surface conditions.  Obeys
+     * the defining formula
+     * \f[
+     * A = RB^{-1}
+     * \f]
+     * in which \f$R\f$ denotes the miscibility ratios (i.e., the dissolved
+     * gas-oil ratio, \f$R_s\f$ and the evaporated oil-gas ratio, \f$R_v\f$)
+     * collected as a matrix and \f$B\f$ is the diagonal matrix of
+     * formation-volume expansion factors.  The function is sampled in each grid
+     * cell.  Array of size <CODE>nphases * nphases * nc</CODE>.
+     */
+    double *Ac;
+
+    /**
+     * Derivative of \f$A\f$ with respect to pressure,
+     * \f[
+     * \frac{\partial A}{\partial p} = \frac{\partial R}{\partial p}B^{-1} +
+     * R\frac{\partial B^{-1}}{\partial p} = (\frac{\partial R}{\partial p} -
+     * A\frac{\partial B}{\partial p})B^{-1}
+     * \f]
+     * sampled in each grid cell.  Array of size
+     * <CODE>nphases * nphases * nc</CODE>.
+     */
+    double *dAc;
+
+    /**
+     * Fluid matrix sampled at each interface.  Possibly as a result of an
+     * upwind calculation.  Array of size <CODE>nphases * nphases * nf</CODE>.
+     */
+    double *Af;
+
+    /**
+     * Phase mobility per interface.  Possibly defined through an upwind
+     * calculation.  Array of size <CODE>nphases * nf</CODE>.
+     */
+    double *phasemobf;
+
+    /**
+     * Deceptively named "volume-discrepancy" term.  Array of size @c nc.
+     * Unused by the cfs_tpfa_residual module.
+     */
+    double *voldiscr;
 };
 
+
+/**
+ * Create management structure capable of storing derived fluid quantities
+ * pertaining to a reservoir model of a particular size.
+ *
+ * The resources acquired using function compr_quantities_gen_allocate() must
+ * be released using the destructor function compr_quantities_gen_deallocate().
+ *
+ * @param[in] nc Number of grid cells
+ * @param[in] nf Number of grid interfaces
+ * @param[in] np Number of fluid phases (and components)
+ *
+ * @return Fully formed management structure.  Returns @c NULL in case of
+ * allocation failure.
+ */
 struct compr_quantities_gen *
 compr_quantities_gen_allocate(size_t nc, size_t nf, int np);
 
+
+/**
+ * Release resources acquired in a previous call to constructor function
+ * compr_quantities_gen_allocate().
+ *
+ * Note that
+ * <CODE>
+ * compr_quantities_gen_deallocate(NULL)
+ * </CODE>
+ * is supported and benign (i.e., this statement behaves as
+ * <CODE>free(NULL)</CODE>).
+ *
+ * @param[in,out] cq On input - compressible quantity management structure
+ * obtained through a previous call to construction function
+ * compr_quantities_gen_allocate().  On output - invalid pointer.
+ */
 void
 compr_quantities_gen_deallocate(struct compr_quantities_gen *cq);