/*---------------------------------------------------------------------------*\
  ==  == ====== ====   ====    |
                    \\     ||  | Multiphase Code Repository by HZDR
  ======   //   ||  || ===//   | Website: https://doi.org/10.14278/rodare.767
  ||  ||  //    ||  // || \\   | License: GPL-3.0-or-later
  ==  == ====== ====   ==  ==  |
-------------------------------------------------------------------------------
License
    This file is part of the Multiphase Code Repository by HZDR.

    Copyright (C) 2025 by Helmholtz-Zentrum Dresden-Rossendorf e.V. (HZDR),
    Website: https://hzdr.de

    Multiphase Code Repository by HZDR is based on the free software for
    computational fluid dynamics (CFD) from the OpenFOAM Foundation.
    Copyright (C) 2025 by OpenFOAM Foundation, Website: https://openfoam.org

    If you are interested in which files are original OpenFOAM Foundation
    files, which OpenFOAM Foundation files were modified, and which files were
    newly created, see FILES.md.

    Multiphase Code Repository by HZDR is free software: you can redistribute
    it and/or modify it under the terms of the GNU General Public License as
    published by the Free Software Foundation, either version 3 of the
    License, or (at your option) any later version.

    Multiphase Code Repository by HZDR is distributed in the hope that it will
    be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with the Multiphase Code Repository by HZDR. If not, see
    <http://www.gnu.org/licenses/>.

Class
    Foam::shearUnderResolution

Description
    The under-resolution indicator function \f$f_\mathrm{UR}\f$ as proposed by
    Meller et al. (2023) is calculated based on the shear stress, similarly to
    dimensionless wall distance in wall-bounded flows, which is expressed in
    terms of y+. It returns values between 0 (resolved flow) and 1 (unresolved
    flow).

    Reference:
    \verbatim
        Meller, R., Tekavcic, M., Krull, B., & Schlegel, F. (2023).
        Momentum exchange modeling for coarsely resolved interfaces in a
        multifield two‐fluid model.
        International Journal for Numerical Methods in Fluids, 95(9), 1521-1545.
    \endverbatim

    For this purpose three information need to be determined:

      1. velocity \f$\mathbf{U}_1\f$ of phase 1 at the side of the interface,
         where this phase is actually present,

      2. same for velocity \f$\mathbf{U}_2\f$

      3. pairwise gradient vector \f$\mathbf{n}_{12}\f$.

    All three information are transported across the interface from cell to cell
    in several iterations following the negative gradient of \f$\alpha_1\f$,
    \f$\alpha_2\f$ and \f$|\mathbf{n}_{12,\mathrm{loc}}|\f$, respectively.

    The pairwise gradient vector is locally defined as
    \f[
        \mathbf{n}_{12,\mathrm{loc}} =
            \alpha_2 \nabla \alpha_1 - \alpha_1 \nabla \alpha_2.
    \f]

    The relative interface velocity is calculated as
    \f[
        \mathbf{U}_\mathrm{r} = \mathbf{U}_2 - \mathbf{U}_1.
    \f]

    From those information the shear indicator is determined as
    \f[
        f_\mathrm{shear} =
            \frac{\mathbf{U}_\mathrm{r} \times \mathbf{n}_{12,\mathrm{loc}}}
                 {\left|\mathbf{U}_r\right|
                  \left|\mathbf{n}_{12,\mathrm{loc}}\right|}.
    \f]
    with the local formulation of the interface normal vector
    \f$\mathbf{n}_{12,\mathrm{loc}}\f$. The shear indicator is bounded between
    one for a pure shear flow and zero for a pure stagnation flow.

    The dimensionless thickness of the interface layer based on shear stress is
    \f[
        y^+_{12} = \frac{1/\left|\mathbf{n}_{12}\right|}{L^*_{12}},
    \f]
    \f[
        L^*_{12} = \frac{\nu_{12}}{u^*_{12}},
    \f]
    \f[
        \nu_{12} = \frac{\nu_1 + \nu_2}{2},
    \f]
    \f[
        u^*_{12} =
            \sqrt{\nu_{12} |(\mathbf{U}_\mathrm{r} \times \mathbf{n}_{12})|}.
    \f]

    Subsequently, the indicator function is determined as
    \f[
        f_\mathrm{UR} =
            f_\mathrm{shear}\,\mathit{max}(\mathit{min}(F(y^+_{12}), 1), 0)
    \f]
    with the user-defined transfer function \f$F(y^+_{12})\f$. Finally, the
    indicator field is smoothed once.

    Example usage for exponential transfer function according to
    Meller et al. (2023):
    \verbatim
    underResolution
    {
        airC_water
        {
            type                shear;
            nLayers             5;
            nCorrectors         3;
            interfaceRoughness  false;

            func                coded;
            name                underResolutionTransferFunction;

            code
            #{
                return 1.0 - exp(1.0 - x);
            #};
        }
    }
    \endverbatim

    Example usage for linear transition between \f$y^+_{12} = 30\f$ and
    \f$100\f$:
    \verbatim
    underResolution
    {
        airC_water
        {
            type                shear;
            nLayers             5;
            nCorrectors         3;
            interfaceRoughness  false;

            func                table;
            values              2
            (
                ( 30 0)
                (100 1)
            );
        }
    }
    \endverbatim

Usage
    \table
        Property| Description                        | Required| Default value
        func    | Transfer function via Function1    | yes     | -
        interfaceRoughness| whether to consider rough interfaces | no | no
        nCorrectors | number of corrector loops for shear stress | no | 3
        nLayers | maximum number of interfacial cells            | no | 5
    \endtable

See also
    Foam::ResolvedPhaseSystem

SourceFiles
    shearUnderResolution.C

\*---------------------------------------------------------------------------*/

#ifndef shearUnderResolution_H
#define shearUnderResolution_H

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

#include "underResolutionModel.H"
#include "Function1.H"

namespace Foam
{
namespace underResolutionModels
{

/*---------------------------------------------------------------------------*\
                    Class shearUnderResolution Declaration
\*---------------------------------------------------------------------------*/

class shearUnderResolution
:
    public underResolutionModel
{
    // Private Data

        //- Transfer function from yPlus towards under resolution indicator
        autoPtr<Function1<scalar>> func_;


    // Private Member Functions

        //- Shared kinematic viscosity
        tmp<volScalarField> nuI() const;

        //- Indicator for flow type at interface:
        //  pure shear flow (1), pure stagnation flow (0) or in between
        tmp<volScalarField> shearInterface() const;

        //- Dimensionless interface thickness in terms of viscous units
        tmp<volScalarField> yPlusI() const;


public:

    //- Runtime type information
    TypeName("shear");


    // Constructors

        //- Construct from a dictionary and an interface
        shearUnderResolution
        (
            const dictionary& dict,
            const phaseInterface& interface,
            const bool registerObject
        );


    //- Destructor
    virtual ~shearUnderResolution();


    // Member Functions

        //- Correct under resolution factor
        virtual void correct();
};


// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

} // End namespace shearUnderResolution
} // End namespace Foam

// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

#endif

// ************************************************************************* //
