Line data    Source code

       1             : //* This file is part of the MOOSE framework
       2             : //* https://mooseframework.inl.gov
       3             : //*
       4             : //* All rights reserved, see COPYRIGHT for full restrictions
       5             : //* https://github.com/idaholab/moose/blob/master/COPYRIGHT
       6             : //*
       7             : //* Licensed under LGPL 2.1, please see LICENSE for details
       8             : //* https://www.gnu.org/licenses/lgpl-2.1.html
       9             : 
      10             : #pragma once
      11             : 
      12             : #include "DiscreteElementUserObject.h"
      13             : 
      14             : /**
      15             :  * Base class for capillary pressure for multiphase flow in porous media. To implement
      16             :  * an effective saturation formulation, override effectiveSaturation() and derivatives.
      17             :  * To implement a capillary pressure curve that will include the logarithmic extension,
      18             :  * override capillaryPressureCurve() and derivatives.
      19             :  *
      20             :  * Note: Capillary pressure is calculated as a function of true saturation, not
      21             :  * effective saturation (saturation minus residual). Derivatives are returned wrt
      22             :  * true saturation, so no scaling of them is required in objects using these methods.
      23             :  *
      24             :  * Includes an optional logarithmic extension in the low saturation region where
      25             :  * capillary pressure can go to infinity as saturation tends to 0. Calculation of
      26             :  * logarithmic extension from Webb, A simple extension of two-phase characteristic
      27             :  * curves to include the dry region, Water Resources Research 36, 1425-1430 (2000)
      28             :  * The logarithmic extension is only computed for qp=0.  If your overriding class
      29             :  * has no qp dependence (capillary pressure is a function only of saturation, for
      30             :  * example) then no changes are required.  Otherwise, if you use log_extension,
      31             :  * you will have to modify this base class to correctly calculate the log-extension
      32             :  * parameters at each quadpoint.
      33             :  */
      34             : class PorousFlowCapillaryPressure : public DiscreteElementUserObject
      35             : {
      36             : public:
      37             :   static InputParameters validParams();
      38             : 
      39             :   PorousFlowCapillaryPressure(const InputParameters & parameters);
      40             : 
      41           0 :   virtual void initialize() final{};
      42             :   virtual void initialSetup() override;
      43             : 
      44             :   /**
      45             :    * Capillary pressure is calculated as a function of true saturation. Note that this
      46             :    * method includes the ability to use a logarithmic extension at low saturation.
      47             :    * @param saturation true saturation
      48             :    * @param qp quadpoint to use (when capillary-pressure depends on coupled variables, not just
      49             :    * saturation)
      50             :    * @return capillary pressure (Pa)
      51             :    */
      52             :   virtual Real capillaryPressure(Real saturation, unsigned qp = 0) const;
      53             :   virtual ADReal capillaryPressure(const ADReal & saturation, unsigned qp = 0) const;
      54             : 
      55             :   /**
      56             :    * Derivative of capillary pressure wrt true saturation
      57             :    * @param saturation true saturation
      58             :    * @param qp quadpoint to use (when capillary-pressure depends on coupled variables, not just
      59             :    * saturation)
      60             :    * @return derivative of capillary pressure with respect to true saturation
      61             :    */
      62             :   virtual Real dCapillaryPressure(Real saturation, unsigned qp = 0) const;
      63             :   virtual ADReal dCapillaryPressure(const ADReal & saturation, unsigned qp = 0) const;
      64             : 
      65             :   /**
      66             :    * Second derivative of capillary pressure wrt true saturation
      67             :    * @param saturation true saturation
      68             :    * @param qp quadpoint to use (when capillary-pressure depends on coupled variables, not just
      69             :    * saturation)
      70             :    * @return second derivative of capillary pressure with respect to true saturation
      71             :    */
      72             :   virtual Real d2CapillaryPressure(Real saturation, unsigned qp = 0) const;
      73             : 
      74             :   /**
      75             :    * Effective saturation as a function of capillary pressure
      76             :    * @param pc capillary pressure (Pa)
      77             :    * @param qp quadpoint to use (when effective saturation depends on coupled variables, not just
      78             :    * pc)
      79             :    * @return effective saturation
      80             :    */
      81             :   virtual Real effectiveSaturation(Real pc, unsigned qp = 0) const = 0;
      82             : 
      83             :   /**
      84             :    * Derivative of effective saturation wrt capillary pressure
      85             :    * @param pc capillary pressure (Pa)
      86             :    * @param qp quadpoint to use (when effective saturation depends on coupled variables, not just
      87             :    * pc)
      88             :    * @return derivative of effective saturation wrt capillary pressure
      89             :    */
      90             :   virtual Real dEffectiveSaturation(Real pc, unsigned qp = 0) const = 0;
      91             : 
      92             :   /**
      93             :    * Second derivative of effective saturation wrt capillary pressure
      94             :    * @param pc capillary pressure
      95             :    * @param qp quadpoint to use (when effective saturation depends on coupled variables, not just
      96             :    * pc)
      97             :    * @return second derivative of effective saturation wrt capillary pressure
      98             :    */
      99             :   virtual Real d2EffectiveSaturation(Real pc, unsigned qp = 0) const = 0;
     100             : 
     101             :   /**
     102             :    * Saturation as a function of capillary pressure
     103             :    * @param pc capillary pressure (Pa)
     104             :    * @param qp quadpoint to use (when saturation depends on coupled variables, not just
     105             :    * pc)
     106             :    * @return saturation
     107             :    */
     108             :   Real saturation(Real pc, unsigned qp = 0) const;
     109             :   ADReal saturation(const ADReal & pc, unsigned qp = 0) const;
     110             : 
     111             :   /**
     112             :    * Derivative of saturation wrt capillary pressure
     113             :    * @param pc capillary pressure (Pa)
     114             :    * @param qp quadpoint to use (when saturation depends on coupled variables, not just
     115             :    * pc)
     116             :    * @return derivative of saturation wrt capillary pressure
     117             :    */
     118             :   Real dSaturation(Real pc, unsigned qp = 0) const;
     119             :   ADReal dSaturation(const ADReal & pc, unsigned int qp = 0) const;
     120             : 
     121             :   /**
     122             :    * Second derivative of saturation wrt capillary pressure
     123             :    * @param pc capillary pressure
     124             :    * @param qp quadpoint to use (when saturation depends on coupled variables, not just
     125             :    * pc)
     126             :    * @return second derivative of saturation wrt capillary pressure
     127             :    */
     128             :   Real d2Saturation(Real pc, unsigned qp = 0) const;
     129             : 
     130             : protected:
     131             :   /**
     132             :    * Effective saturation of liquid phase given liquid saturation and residual
     133             :    * liquid saturation.
     134             :    * Note: not to be mistaken with effectiveSaturation(pc) which is a function
     135             :    * of capillary pressure.
     136             :    * @param saturation true saturation
     137             :    * @return effective saturation
     138             :    */
     139             :   Real effectiveSaturationFromSaturation(Real saturation) const;
     140             : 
     141             :   /**
     142             :    * Calculates the saturation where the logarithmic extension to capillary
     143             :    * pressure meets the raw curve using Newton's method.
     144             :    * This implementation assumes capillary-pressure is a function of saturation
     145             :    * only, and not any other quad-point dependent quantities
     146             :    *
     147             :    * @return saturation where logarithmic extension begins
     148             :    */
     149             :   Real extensionSaturation() const;
     150             : 
     151             :   /**
     152             :    * Calculates the saturation where the logarithmic extension to capillary
     153             :    * pressure at low saturation.  This is computed for qp=0 only.
     154             :    * This implementation assumes capillary-pressure is a function of saturation
     155             :    * only, and not any other quad-point dependent quantities
     156             :    *
     157             :    * @param s effective saturation
     158             :    * @return capillary pressure function in the logarithmic extension
     159             :    */
     160             :   Real interceptFunction(Real s) const;
     161             : 
     162             :   /**
     163             :    * Calculates the saturation where the logarithmic extension to capillary
     164             :    * pressure at low saturation.
     165             :    * This implementation assumes capillary-pressure is a function of saturation
     166             :    * only, and not any other quad-point dependent quantities
     167             :    *
     168             :    * @param s effective saturation
     169             :    * @return derivative of logarithmic extension function
     170             :    */
     171             :   Real interceptFunctionDeriv(Real s) const;
     172             : 
     173             :   /**
     174             :    * The capillary pressure in the logarithmic extension
     175             :    * This implementation assumes capillary-pressure is a function of saturation
     176             :    * only, and not any other quad-point dependent quantities
     177             :    *
     178             :    * @param s liquid saturation
     179             :    * @return capillary pressure in logarithmic extension
     180             :    */
     181             :   Real capillaryPressureLogExt(Real s) const;
     182             : 
     183             :   /**
     184             :    * The derivative of capillary pressure in the logarithmic extension
     185             :    * This implementation assumes capillary-pressure is a function of saturation
     186             :    * only, and not any other quad-point dependent quantities
     187             :    *
     188             :    * @param s liquid saturation
     189             :    * @return derivative of capillary pressure in logarithmic extension
     190             :    */
     191             :   Real dCapillaryPressureLogExt(Real s) const;
     192             : 
     193             :   /**
     194             :    * The second derivative of capillary pressure in the logarithmic extension
     195             :    * This implementation assumes capillary-pressure is a function of saturation
     196             :    * only, and not any other quad-point dependent quantities
     197             :    *
     198             :    * @param s liquid saturation
     199             :    * @return second derivative of capillary pressure in logarithmic extension
     200             :    */
     201             :   Real d2CapillaryPressureLogExt(Real s) const;
     202             : 
     203             :   /**
     204             :    * Raw capillary pressure curve (does not include logarithmic extension)
     205             :    * @param saturation true saturation
     206             :    * @return capillary pressure (Pa)
     207             :    */
     208             :   virtual Real capillaryPressureCurve(Real saturation, unsigned qp = 0) const = 0;
     209             : 
     210             :   /**
     211             :    * Derivative of raw capillary pressure wrt true saturation
     212             :    * @param saturation true saturation
     213             :    * @return derivative of capillary pressure with respect to true saturation
     214             :    */
     215             :   virtual Real dCapillaryPressureCurve(Real saturation, unsigned qp = 0) const = 0;
     216             : 
     217             :   /**
     218             :    * Second derivative of raw capillary pressure wrt true saturation
     219             :    * @param saturation true saturation
     220             :    * @return second derivative of capillary pressure with respect to true saturation
     221             :    */
     222             :   virtual Real d2CapillaryPressureCurve(Real saturation, unsigned qp = 0) const = 0;
     223             : 
     224             :   /// Liquid residual saturation
     225             :   const Real _sat_lr;
     226             :   /// Derivative of effective saturation with respect to saturation
     227             :   const Real _dseff_ds;
     228             :   /// Flag to use a logarithmic extension for low saturation
     229             :   bool _log_ext;
     230             :   /// Maximum capillary pressure (Pa). Note: must be <= 0
     231             :   const Real _pc_max;
     232             : 
     233             :   /**
     234             :    * Saturation where the logarithmic extension meets the raw curve
     235             :    * This is computed only for qp=0.
     236             :    */
     237             :   Real _sat_ext;
     238             :   /**
     239             :    * Capillary pressure where the extension meets the raw curve.
     240             :    * This is computed only for qp=0.
     241             :    */
     242             :   Real _pc_ext;
     243             :   /**
     244             :    * Gradient of the logarithmic extension
     245             :    * This is computed only for qp=0.
     246             :    */
     247             :   Real _slope_ext;
     248             :   /// log(10)
     249             :   const Real _log10;
     250             : };