ENH: add single-time handling to timeSelector

- the timeSelector is often used to select single or multiple times
  (eg, for post-processing). However, there are a few applications
  where only a *single* time should be selected and set.

  These are now covered by this type of use:

      timeSelector::addOptions_singleTime();  // Single-time options
      ...
      // Allow override of time from specified time options, or no-op
      timeSelector::setTimeIfPresent(runTime, args);

   In some cases, if can be desirable to force starting from the
   initial Time=0 when no time options have been specified:

      // Set time from specified time options, or force start from Time=0
      timeSelector::setTimeIfPresent(runTime, args, true);

   These changes make a number of includes redundant:

     * addTimeOptions.H
     * checkConstantOption.H
     * checkTimeOption.H
     * checkTimeOptions.H
     * checkTimeOptionsNoConstant.H

ENH: add time handling to setFields, setAlphaField (#3143)

    Co-authored-by: Johan Roenby <>

STYLE: replace instant("constant") with instant(0, "constant")

- avoids relying on atof parse behaviour returning zero

applications/utilities/mesh/conversion/ccm/foamToCcm/foamToCcm.C

@@ -157,7 +157,7 @@ int main(int argc, char *argv[])
 //     // skip over time=0, unless some other time option has been specified
 //     if
 //     (
-//         !args.found("zeroTime")
+//         !args.found("noZero")
 //      && !args.found("time")
 //      && !args.found("latestTime")
 //      && Times.size() > 2

applications/utilities/mesh/conversion/gmshToFoam/gmshToFoam.C

@@ -1569,7 +1569,7 @@ int main(int argc, char *argv[])
 
     //Get polyMesh to write to constant
 
-    runTime.setTime(instant(runTime.constant()), 0);
+    runTime.setTime(instant(0, runTime.constant()), 0);
 
     repatcher.repatch();
 

applications/utilities/mesh/manipulation/renumberMesh/renumberMesh.C

@@ -803,6 +803,10 @@ CompactListList<label> regionRenumber
 
 int main(int argc, char *argv[])
 {
+    argList::noFunctionObjects();           // Never use function objects
+
+    timeSelector::addOptions_singleTime();  // Single-time options
+
     argList::addNote
     (
         "Renumber mesh cells to reduce the bandwidth. Use the -lib option or"
@@ -863,11 +867,8 @@ int main(int argc, char *argv[])
         "eg, 'reverse true;'"
     );
 
-    argList::noFunctionObjects();  // Never use function objects
-
     #include "addAllRegionOptions.H"
     #include "addOverwriteOption.H"
-    #include "addTimeOptions.H"
 
     // -------------------------
 
@@ -926,14 +927,15 @@ int main(int argc, char *argv[])
     // Get region names
     #include "getAllRegionOptions.H"
 
-    // Get times list
-    instantList Times = runTime.times();
-
-    // Set startTime depending on -time and -latestTime options
-    #include "checkTimeOptions.H"
-
-    runTime.setTime(Times[startTime], startTime);
+    // Set time from specified time options, or force start from Time=0
+    timeSelector::setTimeIfPresent(runTime, args, true);
 
+    // Capture current time information for non-overwrite
+    const Tuple2<instant, label> startTime
+    (
+        instant(runTime.value(), runTime.timeName()),
+        runTime.timeIndex()
+    );
 
     // Start/reset all timings
     timer.resetTime();
@@ -947,7 +949,10 @@ int main(int argc, char *argv[])
     for (fvMesh& mesh : meshes)
     {
         // Reset time in case of multiple meshes and not overwrite
-        runTime.setTime(Times[startTime], startTime);
+        if (!overwrite)
+        {
+            runTime.setTime(startTime.first(), startTime.second());
+        }
 
         const word oldInstance = mesh.pointsInstance();
 

applications/utilities/mesh/manipulation/setsToZones/setsToZones.C

@@ -62,12 +62,13 @@ using namespace Foam;
 
 int main(int argc, char *argv[])
 {
+    timeSelector::addOptions_singleTime();  // Single-time options
+
     argList::addNote
     (
         "Add point/face/cell Zones from similarly named point/face/cell Sets"
     );
 
-    timeSelector::addOptions(true, false);  // constant(true), zero(false)
     argList::addBoolOption
     (
         "noFlipMap",
@@ -75,14 +76,13 @@ int main(int argc, char *argv[])
     );
 
     #include "addRegionOption.H"
-    #include "addTimeOptions.H"
     #include "setRootCase.H"
     #include "createTime.H"
 
     const bool noFlipMap = args.found("noFlipMap");
 
-    // Get times list
-    (void)timeSelector::selectIfPresent(runTime, args);
+    // Allow override of time from specified time options, or no-op
+    timeSelector::setTimeIfPresent(runTime, args);
 
     #include "createNamedPolyMesh.H"
 

applications/utilities/mesh/manipulation/topoSet/topoSet.C

@@ -240,9 +240,9 @@ int main(int argc, char *argv[])
     // Read set construct info from dictionary
     List<namedDictionary> actionEntries(topoSetDict.lookup("actions"));
 
-    forAll(timeDirs, timeI)
+    forAll(timeDirs, timei)
     {
-        runTime.setTime(timeDirs[timeI], timeI);
+        runTime.setTime(timeDirs[timei], timei);
         Info<< "Time = " << runTime.timeName() << endl;
 
         // Optionally re-read mesh

applications/utilities/postProcessing/dataConversion/foamToTetDualMesh/foamToTetDualMesh.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2016 OpenFOAM Foundation
-    Copyright (C) 2023 OpenCFD Ltd.
+    Copyright (C) 2023-2024 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -36,6 +36,7 @@ Description
 \*---------------------------------------------------------------------------*/
 
 #include "argList.H"
+#include "timeSelector.H"
 #include "fvMesh.H"
 #include "volFields.H"
 #include "pointFields.H"
@@ -145,20 +146,22 @@ void ReadAndMapFields
 
 int main(int argc, char *argv[])
 {
+    argList::noFunctionObjects();           // Never use function objects
+
+    timeSelector::addOptions_singleTime();  // Single-time options
+
     argList::addNote
     (
         "Convert polyMesh results to tetDualMesh"
     );
 
     #include "addOverwriteOption.H"
-    #include "addTimeOptions.H"
 
     #include "setRootCase.H"
     #include "createTime.H"
-    // Get times list
-    instantList Times = runTime.times();
-    #include "checkTimeOptions.H"
-    runTime.setTime(Times[startTime], startTime);
+
+    // Set time from specified time options, or force start from Time=0
+    timeSelector::setTimeIfPresent(runTime, args, true);
 
     // Read the mesh
     #include "createNamedMesh.H"

applications/utilities/postProcessing/lumped/lumpedPointMovement/lumpedPointMovement.C

@@ -353,7 +353,7 @@ int main(int argc, char *argv[])
 
     #include "createTime.H"
 
-    runTime.setTime(instant(runTime.constant()), 0);
+    runTime.setTime(instant(0, runTime.constant()), 0);
 
     #include "createNamedMesh.H"
 

applications/utilities/postProcessing/lumped/lumpedPointZones/lumpedPointZones.C

@@ -106,7 +106,7 @@ int main(int argc, char *argv[])
     }
 
 
-    runTime.setTime(instant(runTime.constant()), 0);
+    runTime.setTime(instant(0, runTime.constant()), 0);
 
     #include "createNamedMesh.H"
 

applications/utilities/preProcessing/setAlphaField/setAlphaField.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2016-2017 DHI
-    Copyright (C) 2017-2020 OpenCFD Ltd.
+    Copyright (C) 2017-2024 OpenCFD Ltd.
     Copyright (C) 2017-2020 German Aerospace Center (DLR)
     Copyright (C) 2020 Johan Roenby
 -------------------------------------------------------------------------------
@@ -39,6 +39,7 @@ Description
 \*---------------------------------------------------------------------------*/
 
 #include "fvCFD.H"
+#include "timeSelector.H"
 
 #include "triSurface.H"
 #include "triSurfaceTools.H"
@@ -139,6 +140,10 @@ void setAlpha
 
 int main(int argc, char *argv[])
 {
+    argList::noFunctionObjects();           // Never use function objects
+
+    timeSelector::addOptions_singleTime();  // Single-time options
+
     argList::addNote
     (
         "Uses cutCellIso to create a volume fraction field from an "
@@ -151,9 +156,14 @@ int main(int argc, char *argv[])
         "file",
         "Alternative setAlphaFieldDict dictionary"
     );
+
     #include "addRegionOption.H"
     #include "setRootCase.H"
     #include "createTime.H"
+
+    // Set time from specified time options, or no-op
+    timeSelector::setTimeIfPresent(runTime, args);
+
     #include "createNamedMesh.H"
 
     const word dictName("setAlphaFieldDict");

applications/utilities/preProcessing/setFields/setFields.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2016 OpenFOAM Foundation
-    Copyright (C) 2022-2023 OpenCFD Ltd.
+    Copyright (C) 2022-2024 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -36,6 +36,7 @@ Description
 \*---------------------------------------------------------------------------*/
 
 #include "argList.H"
+#include "timeSelector.H"
 #include "Time.H"
 #include "fvMesh.H"
 #include "faMesh.H"
@@ -656,6 +657,10 @@ struct setAreaField
 
 int main(int argc, char *argv[])
 {
+    argList::noFunctionObjects();           // Never use function objects
+
+    timeSelector::addOptions_singleTime();  // Single-time options
+
     argList::addNote
     (
         "Set values on a selected set of cells/patch-faces via a dictionary"
@@ -670,8 +675,15 @@ int main(int argc, char *argv[])
     );
 
     #include "addRegionOption.H"
+
+    // -------------------------
+
     #include "setRootCase.H"
     #include "createTime.H"
+
+    // Set time from specified time options, or no-op
+    timeSelector::setTimeIfPresent(runTime, args);
+
     #include "createNamedMesh.H"
 
     autoPtr<faMesh> faMeshPtr;