ENH: update handling of "writeTime" in timeControl class

- handle zero or negative values as being identical to 1.
  As per timeStep control and what the comments suggested.

- drop old outputTime enumeration, since this is covered by the
  writeTime enumeration and a corresponding Enum name.

- support construction of a "pass-through" control object that always
  executes and add some method to test for these conditions and be able
  to output some meaning full information.
  Eg,

     if (ctrl.execute())
     {
         if (!ctrl.always())
         {
             Info<< "Sampling executed based on " << ctrl.type() << nl;
         }
         ...
     }

     To produce "Sampling executed based on runTime"

src/OpenFOAM/db/functionObjects/functionObject/functionObject.H

@@ -62,30 +62,31 @@ Description
 
     Where:
     \table
-        Property | Description                           | Required | Default
-        type     | Type of function object               | yes      |
-        libs     | Libraries containing implementation   | yes      |
-        region   | Name of region for multi-region cases | no       |
-        enabled  | On/off switch                         | no       | yes
-        log      | Log information to standard output    | no       | yes
-        timeStart| Start time                            | no       |
-        timeEnd  | End time                              | no       |
-        executeControl  | See time controls below        | no       | timeStep
-        executeInterval | Steps between each execute phase | no     |
-        writeControl    | See time controls below        | no       | timeStep
-        writeInterval   | Steps between each write phase | no       |
+        Property | Description                              | Required | Default
+        type     | Type of function object                  | yes |
+        libs     | Libraries containing implementation      | yes |
+        region   | Name of region for multi-region cases    | no  |
+        enabled  | On/off switch                            | no  | yes
+        log      | Log information to standard output       | no  | yes
+        timeStart| Start time                               | no  |
+        timeEnd  | End time                                 | no  |
+        executeControl  | See time controls below           | no  | timeStep
+        executeInterval | Steps/time between execute phases | no  | 1
+        writeControl    | See time controls below           | no  | timeStep
+        writeInterval   | Steps/time between write phases   | no  | 1
     \endtable
 
     Time controls:
     \table
         Option            | Description
-        timeStep          | Execute/write every 'Interval' time-steps
-        writeTime         | Execute/write every 'Interval' output times
-        adjustableRunTime | Execute/write every 'Interval' run time period
-        runTime           | Execute/write every 'Interval' run time period
-        clockTime         | Execute/write every 'Interval' clock time period
-        cpuTime           | Execute/write every 'Interval' CPU time period
-        none              | Execute/write disabled
+        none              | Trigger is disabled
+        timeStep          | Trigger every 'Interval' time-steps
+        writeTime         | Trigger every 'Interval' output times
+        runTime           | Trigger every 'Interval' run time period
+        adjustableRunTime | Currently identical to "runTime"
+        clockTime         | Trigger every 'Interval' clock time period
+        cpuTime           | Trigger every 'Interval' CPU time period
+        onEnd             | Trigger on end of run
     \endtable
 
     The sub-dictionary name \c \<functionObjectName\> is chosen by the user, and

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

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2016 OpenFOAM Foundation
-    Copyright (C) 2016 OpenCFD Ltd.
+    Copyright (C) 2016-2019 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -35,18 +35,19 @@ const Foam::Enum
 <
     Foam::timeControl::timeControls
 >
-Foam::timeControl::timeControlNames_
+Foam::timeControl::controlNames_
 ({
+    { timeControl::ocNone, "none" },
+    { timeControl::ocAlways, "always" },
     { timeControl::ocTimeStep, "timeStep" },
     { timeControl::ocWriteTime, "writeTime" },
-    { timeControl::ocOutputTime, "outputTime" },
+    { timeControl::ocWriteTime, "outputTime" },
+    { timeControl::ocRunTime, "runTime" },
     { timeControl::ocAdjustableRunTime, "adjustable" },
     { timeControl::ocAdjustableRunTime, "adjustableRunTime" },
-    { timeControl::ocRunTime, "runTime" },
     { timeControl::ocClockTime, "clockTime" },
     { timeControl::ocCpuTime, "cpuTime" },
     { timeControl::ocOnEnd, "onEnd" },
-    { timeControl::ocNone, "none" },
 });
 
 
@@ -54,17 +55,27 @@ Foam::timeControl::timeControlNames_
 
 Foam::timeControl::timeControl
 (
-    const Time& t,
-    const dictionary& dict,
+    const Time& runTime,
     const word& prefix
 )
 :
-    time_(t),
+    time_(runTime),
     prefix_(prefix),
-    timeControl_(ocTimeStep),
+    timeControl_(ocAlways),
     intervalSteps_(0),
     interval_(-1),
     executionIndex_(0)
+{}
+
+
+Foam::timeControl::timeControl
+(
+    const Time& runTime,
+    const dictionary& dict,
+    const word& prefix
+)
+:
+    timeControl(runTime, prefix)
 {
     read(dict);
 }
@@ -97,27 +108,21 @@ void Foam::timeControl::read(const dictionary& dict)
             << "Using deprecated 'outputControl'" << nl
             << "    Please use 'writeControl' with 'writeInterval'"
             << endl;
+        error::warnAboutAge("outputControl", 1606);
 
         // Change to the old names for this option
         controlName = "outputControl";
         intervalName = "outputInterval";
     }
 
-    timeControl_ =
-        timeControlNames_.lookupOrDefault(controlName, dict, ocTimeStep);
+    timeControl_ = controlNames_.getOrDefault(controlName, dict, ocTimeStep);
 
     switch (timeControl_)
     {
         case ocTimeStep:
-        {
-            intervalSteps_ = dict.lookupOrDefault<label>(intervalName, 0);
-            break;
-        }
-
         case ocWriteTime:
-        case ocOutputTime:
         {
-            intervalSteps_ = dict.lookupOrDefault<label>(intervalName, 1);
+            intervalSteps_ = dict.getOrDefault<label>(intervalName, 0);
             break;
         }
 
@@ -131,7 +136,6 @@ void Foam::timeControl::read(const dictionary& dict)
             break;
         }
 
-        case ocOnEnd:
         default:
         {
             break;
@@ -144,6 +148,18 @@ bool Foam::timeControl::execute()
 {
     switch (timeControl_)
     {
+        case ocNone:
+        {
+            return false;
+            break;
+        }
+
+        case ocAlways:
+        {
+            return true;
+            break;
+        }
+
         case ocTimeStep:
         {
             return
@@ -155,12 +171,15 @@ bool Foam::timeControl::execute()
         }
 
         case ocWriteTime:
-        case ocOutputTime:
         {
             if (time_.writeTime())
             {
-                executionIndex_++;
-                return !(executionIndex_ % intervalSteps_);
+                ++executionIndex_;
+                return
+                (
+                    (intervalSteps_ <= 1)
+                 || !(executionIndex_ % intervalSteps_)
+                );
             }
             break;
         }
@@ -222,16 +241,11 @@ bool Foam::timeControl::execute()
             break;
         }
 
-        case ocNone:
-        {
-            return false;
-        }
-
         default:
         {
             FatalErrorInFunction
                 << "Undefined time control: "
-                << timeControlNames_[timeControl_] << nl
+                << controlNames_[timeControl_] << nl
                 << abort(FatalError);
             break;
         }

src/OpenFOAM/db/functionObjects/timeControl/timeControl.H

@@ -6,6 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2016 OpenFOAM Foundation
+    Copyright (C) 2019 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,7 +29,16 @@ Class
 
 Description
     General time dependent execution controller.
-    The default to execute every time-step.
+    The execution parameters are given by the "Control" and (optionally)
+    the "Interval", with the default being to execute every time-step.
+
+    For example, an "execute" control every tenth write time:
+    \verbatim
+        executeControl  writeTime;
+        executeInterval 10;
+    \endverbatim
+
+    See Foam::functionObject for a list of known selection types.
 
 SourceFiles
     timeControl.C
@@ -56,39 +66,40 @@ public:
     //- The time control options
     enum timeControls
     {
-        ocTimeStep,           //!< execution is coupled to the time-step
-        ocWriteTime,          //!< execution is coupled to the write-time
-        ocOutputTime,         //!< execution is coupled to the output-time
-        ocAdjustableRunTime,  //!< Adjust time step for execution
-        ocRunTime,            //!< run time for execution
-        ocClockTime,          //!< clock time for execution
-        ocCpuTime,            //!< CPU time for execution
-        ocOnEnd,              //!< on end of run
-        ocNone                //!< no execution
+        ocNone = 0,           //!< No execution
+        ocAlways,             //!< Always execute
+        ocTimeStep,           //!< Execution coupled to time-step (default)
+        ocWriteTime,          //!< Execution coupled to write-time
+        ocRunTime,            //!< Use run-time for execution
+        ocAdjustableRunTime,  //!< Currently identical to "runTime"
+        ocClockTime,          //!< Use clock time for execution
+        ocCpuTime,            //!< Use CPU time for execution
+        ocOnEnd               //!< Execute on end of run
     };
 
 
 private:
 
-    // Private data
+        //- The selection names for timeControls enumerations
+        static const Enum<timeControls> controlNames_;
+
+
+    // Private Data
 
         //- Time object
         const Time& time_;
 
-        //- Prefix
+        //- The prefix for the control name (eg, "write", "execute", ...)
         const word prefix_;
 
-        //- String representation of timeControls enums
-        static const Enum<timeControls> timeControlNames_;
-
         //- Type of time control
         timeControls timeControl_;
 
-        //- Execution interval steps for timeStep mode
-        //  a value <= 1 means execute at every time step
+        //- Execution interval steps (timeStep | writeTime).
+        //  A value <= 1 means execute at every time-step or writeTime.
         label intervalSteps_;
 
-        //- Execution interval
+        //- Execution interval (clockTime | runTime | cpuTime | adjustable)
         scalar interval_;
 
         //- Index of previous execution
@@ -108,11 +119,17 @@ public:
 
     // Constructors
 
-        //- Construct from Time object and dictionary
+        //- Construct a control object that executes each time-step.
+        //  For places where a time control object is required, but should
+        //  not actually intervene.
+        explicit timeControl(const Time& runTime, const word& prefix = "");
+
+        //- Construct from Time object, dictionary and the prefix for the
+        //- control name.
         timeControl
         (
-            const Time&,
-            const dictionary&,
+            const Time& runTime,
+            const dictionary& dict,
             const word& prefix
         );
 
@@ -123,22 +140,31 @@ public:
 
     // Member Functions
 
-        //- Helper function to identify if a timeControl object is present
-        //  in the dictionary
+        //- Identify if a timeControl object is present in the dictionary
+        //  Matches prefix + "Control"
         static bool entriesPresent(const dictionary& dict, const word& prefix);
 
         //- Read from dictionary
-        void read(const dictionary&);
+        void read(const dictionary& dict);
 
-        //- Return Time
+        //- Return the Time
         inline const Time& time() const;
 
-        //- Flag to indicate whether to execute
-        bool execute();
+        //- Return the name (prefix)
+        inline const word& name() const;
+
+        //- Return the named control enumeration as its 'type'
+        inline const word& type() const;
 
-        //- Return control
+        //- Return the control enumeration
         inline timeControls control() const;
 
+        //- Return true if the control will always execute - ie, no intervention
+        inline bool always() const;
+
+        //- Flag to indicate whether to execute
+        bool execute();
+
         //- Return interval
         inline scalar interval() const;
 

src/OpenFOAM/db/functionObjects/timeControl/timeControlI.H

@@ -6,6 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2016 OpenFOAM Foundation
+    Copyright (C) 2019 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -33,12 +34,34 @@ inline const Foam::Time& Foam::timeControl::time() const
 }
 
 
+inline const Foam::word& Foam::timeControl::name() const
+{
+    return prefix_;
+}
+
+
+inline const Foam::word& Foam::timeControl::type() const
+{
+    return controlNames_[timeControl_];
+}
+
+
 inline Foam::timeControl::timeControls Foam::timeControl::control() const
 {
     return timeControl_;
 }
 
 
+inline bool Foam::timeControl::always() const
+{
+    return
+    (
+        (timeControls::ocAlways == timeControl_)
+     || (timeControls::ocTimeStep == timeControl_ && intervalSteps_ <= 1)
+    );
+}
+
+
 inline Foam::scalar Foam::timeControl::interval() const
 {
     return interval_;