ENH: support 'if-present' handling of relaxation coefficients

- new

  scalar relaxCoeff = 0;
  if (solution().relaxEquation(name, relaxCoeff))
  {
      relax(relaxCoeff);
  }

  // or
  scalar relaxCoeff = 0;
  solution().relaxEquation(name, relaxCoeff);

- old

  if (solution().relaxEquation(name))
  {
      relax(solution().equationRelaxationFactor(name));
  }

  // or
  scalar relaxCoeff = 0;
  if (solution().relaxEquation(name))
  {
      relaxCoeff = solution().equationRelaxationFactor(name);
  }

src/OpenFOAM/fields/GeometricFields/GeometricField/GeometricField.C

@@ -1158,9 +1158,11 @@ void Foam::GeometricField<Type, PatchField, GeoMesh>::relax()
         name += "Final";
     }
 
-    if (this->mesh().relaxField(name))
+    scalar relaxCoeff = 1;
+
+    if (this->mesh().relaxField(name, relaxCoeff))
     {
-        relax(this->mesh().fieldRelaxationFactor(name));
+        relax(relaxCoeff);
     }
 }
 

src/OpenFOAM/matrices/solution/solution.C

@@ -325,59 +325,91 @@ bool Foam::solution::relaxEquation(const word& name) const
 }
 
 
-Foam::scalar Foam::solution::fieldRelaxationFactor(const word& name) const
+bool Foam::solution::relaxField(const word& name, scalar& factor) const
 {
-    DebugInfo<< "Lookup variable relaxation factor for " << name << endl;
+    DebugInfo<< "Lookup field relaxation factor for " << name << endl;
 
     if (fieldRelaxDict_.found(name))
     {
-        return Function1<scalar>::New
+        factor = Function1<scalar>::New
         (
             fieldRelaxCache_,  // cache
             name,
             fieldRelaxDict_,
             keyType::REGEX
         )().value(time().timeOutputValue());
+
+        return true;
     }
-    else if (fieldRelaxDefault_)
+    else if (fieldRelaxDict_.found("default") && fieldRelaxDefault_)
     {
-        return fieldRelaxDefault_().value(time().timeOutputValue());
+        factor = fieldRelaxDefault_->value(time().timeOutputValue());
+        return true;
     }
 
-    FatalIOErrorInFunction(fieldRelaxDict_)
+    // Fallthrough - nothing found
-        << "Cannot find variable relaxation factor for '" << name
+    return false;
-        << "' or a suitable default value." << nl
-        << exit(FatalIOError);
-
-    return 0;
 }
 
 
-Foam::scalar Foam::solution::equationRelaxationFactor(const word& name) const
+bool Foam::solution::relaxEquation(const word& name, scalar& factor) const
 {
     DebugInfo<< "Lookup equation relaxation factor for " << name << endl;
 
     if (eqnRelaxDict_.found(name))
     {
-        return Function1<scalar>::New
+        factor = Function1<scalar>::New
         (
             eqnRelaxCache_,  // cache
             name,
             eqnRelaxDict_,
             keyType::REGEX
         )().value(time().timeOutputValue());
+
+        return true;
     }
-    else if (eqnRelaxDefault_)
+    else if (eqnRelaxDict_.found("default") && eqnRelaxDefault_)
     {
-        return eqnRelaxDefault_().value(time().timeOutputValue());
+        factor = eqnRelaxDefault_->value(time().timeOutputValue());
+        return true;
     }
 
-    FatalIOErrorInFunction(eqnRelaxDict_)
+    // Fallthrough - nothing found
-        << "Cannot find equation relaxation factor for '" << name
+    return false;
-        << "' or a suitable default value."
+}
-        << exit(FatalIOError);
 
-    return 0;
+
+Foam::scalar Foam::solution::fieldRelaxationFactor(const word& name) const
+{
+    // Any initial value
+    scalar factor = 0;
+
+    if (!relaxField(name, factor))
+    {
+        FatalIOErrorInFunction(fieldRelaxDict_)
+            << "Cannot find field relaxation factor for '" << name
+            << "' or a suitable default value." << nl
+            << exit(FatalIOError);
+    }
+
+    return factor;
+}
+
+
+Foam::scalar Foam::solution::equationRelaxationFactor(const word& name) const
+{
+    // Any initial value
+    scalar factor = 0;
+
+    if (!relaxEquation(name, factor))
+    {
+        FatalIOErrorInFunction(eqnRelaxDict_)
+            << "Cannot find equation relaxation factor for '" << name
+            << "' or a suitable default value."
+            << exit(FatalIOError);
+    }
+
+    return factor;
 }
 
 

src/OpenFOAM/matrices/solution/solution.H

@@ -192,13 +192,29 @@ public:
         //- True if the relaxation factor is given for the field
         bool relaxField(const word& name) const;
 
+        //- Get the relaxation factor specified for the field
+        //- or the specified "default" entry, if present.
+        //- Does not change \p factor if neither direct nor "default"
+        //- can be used,
+        //  \return True if found
+        bool relaxField(const word& name, scalar& factor) const;
+
         //- True if the relaxation factor is given for the equation
         bool relaxEquation(const word& name) const;
 
-        //- The relaxation factor for the given field
+        //- Get the relaxation factor specified for the equation
+        //- or the specified "default" entry, if present.
+        //- Does not change \p factor if neither direct nor "default"
+        //- can be used,
+        //  \return True if found
+        bool relaxEquation(const word& name, scalar& factor) const;
+
+        //- Get the relaxation factor for the given field.
+        //- Fatal if not found.
         scalar fieldRelaxationFactor(const word& name) const;
 
-        //- The relaxation factor for the given equation
+        //- Get the relaxation factor for the given equation.
+        //- Fatal if not found.
         scalar equationRelaxationFactor(const word& name) const;
 
         //- The entire dictionary or the optional "select" sub-dictionary.

src/finiteArea/faMatrices/faMatrix/faMatrix.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2016-2017 Wikki Ltd
-    Copyright (C) 2019-2022 OpenCFD Ltd.
+    Copyright (C) 2019-2023 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -595,15 +595,16 @@ void Foam::faMatrix<Type>::relax(const scalar alpha)
 template<class Type>
 void Foam::faMatrix<Type>::relax()
 {
-    if (psi_.mesh().relaxEquation(psi_.name()))
+    scalar relaxCoeff = 0;
+
+    if (psi_.mesh().relaxEquation(psi_.name(), relaxCoeff))
     {
-        relax(psi_.mesh().equationRelaxationFactor(psi_.name()));
+        relax(relaxCoeff);
     }
     else
     {
         DebugInFunction
-            << "Relaxation factor for field " << psi_.name()
+            << "No relaxation specified for field " << psi_.name() << nl;
-            << " not found.  Relaxation will not be used." << endl;
     }
 }
 

src/finiteVolume/finiteVolume/fvc/fvcCorrectAlpha.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2017 OpenCFD Ltd.
+    Copyright (C) 2017-2023 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -61,10 +61,7 @@ tmp<GeometricField<scalar, fvsPatchField, surfaceMesh>> alphaCorr
     const word fieldName = U.select(finalIter);
 
     scalar alpha = 1;
-    if (mesh.relaxEquation(fieldName))
+    mesh.relaxEquation(fieldName, alpha);
-    {
-        alpha = mesh.equationRelaxationFactor(fieldName);
-    }
 
     return
         (1 - alpha)

src/finiteVolume/finiteVolume/gradSchemes/iterativeGaussGrad/iterativeGaussGrad.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2021 OpenCFD Ltd.
+    Copyright (C) 2021-2023 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -60,6 +60,10 @@ Foam::fv::iterativeGaussGrad<Type>::calcGrad
 
     const skewCorrectionVectors& skv = skewCorrectionVectors::New(vsf.mesh());
 
+    scalar relax = 1;
+    const bool useRelax =
+        vsf.mesh().relaxField("grad(" + vsf.name() + ")", relax);
+
     for (label i = 0; i < nIter_; ++i)
     {
         tmp<GradSurfFieldType> tsgGrad = linearInterpolate(gGrad);
@@ -68,11 +72,8 @@ Foam::fv::iterativeGaussGrad<Type>::calcGrad
 
         tcorr.ref().dimensions().reset(vsf.dimensions());
 
-        if (vsf.mesh().relaxField("grad(" + vsf.name() + ")"))
+        if (useRelax)
         {
-            const scalar relax =
-                vsf.mesh().fieldRelaxationFactor("grad(" + vsf.name() + ")");
-
             // relax*prediction + (1-relax)*old
             gGrad *= (1.0 - relax);
             gGrad += relax*fv::gaussGrad<Type>::gradf(tcorr + ssf, name);

src/finiteVolume/fvMatrices/fvMatrix/fvMatrix.C

@@ -1260,9 +1260,11 @@ void Foam::fvMatrix<Type>::relax()
         psi_.mesh().data().isFinalIteration()
     );
 
-    if (psi_.mesh().relaxEquation(name))
+    scalar relaxCoeff = 0;
+
+    if (psi_.mesh().relaxEquation(name, relaxCoeff))
     {
-        relax(psi_.mesh().equationRelaxationFactor(name));
+        relax(relaxCoeff);
     }
 }
 

src/functionObjects/field/age/age.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2018-2021 OpenFOAM Foundation
-    Copyright (C) 2021 OpenCFD Ltd.
+    Copyright (C) 2021-2023 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -173,10 +173,7 @@ bool Foam::functionObjects::age::execute()
 
     // Set under-relaxation coeff
     scalar relaxCoeff = 0;
-    if (mesh_.relaxEquation(schemesField_))
+    mesh_.relaxEquation(schemesField_, relaxCoeff);
-    {
-        relaxCoeff = mesh_.equationRelaxationFactor(schemesField_);
-    }
 
     Foam::fv::options& fvOptions(Foam::fv::options::New(mesh_));
 

src/functionObjects/solvers/energyTransport/energyTransport.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2017-2022 OpenCFD Ltd.
+    Copyright (C) 2017-2023 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -371,11 +371,8 @@ bool Foam::functionObjects::energyTransport::execute()
     );
 
     // Set under-relaxation coeff
-    scalar relaxCoeff = 0.0;
+    scalar relaxCoeff = 0;
-    if (mesh_.relaxEquation(schemesField_))
+    mesh_.relaxEquation(schemesField_, relaxCoeff);
-    {
-        relaxCoeff = mesh_.equationRelaxationFactor(schemesField_);
-    }
 
     if (phi.dimensions() == dimMass/dimTime)
     {

src/functionObjects/solvers/scalarTransport/scalarTransport.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2012-2017 OpenFOAM Foundation
-    Copyright (C) 2015-2022 OpenCFD Ltd.
+    Copyright (C) 2015-2023 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -263,11 +263,8 @@ bool Foam::functionObjects::scalarTransport::execute()
     word laplacianScheme("laplacian(" + D.name() + "," + schemesField_ + ")");
 
     // Set under-relaxation coeff
-    scalar relaxCoeff = 0.0;
+    scalar relaxCoeff = 0;
-    if (mesh_.relaxEquation(schemesField_))
+    mesh_.relaxEquation(schemesField_, relaxCoeff);
-    {
-        relaxCoeff = mesh_.equationRelaxationFactor(schemesField_);
-    }
 
     // Two phase scalar transport
     if (phaseName_ != "none")