ENH: Added residualControl function object

- allows users to specify target maximum equation intial residuals, and
  stop the run if the conditions are achieved

src/postProcessing/functionObjects/residualControl/IOresidualControl.H

@@ -0,0 +1,49 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2010-2010 OpenCFD Ltd.
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM 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.
+
+    OpenFOAM 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 OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+Typedef
+    Foam::IOresidualControl
+
+Description
+    Instance of the generic IOOutputFilter for residualControl.
+
+\*---------------------------------------------------------------------------*/
+
+#ifndef IOresidualControl_H
+#define IOresidualControl_H
+
+#include "residualControl.H"
+#include "IOOutputFilter.H"
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+namespace Foam
+{
+    typedef IOOutputFilter<residualControl> IOresidualControl;
+}
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+#endif
+
+// ************************************************************************* //

src/postProcessing/functionObjects/residualControl/Make/files

@@ -0,0 +1,4 @@
+residualControl.C
+residualControlFunctionObject.C
+
+LIB = $(FOAM_LIBBIN)/libresidualControl

src/postProcessing/functionObjects/residualControl/Make/options

@@ -0,0 +1,9 @@
+EXE_INC = \
+    -I$(LIB_SRC)/finiteVolume/lnInclude \
+    -I$(LIB_SRC)/meshTools/lnInclude \
+    -I$(LIB_SRC)/sampling/lnInclude
+
+LIB_LIBS = \
+    -lfiniteVolume \
+    -lmeshTools \
+    -lsampling

src/postProcessing/functionObjects/residualControl/controlDict

@@ -0,0 +1,67 @@
+*--------------------------------*- C++ -*----------------------------------*\
+| =========                 |                                                 |
+| \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox           |
+|  \\    /   O peration     | Version:  1.6                                   |
+|   \\  /    A nd           | Web:      www.OpenFOAM.org                      |
+|    \\/     M anipulation  |                                                 |
+\*---------------------------------------------------------------------------*/
+FoamFile
+{
+    version     2.0;
+    format      ascii;
+    class       dictionary;
+    location    "system";
+    object      controlDict;
+}
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+application     icoFoam;
+
+startFrom       startTime;
+
+startTime       0;
+
+stopAt          endTime;
+
+endTime         0.5;
+
+deltaT          0.005;
+
+writeControl    timeStep;
+
+writeInterval   20;
+
+purgeWrite      0;
+
+writeFormat     ascii;
+
+writePrecision  6;
+
+writeCompression uncompressed;
+
+timeFormat      general;
+
+timePrecision   6;
+
+runTimeModifiable yes;
+
+
+functions
+(
+    convergenceChecks
+    {
+        type           residualControl;
+        functionObjectLibs ( "libresidualControl.so" );
+        outputControl  timeStep;
+        outputInterval 1;
+
+        maxResiduals
+        (
+            (p          5e-4)
+            (U          1e-3)
+        );
+    }
+);
+
+
+// ************************************************************************* //

src/postProcessing/functionObjects/residualControl/residualControl.C

@@ -0,0 +1,174 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2010-2010 OpenCFD Ltd.
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM 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.
+
+    OpenFOAM 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 OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+\*---------------------------------------------------------------------------*/
+
+#include "residualControl.H"
+#include "dictionary.H"
+#include "fvMesh.H"
+#include "Time.H"
+
+// * * * * * * * * * * * * * * Static Data Members * * * * * * * * * * * * * //
+
+namespace Foam
+{
+    defineTypeNameAndDebug(residualControl, 0);
+}
+
+
+// * * * * * * * * * * * * Protected Member Functions  * * * * * * * * * * * //
+
+bool Foam::residualControl::checkCriteria(const bool output) const
+{
+    bool achieved = true;
+    const fvMesh& mesh = static_cast<const fvMesh&>(obr_);
+    const dictionary& solverDict = mesh.solverPerformanceDict();
+    forAll(maxResiduals_, i)
+    {
+        const word& variableName = maxResiduals_[i].first();
+        if (solverDict.found(variableName))
+        {
+            const scalar maxResidual = maxResiduals_[i].second();
+
+            const lduMatrix::solverPerformance
+                sp(solverDict.lookup(variableName));
+
+            const scalar eqnResidual = sp.initialResidual();
+
+            achieved = achieved && (eqnResidual < maxResidual);
+
+            if (output)
+            {
+                Info<< "    " << variableName
+                    << ": requested max residual = " << maxResidual
+                    << ", eqn residual = " << eqnResidual << nl;
+            }
+        }
+    }
+
+    return achieved;
+}
+
+
+// * * * * * * * * * * * * * * * * Constructors  * * * * * * * * * * * * * * //
+
+Foam::residualControl::residualControl
+(
+    const word& name,
+    const objectRegistry& obr,
+    const dictionary& dict,
+    const bool
+)
+:
+    name_(name),
+    obr_(obr),
+    active_(true),
+    maxResiduals_(),
+    criteriaSatisfied_(false)
+{
+    // Only active if a fvMesh is available
+    if (isA<fvMesh>(obr_))
+    {
+        read(dict);
+    }
+    else
+    {
+        active_ = false;
+        WarningIn
+        (
+            "residualControl::residualControl"
+            "("
+                "const word&, "
+                "const objectRegistry&, "
+                "const dictionary&, "
+                "const bool"
+            ")"
+        )   << "No fvMesh available, deactivating."
+            << nl << endl;
+    }
+}
+
+
+// * * * * * * * * * * * * * * * * Destructor  * * * * * * * * * * * * * * * //
+
+Foam::residualControl::~residualControl()
+{}
+
+
+// * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
+
+void Foam::residualControl::read(const dictionary& dict)
+{
+    if (active_)
+    {
+        dict.lookup("maxResiduals") >> maxResiduals_;
+    }
+}
+
+
+void Foam::residualControl::execute()
+{
+    if (active_)
+    {
+        criteriaSatisfied_ = checkCriteria(false);
+
+        if (criteriaSatisfied_)
+        {
+            Info<< "Convergence criteria satisfied - finalising run" << nl
+                << endl;
+
+            checkCriteria(true);
+
+            Info<< endl;
+
+            const fvMesh& mesh = static_cast<const fvMesh&>(obr_);
+            Time& time = const_cast<Time&>(mesh.time());
+            time.writeAndEnd();
+        }
+    }
+}
+
+
+void Foam::residualControl::end()
+{
+    if (active_)
+    {
+        if (criteriaSatisfied_)
+        {
+            Info<< "Residual control criteria satisfied" << nl;
+        }
+        else
+        {
+            Info<< "Residual control criteria not satisfied" << nl;
+        }
+    }
+}
+
+
+void Foam::residualControl::write()
+{
+    // do nothing
+}
+
+
+// ************************************************************************* //

src/postProcessing/functionObjects/residualControl/residualControl.H

@@ -0,0 +1,152 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2010-2010 OpenCFD Ltd.
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM 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.
+
+    OpenFOAM 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 OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+Class
+    Foam::residualControl
+
+Description
+    Function object that allows users to set target convergence criteria, and
+    stop the run if the conditions are satisfied.
+
+SourceFiles
+    residualControl.C
+    IOresidualControl.H
+
+\*---------------------------------------------------------------------------*/
+
+#ifndef residualControl_H
+#define residualControl_H
+
+#include "pointFieldFwd.H"
+#include "Tuple2.H"
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+namespace Foam
+{
+
+// Forward declaration of classes
+class objectRegistry;
+class dictionary;
+class mapPolyMesh;
+
+/*---------------------------------------------------------------------------*\
+                       Class residualControl Declaration
+\*---------------------------------------------------------------------------*/
+
+class residualControl
+{
+protected:
+
+    // Private data
+
+        //- Name of this object
+        word name_;
+
+        //- Reference to object registry
+        const objectRegistry& obr_;
+
+        //- On/off switch - on if obr_ is an fvMesh object
+        bool active_;
+
+        //- List of variable name vs max residual
+        List<Tuple2<word, scalar> > maxResiduals_;
+
+        //- Flag to indicate whether convergence criteria have been met
+        bool criteriaSatisfied_;
+
+
+    // Protected Member Functions
+
+        //- Perform residual control checks
+        bool checkCriteria(const bool output) const;
+
+        //- Disallow default bitwise copy construct
+        residualControl(const residualControl&);
+
+        //- Disallow default bitwise assignment
+        void operator=(const residualControl&);
+
+
+public:
+
+    //- Runtime type information
+    TypeName("residualControl");
+
+
+    // Constructors
+
+        //- Construct for given objectRegistry and dictionary.
+        //  Allow the possibility to load fields from files
+        residualControl
+        (
+            const word& name,
+            const objectRegistry& obr,
+            const dictionary& dict,
+            const bool loadFromFilesUnused = false
+        );
+
+
+    //- Destructor
+    virtual ~residualControl();
+
+
+    // Member Functions
+
+        //- Return name of the system call set
+        virtual const word& name() const
+        {
+            return name_;
+        }
+
+        //- Read the system calls
+        virtual void read(const dictionary&);
+
+        //- Execute the "executeCalls" at each time-step
+        virtual void execute();
+
+        //- Execute the "endCalls" at the final time-loop
+        virtual void end();
+
+        //- Write, execute the "writeCalls"
+        virtual void write();
+
+        //- Update for changes of mesh
+        virtual void updateMesh(const mapPolyMesh&)
+        {}
+
+        //- Update for changes of mesh
+        virtual void movePoints(const pointField&)
+        {}
+};
+
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+} // End namespace Foam
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+#endif
+
+// ************************************************************************* //

src/postProcessing/functionObjects/residualControl/residualControlFunctionObject.C

@@ -0,0 +1,42 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2010-2010 OpenCFD Ltd.
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM 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.
+
+    OpenFOAM 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 OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+\*---------------------------------------------------------------------------*/
+
+#include "residualControlFunctionObject.H"
+
+// * * * * * * * * * * * * * * Static Data Members * * * * * * * * * * * * * //
+
+namespace Foam
+{
+    defineNamedTemplateTypeNameAndDebug(residualControlFunctionObject, 0);
+
+    addToRunTimeSelectionTable
+    (
+        functionObject,
+        residualControlFunctionObject,
+        dictionary
+    );
+}
+
+// ************************************************************************* //

src/postProcessing/functionObjects/residualControl/residualControlFunctionObject.H

@@ -0,0 +1,54 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2010-2010 OpenCFD Ltd.
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM 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.
+
+    OpenFOAM 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 OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+Typedef
+    Foam::residualControlFunctionObject
+
+Description
+    FunctionObject wrapper around residualControl to allow them to be created
+    via the functions entry within controlDict.
+
+SourceFiles
+    residualControlFunctionObject.C
+
+\*---------------------------------------------------------------------------*/
+
+#ifndef residualControlFunctionObject_H
+#define residualControlFunctionObject_H
+
+#include "residualControl.H"
+#include "OutputFilterFunctionObject.H"
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+namespace Foam
+{
+    typedef OutputFilterFunctionObject<residualControl>
+        residualControlFunctionObject;
+}
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+#endif
+
+// ************************************************************************* //