ENH: runTimeControl - enable resetting the trigger to an earlier instant

The runTimeControl function object can activate further function objects using
triggers. Previously the trigger index could only advance; this change set
allows users to set smaller values to enable function object recycling, e.g.

Repeat for N cycles:
1. average the pressure at a point in space
2. when the average stabilises, run for a further 100 iterations
3. set a new patch inlet velocity
  - back to (1)

- Removes old default behaviour that only permitted an increase in the
  trigger level. This type of 'ratcheting' mechanism (if required) is
  now the responsibility of the derived function object.

src/OpenFOAM/db/functionObjects/functionObjectProperties/functionObjectProperties.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2021 OpenCFD Ltd.
+    Copyright (C) 2021-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -96,13 +96,10 @@ Foam::label Foam::functionObjects::properties::getTrigger() const
 
 bool Foam::functionObjects::properties::setTrigger
 (
-    const label triggeri,
+    const label triggeri
-    bool increaseOnly
 )
 {
-    const label currTriggeri = getTrigger();
+    if (triggeri != getTrigger())
-
-    if (increaseOnly ? (triggeri > currTriggeri) : (triggeri != currTriggeri))
     {
         set("triggerIndex", triggeri);
         return true;

src/OpenFOAM/db/functionObjects/functionObjectProperties/functionObjectProperties.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2021 OpenCFD Ltd.
+    Copyright (C) 2021-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -123,14 +123,9 @@ public:
             //- Get the current trigger index
             label getTrigger() const;
 
-            //- Set the trigger index. Normally only if greater than current
+            //- Set new trigger index.
-            //
-            //  \param triggeri the new trigger index
-            //  \param increaseOnly (default) only change if new index
-            //      is greater than the current index.
-            //
             //  \return True if the index changed
-            bool setTrigger(const label triggeri, bool increaseOnly = true);
+            bool setTrigger(const label triggeri);
 
             //- Set dictionary from named object, return true if set
             bool getObjectDict

src/OpenFOAM/db/functionObjects/stateFunctionObject/stateFunctionObject.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015 OpenFOAM Foundation
-    Copyright (C) 2015-2021 OpenCFD Ltd.
+    Copyright (C) 2015-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -88,11 +88,10 @@ Foam::label Foam::functionObjects::stateFunctionObject::getTrigger() const
 
 bool Foam::functionObjects::stateFunctionObject::setTrigger
 (
-    const label triggeri,
+    const label triggeri
-    bool increaseOnly
 )
 {
-    return stateDict().setTrigger(triggeri, increaseOnly);
+    return stateDict().setTrigger(triggeri);
 }
 
 

src/OpenFOAM/db/functionObjects/stateFunctionObject/stateFunctionObject.H

@@ -124,14 +124,9 @@ public:
             //- Get the current trigger index
             label getTrigger() const;
 
-            //- Set the trigger index. Normally only if greater than current
+            //- Set new trigger index.
-            //
-            //  \param triggeri the new trigger index
-            //  \param increaseOnly (default) only change if new index
-            //      is greater than the current index.
-            //
             //  \return True if the index changed
-            bool setTrigger(const label triggeri, bool increaseOnly = true);
+            bool setTrigger(const label triggeri);
 
             //- Set dictionary, return true if set
             bool getDict

src/OpenFOAM/db/functionObjects/timeControl/timeControlFunctionObject.C

@@ -64,11 +64,10 @@ void Foam::functionObjects::timeControl::readControls()
         timeEnd_ = time_.userTimeToTime(timeEnd_);
     }
 
-    if (dict_.readIfPresent("triggerStart", triggerStart_))
+    controlMode_ =
-    {
+        controlModeNames_.getOrDefault("controlMode", dict_, controlMode::TIME);
+    dict_.readIfPresent("triggerStart", triggerStart_);
     dict_.readIfPresent("triggerEnd", triggerEnd_);
-        controlMode_ = controlModeNames_.get("controlMode", dict_);
-    }
 
     deltaTCoeff_ = GREAT;
     if (dict_.readIfPresent("deltaTCoeff", deltaTCoeff_))
@@ -97,6 +96,18 @@ bool Foam::functionObjects::timeControl::active() const
 
     bool inTrigger = triggeri >= triggerStart_ && triggeri <= triggerEnd_;
 
+    DebugInFunction
+        << name() << " mode:" << controlModeNames_[controlMode_] << nl
+        << " - time:" << time_.value()
+        << " timeStart:" << timeStart_
+        << " timeEnd:" << timeEnd_
+        << " inTime:" << inTime << nl
+        << " - triggeri:" << triggeri
+        << " triggerStart:" << triggerStart_
+        << " triggerEnd:" << triggerEnd_
+        << " inTrigger:" << inTrigger
+        << endl;
+
     switch (controlMode_)
     {
         case controlMode::TIME:
@@ -454,7 +465,7 @@ Foam::functionObjects::timeControl::timeControl
     controlMode_(controlMode::TIME),
     timeStart_(-VGREAT),
     timeEnd_(VGREAT),
-    triggerStart_(labelMax),
+    triggerStart_(labelMin),
     triggerEnd_(labelMax),
     nStepsToStartTimeChange_(labelMax),
     executeControl_(runTime, dict, "execute"),

src/functionObjects/utilities/Make/files

@@ -22,11 +22,11 @@ timeInfo/timeInfo.C
 runTimeControl/runTimeControl.C
 runTimeControl/runTimeCondition/runTimeCondition/runTimeCondition.C
 runTimeControl/runTimeCondition/runTimeCondition/runTimeConditionNew.C
+runTimeControl/runTimeCondition/averageCondition/averageCondition.C
 runTimeControl/runTimeCondition/equationMaxIterCondition/equationMaxIterCondition.C
 runTimeControl/runTimeCondition/equationInitialResidualCondition/equationInitialResidualCondition.C
 runTimeControl/runTimeCondition/maxDurationCondition/maxDurationCondition.C
 runTimeControl/runTimeCondition/minMaxCondition/minMaxCondition.C
-runTimeControl/runTimeCondition/averageCondition/averageCondition.C
 runTimeControl/runTimeCondition/minTimeStepCondition/minTimeStepCondition.C
 runTimeControl/runTimeCondition/noneCondition/noneCondition.C
 

src/functionObjects/utilities/runTimeControl/runTimeCondition/averageCondition/averageCondition.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015 OpenFOAM Foundation
-    Copyright (C) 2015-2020 OpenCFD Ltd.
+    Copyright (C) 2015-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -83,17 +83,18 @@ Foam::functionObjects::runTimeControls::averageCondition::averageCondition
     iter_(-1)
 {
     dictionary& conditionDict = this->conditionDict();
+    conditionDict.readIfPresent("iter", iter_);
 
+    if (resetOnRestart_)
+    {
+        reset();
+    }
+    else
+    {
         forAll(fieldNames_, fieldi)
         {
             const word& fieldName = fieldNames_[fieldi];
 
-        if (resetOnRestart_)
-        {
-            conditionDict.set(fieldName, dictionary());
-        }
-        else
-        {
             if (conditionDict.found(fieldName))
             {
                 const dictionary& valueDict = conditionDict.subDict(fieldName);
@@ -105,8 +106,6 @@ Foam::functionObjects::runTimeControls::averageCondition::averageCondition
             }
         }
     }
-
-    conditionDict.readIfPresent("iter", iter_);
 }
 
 
@@ -194,4 +193,21 @@ void Foam::functionObjects::runTimeControls::averageCondition::write()
 }
 
 
+void Foam::functionObjects::runTimeControls::averageCondition::reset()
+{
+    dictionary& conditionDict = this->conditionDict();
+
+    forAll(fieldNames_, fieldi)
+    {
+        const word& fieldName = fieldNames_[fieldi];
+
+        conditionDict.set(fieldName, dictionary());
+        totalTime_[fieldi] = 0;
+    }
+
+    iter_ = -1;
+    conditionDict.set("iter", iter_);
+}
+
+
 // ************************************************************************* //

src/functionObjects/utilities/runTimeControl/runTimeCondition/averageCondition/averageCondition.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015 OpenFOAM Foundation
-    Copyright (C) 2016-2018 OpenCFD Ltd.
+    Copyright (C) 2016-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -77,7 +77,7 @@ public:
 
 protected:
 
-    // Protected data
+    // Protected Data
 
         //- Name of function object to retrieve data from
         word functionObjectName_;
@@ -143,6 +143,9 @@ public:
 
         //- Write
         virtual void write();
+
+        //- Reset
+        virtual void reset();
 };
 
 

src/functionObjects/utilities/runTimeControl/runTimeCondition/equationInitialResidualCondition/equationInitialResidualCondition.C

@@ -230,4 +230,11 @@ equationInitialResidualCondition::write()
 }
 
 
+void Foam::functionObjects::runTimeControls::
+equationInitialResidualCondition::reset()
+{
+    // do nothing
+}
+
+
 // ************************************************************************* //

src/functionObjects/utilities/runTimeControl/runTimeCondition/equationInitialResidualCondition/equationInitialResidualCondition.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015 OpenFOAM Foundation
-    Copyright (C) 2016-2019 OpenCFD Ltd.
+    Copyright (C) 2016-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -130,6 +130,9 @@ public:
 
         //- Write
         virtual void write();
+
+        //- Reset
+        virtual void reset();
 };
 
 

src/functionObjects/utilities/runTimeControl/runTimeCondition/equationMaxIterCondition/equationMaxIterCondition.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015 OpenFOAM Foundation
-    Copyright (C) 2015-2020 OpenCFD Ltd.
+    Copyright (C) 2015-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -168,4 +168,11 @@ void Foam::functionObjects::runTimeControls::equationMaxIterCondition::write()
 }
 
 
+
+void Foam::functionObjects::runTimeControls::equationMaxIterCondition::reset()
+{
+    // do nothing
+}
+
+
 // ************************************************************************* //

src/functionObjects/utilities/runTimeControl/runTimeCondition/equationMaxIterCondition/equationMaxIterCondition.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015 OpenFOAM Foundation
-    Copyright (C) 2016 OpenCFD Ltd.
+    Copyright (C) 2016-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -97,6 +97,9 @@ public:
 
         //- Write
         virtual void write();
+
+        //- Reset
+        virtual void reset();
 };
 
 

src/functionObjects/utilities/runTimeControl/runTimeCondition/maxDurationCondition/maxDurationCondition.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018-2020 OpenCFD Ltd.
+    Copyright (C) 2018-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -110,4 +110,10 @@ void Foam::functionObjects::runTimeControls::maxDurationCondition::write()
 }
 
 
+void Foam::functionObjects::runTimeControls::maxDurationCondition::reset()
+{
+    initialised_ = false;
+}
+
+
 // ************************************************************************* //

src/functionObjects/utilities/runTimeControl/runTimeCondition/maxDurationCondition/maxDurationCondition.H

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2018 OpenCFD Ltd.
+    Copyright (C) 2018-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -99,6 +99,9 @@ public:
 
         //- Write
         virtual void write();
+
+        //- Reset
+        virtual void reset();
 };
 
 

src/functionObjects/utilities/runTimeControl/runTimeCondition/minMaxCondition/minMaxCondition.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015 OpenFOAM Foundation
-    Copyright (C) 2015-2016 OpenCFD Ltd.
+    Copyright (C) 2015-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -166,4 +166,10 @@ void Foam::functionObjects::runTimeControls::minMaxCondition::write()
 }
 
 
+void Foam::functionObjects::runTimeControls::minMaxCondition::reset()
+{
+    // do nothing
+}
+
+
 // ************************************************************************* //

src/functionObjects/utilities/runTimeControl/runTimeCondition/minMaxCondition/minMaxCondition.H

@@ -6,6 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015 OpenFOAM Foundation
+    Copyright (C) 2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -124,6 +125,9 @@ public:
 
         //- Write
         virtual void write();
+
+        //- Reset
+        virtual void reset();
 };
 
 

src/functionObjects/utilities/runTimeControl/runTimeCondition/minTimeStepCondition/minTimeStepCondition.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015 OpenFOAM Foundation
-    Copyright (C) 2019 OpenCFD Ltd.
+    Copyright (C) 2019-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -94,4 +94,10 @@ void Foam::functionObjects::runTimeControls::minTimeStepCondition::write()
 }
 
 
+void Foam::functionObjects::runTimeControls::minTimeStepCondition::reset()
+{
+    // do nothing
+}
+
+
 // ************************************************************************* //

src/functionObjects/utilities/runTimeControl/runTimeCondition/minTimeStepCondition/minTimeStepCondition.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015 OpenFOAM Foundation
-    Copyright (C) 2016 OpenCFD Ltd.
+    Copyright (C) 2016-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -91,6 +91,9 @@ public:
 
         //- Write
         virtual void write();
+
+        //- Reset
+        virtual void reset();
 };
 
 

src/functionObjects/utilities/runTimeControl/runTimeCondition/runTimeCondition/runTimeCondition.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015 OpenFOAM Foundation
-    Copyright (C) 2016 OpenCFD Ltd.
+    Copyright (C) 2016-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -162,6 +162,9 @@ public:
 
         //- Write
         virtual void write() = 0;
+
+        //- Reset
+        virtual void reset() = 0;
 };
 
 

src/functionObjects/utilities/runTimeControl/runTimeControl.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015 OpenFOAM Foundation
-    Copyright (C) 2015-2021 OpenCFD Ltd.
+    Copyright (C) 2015-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -74,7 +74,8 @@ Foam::functionObjects::runTimeControls::runTimeControl::runTimeControl
     writeStepI_(0),
     satisfiedAction_(satisfiedAction::END),
     triggerIndex_(labelMin),
-    active_(getObjectProperty(name, "active", true))
+    active_(getProperty("active", true)),
+    canRestart_(getProperty("canRestart", false))
 {
     read(dict);
 }
@@ -177,6 +178,12 @@ bool Foam::functionObjects::runTimeControls::runTimeControl::read
 
 bool Foam::functionObjects::runTimeControls::runTimeControl::execute()
 {
+    if (canRestart_)
+    {
+        active_ = true;
+        canRestart_ = false;
+    }
+
     if (!active_)
     {
         return true;
@@ -199,7 +206,7 @@ bool Foam::functionObjects::runTimeControls::runTimeControl::execute()
         {
             bool conditionSatisfied = condition.apply();
 
-            label groupi = condition.groupID();
+            const label groupi = condition.groupID();
 
             auto conditionIter = groupMap_.cfind(groupi);
 
@@ -271,14 +278,10 @@ bool Foam::functionObjects::runTimeControls::runTimeControl::execute()
 
                     if (nWriteStep_ != 0)
                     {
-                        Info<< " - final step" << nl;
+                        Info<< " - final step";
-                    }
-                    else
-                    {
-                        Info<< nl;
                     }
 
-                    Info<< endl;
+                    Info<< nl << endl;
                     active_ = false;
 
                     // Write any registered objects and set the end-time
@@ -299,11 +302,25 @@ bool Foam::functionObjects::runTimeControls::runTimeControl::execute()
             case satisfiedAction::SET_TRIGGER:
             {
                 Info<< "    Setting trigger " << triggerIndex_ << nl;
+
                 setTrigger(triggerIndex_);
 
                 // Deactivate the model
                 active_ = false;
                 setProperty("active", active_);
+
+                // Can be restarted
+                canRestart_ = true;
+                setProperty("canRestart", canRestart_);
+
+                // Reset all conditions in case the control is recycled/trigger
+                // index is set to a smaller value
+                forAll(conditions_, conditioni)
+                {
+                    runTimeCondition& condition = conditions_[conditioni];
+                    condition.reset();
+                }
+
                 break;
             }
         }

src/functionObjects/utilities/runTimeControl/runTimeControl.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2015-2016 OpenFOAM Foundation
-    Copyright (C) 2016-2021 OpenCFD Ltd.
+    Copyright (C) 2016-2022 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -111,6 +111,11 @@ private:
         //  trigger has been set
         bool active_;
 
+        //- Can be restarted flag
+        //  Used in the trigger case after the trigger has been set to allow
+        //  this object to be restarted/reset the active flag
+        bool canRestart_;
+
 
     // Private Member Functions