diff --git a/opm/core/pressure/tpfa/cfs_tpfa_residual.h b/opm/core/pressure/tpfa/cfs_tpfa_residual.h index 5eddeed6..368cce10 100644 --- a/opm/core/pressure/tpfa/cfs_tpfa_residual.h +++ b/opm/core/pressure/tpfa/cfs_tpfa_residual.h @@ -25,6 +25,37 @@ #include +/** + * \file + * Public interface to assembler for (compressible) discrete pressure system + * based on two-point flux approximation method. The assembler implements a + * residual formulation that for a single cell \f$i\f$ reads + * \f[ + * \mathit{pv}_i\cdot (1 - \sum_\alpha A_i^{-1}(p^{n+1},z^n)z^n) + + * \Delta t\sum_\alpha A_i^{-1}(p^{n+1},z^n) \Big(\sum_j A_{ij}v_{ij}^{n+1} - + * q_i^{n+1}\Big) = 0 + * \f] + * in which \f$\mathit{pv}_i\f$ is the (constant or pressure-dependent) + * pore-volume of cell \f$i\f$. Moreover, \f$\Delta t\f$ is the time step size, + * \f$n\f$ denotes the time level, \f$A\f$ is the pressure and mass-dependent + * fluid matrix that converts phase volumes at reservoir conditions into + * component volumes at surface conditions and \f$v_{ij}\f$ is the vector of + * outward (with respect to cell \f$i\f$) phase fluxes across the \f$ij\f$ + * cell-interface. + * + * This module's usage model is intended to be + * -# Construct assembler + * -# for (each time step) + * -# while (pressure not converged) + * -# Assemble appropriate (Jacobian) system of linear equations + * -# Solve Jacobian system to derive pressure increments + * -# Include increments into current state + * -# Check convergence + * -# Derive fluxes and, optionally, interface pressures + * -# Solve transport by some means + * -# Destroy assembler + */ + #ifdef __cplusplus extern "C" { #endif @@ -33,36 +64,121 @@ struct cfs_tpfa_res_impl; struct CSRMatrix; struct compr_quantities_gen; +/** + * Type encapsulating well topology and completion data (e.g., phase mobilities + * per connection (perforation)). + */ struct cfs_tpfa_res_wells { + /** + * All wells pertaining to a particular linear system assembly. + * Must include current controls/targets and complete well topology. + */ struct Wells *W ; + + /** + * Completion data describing the fluid state at the current time level. + */ struct CompletionData *data; }; + +/** + * Type encapsulating all driving forces affecting the discrete pressure system. + */ struct cfs_tpfa_res_forces { - struct cfs_tpfa_res_wells *wells; - struct compr_src *src ; + struct cfs_tpfa_res_wells *wells; /**< Wells */ + struct compr_src *src ; /**< Explicit source terms */ }; + +/** + * Result structure that presents the fully assembled system of linear + * equations, linearised around the current pressure point. + */ struct cfs_tpfa_res_data { - struct CSRMatrix *J; - double *F; + struct CSRMatrix *J; /**< Jacobian matrix */ + double *F; /**< Residual vector (right-hand side) */ - struct cfs_tpfa_res_impl *pimpl; + struct cfs_tpfa_res_impl *pimpl; /**< Internal management structure */ }; +/** + * Construct assembler for system of linear equations. + * + * @param[in] G Grid + * @param[in] wells Well description. @c NULL in case of no wells. + * For backwards compatibility, the constructor also + * interprets (wells != NULL) && + * (wells->W == NULL) as "no wells present", but new + * code should use wells == NULL to signify + * "no wells". + * @param[in] nphases Number of active fluid phases in this simulation run. + * Needed to correctly size various internal work arrays. + * @return Fully formed assembler structure suitable for forming systems of + * linear equations using, e.g., function cfs_tpfa_res_assemble(). @c NULL in + * case of allocation failure. Must be destroyed using function + * cfs_tpfa_res_destroy(). + */ struct cfs_tpfa_res_data * cfs_tpfa_res_construct(struct UnstructuredGrid *G , struct cfs_tpfa_res_wells *wells , int nphases); + +/** + * Destroy assembler for system of linear equations. + * + * Disposes of all resources acquired in a previous call to construction + * function cfs_tpfa_res_construct(). Note that the statement + * + * cfs_tpfa_res_destroy(NULL) + * + * is supported and benign (i.e., behaves like free(NULL)). + * + * @param[in,out] h On input - assembler obtained through a previous call to + * construction function cfs_tpfa_res_construct(). On output - invalid pointer. + */ void cfs_tpfa_res_destroy(struct cfs_tpfa_res_data *h); -/* Return value is 1 if the assembled matrix was adjusted to remove a - singularity. This happens if all fluids are incompressible and - there are no pressure conditions on wells or boundaries. - Otherwise return 0. */ + +/** + * Assemble system of linear equations by linearising the residual around the + * current pressure point. Assume incompressible rock (i.e., that the + * pore-volume is independent of pressure). + * + * The fully assembled system is presented in h->J and + * h->F and must be solved separately using external software. + * + * @param[in] G Grid. + * @param[in] dt Time step size \f$\Delta t\f$. + * @param[in] forces Driving forces. + * @param[in] zc Component volumes, per pore-volume, at surface + * conditions for all components in all cells stored + * consecutively per cell. Array of size + * G->number_of_cells * cq->nphases. + * @param[in] cq Compressible quantities describing the current fluid + * state. Fields @c Ac, @c dAc, @c Af, and + * @c phasemobf must be valid. + * @param[in] trans Background transmissibilities as defined by function + * tpfa_trans_compute(). + * @param[in] gravcap_f Discrete gravity and capillary forces. + * @param[in] cpress Cell pressures. One scalar value per grid cell. + * @param[in] wpress Well (bottom-hole) pressures. One scalar value per + * well. @c NULL in case of no wells. + * @param[in] porevol Pore-volumes. One (positive) scalar value for each + * grid cell. + * @param[in,out] h On input-a valid (non-@c NULL) assembler obtained + * from a previous call to constructor function + * cfs_tpfa_res_construct(). On output-valid assembler + * that includes the new system of linear equations in + * its @c J and @c F fields. + * + * @return 1 if the assembled matrix was adjusted to remove a singularity. This + * happens if all fluids are incompressible and there are no pressure conditions + * on wells or boundaries. Otherwise return 0. + */ int cfs_tpfa_res_assemble(struct UnstructuredGrid *G, double dt, @@ -76,11 +192,48 @@ cfs_tpfa_res_assemble(struct UnstructuredGrid *G, const double *porevol, struct cfs_tpfa_res_data *h); -/* Return value is 1 if the assembled matrix was adjusted to remove a - singularity. This happens if all fluids are incompressible, the - rock is incompressible, and there are no pressure conditions on - wells or boundaries. - Otherwise return 0. */ + +/** + * Assemble system of linear equations by linearising the residual around the + * current pressure point. Assume compressible rock (i.e., that the pore-volume + * depends on pressure). + * + * The fully assembled system is presented in h->J and + * h->F and must be solved separately using external software. + * + * @param[in] G Grid. + * @param[in] dt Time step size \f$\Delta t\f$. + * @param[in] forces Driving forces. + * @param[in] zc Component volumes, per pore-volume, at surface + * conditions for all components in all cells stored + * consecutively per cell. Array of size + * G->number_of_cells * cq->nphases. + * @param[in] cq Compressible quantities describing the current fluid + * state. Fields @c Ac, @c dAc, @c Af, and + * @c phasemobf must be valid. + * @param[in] trans Background transmissibilities as defined by function + * tpfa_trans_compute(). + * @param[in] gravcap_f Discrete gravity and capillary forces. + * @param[in] cpress Cell pressures. One scalar value per grid cell. + * @param[in] wpress Well (bottom-hole) pressures. One scalar value per + * well. @c NULL in case of no wells. + * @param[in] porevol Pore-volumes. One (positive) scalar value for each + * grid cell. + * @param[in] porevol0 Pore-volumes at start of time step (i.e., at time + * level \f$n\f$). One (positive) scalar value for + * each grid cell. + * @param[in] rock_comp Rock compressibility. One non-negative scalar for + * each grid cell. + * @param[in,out] h On input-a valid (non-@c NULL) assembler obtained + * from a previous call to constructor function + * cfs_tpfa_res_construct(). On output-valid assembler + * that includes the new system of linear equations in + * its @c J and @c F fields. + * + * @return 1 if the assembled matrix was adjusted to remove a singularity. This + * happens if all fluids are incompressible, the rock is incompressible, and + * there are no pressure conditions on wells or boundaries. Otherwise return 0. + */ int cfs_tpfa_res_comprock_assemble( struct UnstructuredGrid *G, @@ -97,6 +250,38 @@ cfs_tpfa_res_comprock_assemble( const double *rock_comp, struct cfs_tpfa_res_data *h); + +/** + * Derive interface (total) Darcy fluxes from (converged) pressure solution. + * + * @param[in] G Grid + * @param[in] forces Driving forces. Must correspond to those used when + * forming the system of linear equations, e.g., in the + * call to function cfs_tpfa_res_assemble(). + * @param[in] np Number of fluid phases (and components). + * @param[in] trans Background transmissibilities as defined by function + * tpfa_trans_compute(). Must correspond to equally + * named parameter of the assembly functions. + * @param[in] pmobc Phase mobilities stored consecutively per cell with + * phase index cycling the most rapidly. Array of size + * G->number_of_cells * np. + * @param[in] pmobf Phase mobilities stored consecutively per interface + * with phase index cycling the most rapidly. Array of + * size G->number_of_faces * np. + * @param[in] gravcap_f Discrete gravity and capillary forces. + * @param[in] cpress Cell pressure values. One (positive) scalar for each + * grid cell. + * @param[in] wpress Well (bottom-hole) pressure values. One (positive) + * scalar value for each well. @c NULL in case of no + * wells. + * @param[out] fflux Total Darcy interface fluxes. One scalar value for + * each interface (inter-cell connection). Array of size + * G->number_of_faces. + * @param[out] wflux Total Darcy well connection fluxes. One scalar value + * for each well connection (perforation). Array of size + * forces->wells->W->well_connpos + * [forces->wells->W->number_of_wells]. + */ void cfs_tpfa_res_flux(struct UnstructuredGrid *G , struct cfs_tpfa_res_forces *forces , @@ -110,6 +295,31 @@ cfs_tpfa_res_flux(struct UnstructuredGrid *G , double *fflux , double *wflux ); + +/** + * Derive interface pressures from (converged) pressure solution. + * + * @param[in] G Grid + * @param[in] np Number of fluid phases (and components). + * @param[in] htrans Background one-sided ("half") transmissibilities as + * defined by function tpfa_htrans_compute(). + * @param[in] pmobf Phase mobilities stored consecutively per interface + * with phase index cycling the most rapidly. Array of + * size G->number_of_faces * np. + * @param[in] gravcap_f Discrete gravity and capillary forces. + * @param[in] h System assembler. Must correspond to the assembler + * state used to form the final system of linear equations + * from which the converged pressure solution was derived. + * @param[in] cpress Cell pressure values. One (positive) scalar for each + * grid cell. + * @param[in] fflux Total Darcy interface fluxes. One scalar value for + * each interface (inter-cell connection). Array of size + * G->number_of_faces. Typically computed + * using function cfs_tpfa_res_flux(). + * @param[out] fpress Interface pressure values. One (positive) scalar for + * each interface. Array of size + * G->number_of_faces. + */ void cfs_tpfa_res_fpress(struct UnstructuredGrid *G, int np,